> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/studio/tasks/reference/locale-compare/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# localeCompare

> Use the localeCompare task to compare two strings in the current locale and return a numeric sort-order result.

The `localeCompare` task compares two strings in the current locale and returns a numeric value (negative, zero, or positive) indicating whether the reference string comes before, after, or is the same as the `compareString` in sort order. The locale is based on the language settings of the browser.

## Potential use case

Use this task to sort an array of strings with special characters, or to implement "natural sorting" in which numbers embedded in strings are treated numerically (sorted low to high). The task also provides multiple options to control how certain formatting conventions are handled when sorting.

## Properties

| Input           | Type   | Required | Description                                                                                                                                                                 |
| :-------------- | :----- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `referenceStr`  | String |    Yes   | The reference string to compare.                                                                                                                                            |
| `compareString` | String |    Yes   | The string to compare against `referenceStr`.                                                                                                                               |
| `locales`       | String |    No    | A BCP 47 language tag string, or an array of such tags. If not provided, the default locale is used. Allowed Unicode extension keys are `"co"`, `"kn"`, and `"kf"`.         |
| `options`       | Object |    No    | Options to apply to the sort order. The `options` object may include: `"caseFirst"`, `"ignorePunctuation"`, `"localeMatcher"`, `"numeric"`, `"sensitivity"`, and `"usage"`. |

| Output          | Type   | Description                                                                                                                                                                                                                                                                                                                                                   |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `compareResult` | Number | A number indicating the sort relationship. Returns **-1** (negative) when the reference string appears before `compareString`; **0** if the two strings are equal; **1** (positive) when the reference string appears after `compareString`. Do not rely on exact return values of -1 or 1 — negative and positive values vary between browsers and versions. |

## Example 1

In this example, `referenceStr` is `"Hello World"` and `compareString` is `"héllö wôrld"` (with an acute accent on `é`, a diaeresis on `ö`, and a circumflex on `ô`).

![](/_fern-img/621e50c8af42a107dd7cae93fb1c8819d597463a2d45cb5ba3acef9a03ceeb17.webp)

The `compareResult` is **-1** (negative) because the reference string comes before the comparison string.

![](/_fern-img/ad224887f421c5717791677bc7b98591f2f6d1e433b6229219d8d8a839e9cf4c.webp)

## Example 2

In this example, `referenceStr` is `"8"` and `compareString` is `"30"`.

![](/_fern-img/92b0383a416fb1a24576cdd8daed4ba40aade2c6a3c202d9ee6651c3f8fc5037.webp)

The `compareResult` is **1** (positive) because the string value `"8"` comes after `"30"` in string sort order.

![](/_fern-img/f7f7e9c90f55cc56c2b1361dfa93a611105677fbb10541a963001b017fae1d76.webp)

## Example 3

In this example, `referenceStr` is `"réservé"` (with acute accents) and `compareString` is `"reserve"` (no accents). The `locales` option is set to `"en"` (English), and `options` includes `"sensitivity": "base"` to indicate the strings do not have the same base letters.

![](/_fern-img/d29c32f9359af3f91b99ce7f8b8505a29f2bc07249e6e7d60f81415ca04b5ee4.webp)

The `compareResult` is **0** because the two strings are considered equal under these settings.

![](/_fern-img/07c61a892652ef39615df4cc688286c6b7787f28873a26af30772606ffe64c91.webp)

## Related reading

See the [Intl.Collator constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) on MDN for more information on the `locales` and `options` parameters.

> Use the localeCompare task to compare two strings in the current locale and return a numeric sort-order result.