localeCompare Method (String) (JavaScript)

Determines whether two strings are equivalent in the current locale.

Syntax

stringVar.localeCompare(stringExp[, locales][, options])   

Parameters

stringVar
Required. The first string to compare.

stringExp
Required. The second string to compare.

locales
Optional. An array of locale strings that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used. This parameter must conform to BCP 47 standards; see the Intl.Collator object for details.

options
Optional. An object that contains one or more properties that specify comparison options. see the Intl.Collator object for details.

Remarks

For the comparison strings, you may specify either String objects or string literals.

Starting in Internet Explorer 11, localeCompare uses the Intl.Collator object internally to make comparisons, which adds support for the locales and options parameters. For more information about these parameters, see Intl.Collator and Intl.Collator.compare.

The localeCompare method performs a locale-sensitive string comparison of stringVar and stringExp and returns one of the following results, depending on the sort order of the system default locale:

• -1 if stringVar sorts before stringExp.

• +1 if stringVar sorts after stringExp.

• 0 (zero) if the two strings are equivalent.

Example

The following code shows how to use localeCompare.

var str1 = "def";  
var str2 = "abc"  

document.write(str1.localeCompare(str2) + "<br/>");  

// Output: 1  
var str3 = "ghi";  

document.write(str1.localeCompare(str3)+ "<br/>");  

// Output: -1  
var str4 = "def";  

document.write(str1.localeCompare(str4));  

// Output: 0  

Example

The following code shows how to use localeCompare with the German (Germany) locale.

var str1 = "a";  
var str2 = "b";  

document.write(str1.localeCompare(str2, "de-DE"));  

// Output  
// - 1  

Example

The following example shows how to use localeCompare with the German (Germany) locale and a locale-specific extension that specifies the sort order for German phone books. This example shows locale-specific differences.

var arr = ["ä", "ad", "af", "a"];  

document.write(arr[0].localeCompare(arr[1], "de-DE-u-co-phonebk"));  // Returns 1  
document.write (arr[0].localeCompare(arr[2], "de-DE-u-co-phonebk"));  // Returns -1  
document.write (arr[0].localeCompare(arr[3], "de-DE-u-co-phonebk"));  // Returns 1  

document.write (arr[0].localeCompare(arr[1], "de-DE"));  // Returns -1  
document.write (arr[0].localeCompare(arr[2], "de-DE"));  // Returns -1  
document.write (arr[0].localeCompare(arr[3], "de-DE"));  // Returns 1  

Requirements

Supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards, Internet Explorer 9 standards, Internet Explorer 10 standards, Internet Explorer 11 standards. Also supported Store apps (Windows 8 and Windows Phone 8.1). See Version Information.

locales and options parameters:

Supported in the Internet Explorer 11 standards document mode. Also supported in Store apps (Windows 8.1 and Windows Phone 8.1). See Version Information.
Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards, Internet Explorer 9 standards, Internet Explorer 10 standards. Not supported in Windows 8.

See Also

toLocaleString Method (Object)