JavaScript Reference ยท String
String.prototype.localeCompare()
Reference for JavaScript String.prototype.localeCompare(): compare strings by language rules, sort with accents, ignore case, and sort numbers inside text.
The localeCompare() method compares two strings according to the sorting rules of a language and returns a number that tells you which one comes first. It is the standard way to sort human-readable text.
Comparing with < and > looks at raw code units, so every capital letter sorts before every lowercase letter, and accented letters land after z. localeCompare() follows the dictionary order that readers of a given language expect.
"a".localeCompare("b"); // a negative number
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
referenceStr.localeCompare(compareString) referenceStr.localeCompare(compareString, locales) referenceStr.localeCompare(compareString, locales, options)
| Name | Description |
|---|---|
compareString |
The string to compare with. It is converted to a string. |
locales |
Optional. A BCP 47 language tag such as "de" or "sv", or an array of tags. Without it, the runtime's default locale is used. |
options |
Optional. An object with the same options as Intl.Collator, for example sensitivity, numeric, caseFirst, ignorePunctuation. |
Return value: a negative number if the reference string sorts before compareString, a positive number if it sorts after, and 0 if they are equal under the chosen rules. The size of the number is unspecified, so test with < 0, > 0 or Math.sign(), never with === -1.
Exceptions: a RangeError if locales is not a valid language tag or an option has an invalid value.
Usage notes
- Pass a locale explicitly when the order must be the same for everyone. With the default locale, the same code can sort differently on different machines.
- Sorting:
array.sort((a, b) => a.localeCompare(b))works because the return value is negative, zero or positive. SeeArray.prototype.sort(). sensitivitydecides what counts as a difference:"base"ignores case and accents,"accent"ignores case only,"case"ignores accents only, and"variant"(the default for sorting) tells everything apart.numeric: truecompares digit runs as numbers, sofile2comes beforefile10.- Many comparisons: each call has to set up its rules. When sorting large arrays, create one
Intl.Collatorand pass itscomparemethod tosort(), which is considerably faster. SeeIntl.Collator. - Equal does not mean identical. With a relaxed
sensitivity, two different strings can return0. Do not use it as a general equality test. - Unicode forms: canonically equivalent strings, such as a precomposed
รฉandeplus a combining accent, compare as equal. Seenormalize(). - Environment support: the options and locales available depend on the browser's internationalization data.
Browser support
localeCompare() works everywhere, but the locales and options arguments need internationalization support, which all current browsers include. Exact ordering for less common languages can differ between engines.