The localeCompare[]
method returns a number indicating whether a reference string comes before or after or is the same as the given string in sort order.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone //github.com/mdn/interactive-examples and send us a pull request.
The new locales
and options
arguments let applications specify the language whose sort order should be used and customize the behavior of the function. In older implementations, which ignore the locales
and options
arguments, the locale and sort order used are entirely implementation dependent.
Syntax
referenceStr.localeCompare[compareString[, locales[, options]]]
Parameters
Check the
Browser compatibility section to see which browsers support the locales
and options
arguments, and Check browser support for extended arguments for feature detection.
compareString
The string against which the referring string is comparedlocales
Optional. A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales
argument, see the
Intl page. The following Unicode
extension keys are allowed:
co
Variant collations for certain locales. Possible values include: "big5han"
, "dict"
, "direct"
, "ducet"
, "gb2312"
, "phonebk"
, "phonetic"
, "pinyin"
, "reformed"
, "searchjl"
, "stroke"
, "trad"
, "unihan"
. The "standard"
and "search"
values are ignored; they are replaced by the options
property usage
[see below].kn
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are "true"
and
"false"
. This option can be set through an options
property or through a Unicode extension key; if both are provided, the options
property takes precedence.kf
Whether upper case or lower case should sort first. Possible values are "upper"
, "lower"
, or "false"
[use the locale's default]. This option can be set through an options
property or through a Unicode extension key; if both are provided, the options
property takes precedence.options
Optional. An object with some or all of the following properties:
localeMatcher
The locale matching algorithm to use. Possible values are "lookup"
and "best fit"
; the default is "best fit"
. For information about this option, see the Intl page.usage
Whether the comparison is for sorting or for searching for matching strings. Possible values are "sort"
and "search"
; the default is "sort"
.sensitivity
Which differences in the strings should lead to non-zero result values. Possible values are:
"base"
: Only strings that differ in base letters compare as unequal. Examples:a ≠ b
,a = á
,a = A
."accent"
: Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples:a ≠ b
,a ≠ á
,a = A
."case"
: Only strings that differ in base letters or case compare as unequal. Examples:a ≠ b
,a = á
,a ≠ A
."variant"
: Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other differences may also be taken into consideration. Examples:a ≠ b
,a ≠ á
,a ≠ A
.
The default is "variant"
for usage "sort"
; it's locale dependent for usage "search"
.
ignorePunctuation
Whether punctuation should be ignored. Possible values are true
and false
; the default is false
.numeric
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are true
and false
; the
default is false
. This option can be set through an options
property or through a Unicode extension key; if both are provided, the options
property takes precedence. Implementations are not required to support this property.caseFirst
Whether upper case or lower case should sort first. Possible values are "upper"
, "lower"
, or "false"
[use the locale's default]; the default is "false"
. This option can be set through an options
property or through a Unicode extension key;
if both are provided, the options
property takes precedence. Implementations are not required to support this property.Return value
A negative number if the reference string occurs before the compare string; positive if the reference string occurs after the compare string; 0 if they are equivalent.
Description
Returns an integer indicating whether the referenceStr comes before, after or is equivalent to the compareStr.
- Negative when the referenceStr occurs before compareStr
- Positive when the referenceStr occurs after compareStr
- Returns 0 if they are equivalent
DO NOT rely on exact return values of -1 or 1. Negative and positive integer results vary between browsers [as well as between browser versions] because the W3C specification only mandates negative and positive values. Some browsers may return -2 or 2 or even some other negative or positive value.
Examples
Using localeCompare[]
Sort an array
localeCompare
enables a case-insensitive sort of an array.
Check browser support for extended arguments
The locales
and options
arguments
are not supported in all browsers yet. To check whether an implementation supports them, use the "i" argument [a requirement that illegal language tags are rejected] and look for a RangeError
exception:
Using locales
The results provided by localeCompare[]
vary between languages. In order to get the
sort order of the language used in the user interface of your application, make sure to specify that language [and possibly some fallback languages] using the locales
argument:
Using options
The results provided by localeCompare[]
can be customized using the options
argument:
Numeric sorting
Performance
When comparing large numbers of strings, such as in sorting large arrays, it is better to create an
Intl.Collator
object and use the function provided by its compare
property.
Specifications
ECMAScript 3rd Edition [ECMA-262] | Standard | Initial definition. Implemented in JavaScript 1.2. |
ECMAScript 5.1 [ECMA-262] The definition of 'String.prototype.localeCompare' in that specification. | Standard | |
ECMAScript 2015 [6th Edition, ECMA-262] The definition of 'String.prototype.localeCompare' in that specification. | Standard | |
ECMAScript Latest Draft [ECMA-262] The definition of 'String.prototype.localeCompare' in that specification. | Draft | |
ECMAScript Internationalization API 1.0 [ECMA-402] The definition of 'String.prototype.localeCompare' in that specification. | Standard | locale and option parameter definitions.
|
ECMAScript Internationalization API 2.0 [ECMA-402] The definition of 'String.prototype.localeCompare' in that specification. | Standard | |
ECMAScript Internationalization API 4.0 [ECMA-402] The definition of 'String.prototype.localeCompare' in that specification. | Draft |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out //github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
DesktopMobileServer | ||||||||||||
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js | ||||||||||||
Chrome Full support Yes | Edge Full support 12 | Firefox Full support 1 | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 4 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs Full support Yes |
Chrome Full support 24 | Edge Full support Yes | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android No support No | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
Chrome Full support 24 | Edge Full support Yes | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android No support No | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
Legend
Full support Full support No support No support Compatibility unknown Compatibility unknownSee also
Intl.Collator