Comparing & sorting text

People and JavaScript order text differently

A string is a piece of text, like "apple". JavaScript can compare any two strings. But by default it does not compare them like a dictionary does. It compares the numbers it stores for each piece of the text. These numbers are called UTF-16 code units. You met them in the Unicode & string internals lesson.

Code units are good for exact rules that machines follow. But they often give a strange order for names, titles, product lists, and search boxes. This lesson shows the tools that order text the way people expect.

This lesson builds on three earlier lessons: Comparisons, Sorting & copying safely, and Unicode & string internals. The Internationalization with Intl lesson comes later and goes further. You will still write the same kind of sort function. Only the part that compares two strings changes.

When both sides of < are strings, JavaScript reads them one code unit at a time, from the left. It stops at the first place where they differ. The string with the smaller number there comes first. Array sort() uses the same rule for strings when you don't give it a compare function.

1console.log("a".charCodeAt(0)); // 972console.log("Z".charCodeAt(0)); // 903 4console.log("Zebra" < "apple"); // true

charCodeAt(0) gives the code unit at position 0, which is the first letter. Line 1 prints 97 for small a. Line 2 prints 90 for capital Z. Every plain capital letter has a smaller number than every plain small letter. So line 4 prints true: Zebra comes before apple.

Code-unit order is not a mistake. It is an exact rule for machines, not the rule of any language. It also explains why "10" < "9" is true. The first code units already differ: "1" comes before "9", so JavaScript never looks further.

1const collator = new Intl.Collator("en");2const result = collator.compare("apple", "banana");3 4console.log(result < 0); // true: apple comes before banana5console.log(Math.sign(result)); // -1, but only the sign is guaranteed

A comparator is a compare function: it takes two values, a and b, and tells sort() which one comes first. It returns a number:

• A negative number means a comes first.
• Zero means they count as equal for this rule.
• A positive number means b comes first.

Line 1 makes an Intl.Collator, a tool that compares text with English rules. You'll learn it properly below. Line 2 compares apple with banana and gets a negative number, so line 4 prints true. Line 5 uses Math.sign, which turns any number into -1, 0, or 1. Only the sign of the result is promised. So don't write code that expects exactly -1 or 1.

1const words = ["banana", "apple", "Cherry", "éclair"];Run2const sorted = [...words].sort();3console.log(sorted.join(", "));

1const names = ["Zoe", "Asha", "Mina"];2const sortedNames = [...names].sort((a, b) => a.localeCompare(b, "en"));3 4console.log(names.join(", "));5console.log(sortedNames.join(", "));

[...names] uses the spread syntax. It makes a new array with the same items, called a shallow copy. sort() changes the array it is called on, so here it changes only the copy. Line 2 compares with localeCompare, which the next section explains. Line 4 prints "Zoe, Asha, Mina", the original order. Line 5 prints "Asha, Mina, Zoe", the sorted copy. Do this when another part of the page still needs the original order.

Use the default order for IDs, exact codes that programs send to each other, and other places where you want the exact machine rule. For names and labels that people read, use a comparison that knows the language.

Every string has a localeCompare method. You call it on one string and pass the other one: a.localeCompare(b, locale). A locale is a short code for a language, such as "en" for English or "de" for German.

localeCompare returns the same kind of number as a comparator. Negative means "comes before". Zero means "counts as equal here". Positive means "comes after". So a sort function can return it directly.

1"äpfel".localeCompare("zebra", "de"); // negative2"äpfel".localeCompare("zebra", "sv"); // positive3[...names].sort((a, b) => a.localeCompare(b, "de"));

1const german = "äpfel".localeCompare("zebra", "de");2const swedish = "äpfel".localeCompare("zebra", "sv");3 4console.log(german < 0); // true: German places ä near a5console.log(swedish > 0); // true: Swedish places ä after z

Always pass the locale: for example "en" (English), "de" (German), "sv" (Swedish), or "tr" (Turkish). If you leave it out, JavaScript uses the default language of the browser or computer. That can be right for an app that follows the user's language settings. In examples and tests, write the locale, so the result is the same on every computer.

In both blocks, line 1 uses German rules and line 2 uses Swedish rules on the same two words. German sorts ä next to a. Swedish treats ä as its own letter near the end of the alphabet, after z. The words did not change. Only the rules did. In the first block, line 3 uses localeCompare as the compare function for a whole sort.

localeCompare can also take a third argument with options. One option, sensitivity, says which differences count, such as capital letters or accents. The playground shows two of its settings at the bottom.

1const words = ["zebra", "äpfel", "apfel", "åre", "öl"];2const collator = new Intl.Collator(locale);3const sorted = [...words].sort(collator.compare);

localeCompare is handy for one or two comparisons. But a sort compares many pairs. For a sort, make one Intl.Collator. A collator is an object that holds one locale and one set of options.

A collator has a compare method. It is a ready-made comparator, so you can pass collator.compare straight to sort(). The rules are set up once, not again for every pair.

The table lists the options you'll use most. Read each row as: this option, what it changes, and a short example.

numeric: true helps most with file names. Without it, item10 sorts before item9. The first character that differs is 1 in one name and 9 in the other, and 1 comes first. With numeric: true, a run of digits is compared as one whole number, so 9 comes before 10.

toUpperCase() turns text into capital letters. toLowerCase() turns it into small letters. Changing between capital and small letters is called case conversion. These two methods use rules that suit most languages. A few languages need their own rules. For those, use toLocaleUpperCase(locale) and toLocaleLowerCase(locale), and name the language.

1"i".toLocaleUpperCase("tr"); // "İ"2"I".toLocaleLowerCase("tr"); // "ı"3"ß".toLocaleUpperCase("de"); // "SS"

Turkish has two different i letters: i with a dot and ı without one. Each has its own capital. So with Turkish rules, the capital of i is İ, a capital I with a dot. German is different again: JavaScript turns ß into two capitals, SS.

1const upperName = "Straße".toLocaleUpperCase("de");2 3console.log(upperName); // "STRASSE"4console.log(upperName.length); // 7, not 6

Line 1 makes the German capitals of Straße. Line 3 prints "STRASSE". Line 4 prints 7, one more than the 6 letters we started with. So one letter can become two.

This matters when you save or compare text after changing it. Don't assume each letter stays one letter. And don't write your own table of capital letters. Use these methods with the right locale.

A case-insensitive search ignores the difference between capital and small letters. Beginners often write haystack.toLowerCase().includes(needle.toLowerCase()). Here haystack is the text you search in, and needle is the text the user typed. Both become small letters. Then includes checks whether the first contains the second. This works for simple English labels. It misses three things:

• Accents: é and e still count as different.
• Language rules for capitals, like the two Turkish i letters.
• Two ways of storing the same letter. You'll see this below.

To check whether two whole strings are equal, a collator with sensitivity: "base" is often clearer.

1const collator = new Intl.Collator("en", { sensitivity: "base" });2 3collator.compare("Résumé", "resume") === 0; // true4"Résumé" === "resume"; // false

Line 1 makes a collator that ignores capitals and accents. Its compare method returns 0 when two strings count as equal. So line 3 is true. Line 4 is false, because === only says yes when every code unit is the same.

A collator can't tell you whether one string contains another. It only compares whole strings. For a search box with a small list, a common way is to fold the text first. To fold text means to turn it into a plain form used only for matching, for example José into jose. Fold the text the user typed too, not just the list. The fold uses normalization, so that comes first.

1const composed = "é";2const decomposed = "e\u0301";3 4console.log(composed === decomposed); // false5console.log(composed.normalize("NFC") === decomposed.normalize("NFC")); // true

The letter é can be stored in two ways:

• Line 1: as one character, "é".
• Line 2: as a plain e followed by a separate accent mark, \u0301. A separate mark like this is called a combining mark.

Both look the same on screen. But line 4 prints false, because === sees different code units.

Normalization rewrites text into one chosen form. normalize("NFC") joins a letter and its mark into one character where it can. Line 5 normalizes both sides, so it prints true. normalize("NFD") does the opposite: it splits letters from their marks. That helps when the next step removes the marks.

1function foldForSearch(value) {2  return value3    .normalize("NFD")4    .replace(/[\u0300-\u036f]/g, "")5    .toLocaleLowerCase("en");6}7 8console.log(foldForSearch("José")); // "jose"9console.log(foldForSearch("Søren")); // "søren"

The foldForSearch function has three steps:

1. Line 3 splits each letter from its accent marks with normalize("NFD").
2. Line 4 removes the marks. /[\u0300-\u036f]/g is a regular expression, a pattern for finding text. It finds every common combining mark, and replace swaps each one for nothing.
3. Line 5 changes the text to small letters with English rules.

So line 8 turns José into jose. Line 9 leaves ø as it is. ø is its own letter, not an o with a separate mark, so there is no mark to remove. This simple fold works for a known list of names in Latin letters, the alphabet English uses. For many other languages, use a search tool built for them.

1function foldForSearch(value) {2  return value3    .normalize("NFD")4    .replace(/[\u0300-\u036f]/g, "")5    .toLocaleLowerCase("en");6}7 8const names = ["José", "Soren", "Søren", "Zoë", "İpek", "Ipek"];9const matches = names.filter((name) =>10  foldForSearch(name).includes(foldForSearch(query)),11);

Where you’ll use this

You'll compare text anywhere people look through a list: contact names, countries, product titles, table columns, menus of commands, and file names. A safe pattern has three parts:

• Keep the original string to show on the screen.
• Make a compare or search helper for the job.
• Write the locale and the options in your code.

1const collator = new Intl.Collator(userLocale, {2  sensitivity: "base",3  numeric: true,4});5 6const visibleProducts = products7  .filter((product) => matchesSearch(product.name, query))8  .sort((a, b) => collator.compare(a.name, b.name));

Lines 1 to 4 make one collator from the user's locale, userLocale. Line 2 says to ignore capitals and accents. Line 3 says to compare digits as whole numbers. Line 7 keeps only the products that match the search. Line 8 sorts them by name with the collator.

Common misconceptions

• "Alphabetical order is the same everywhere." Languages put ä, å, and ö in different places. German puts ä next to a. Swedish puts it after z.
• "sort() knows my users' language." With no compare function, sort() uses code-unit order.
• "localeCompare always returns -1 or 1." Only the sign is promised: negative, zero, or positive.
• "Making both sides small letters fixes search for everyone." é and e still count as different, and language rules like the Turkish i are ignored.
• "Equal for a collator means the strings are the same." With sensitivity: "base", Résumé and resume count as equal, but === says false.

Key takeaways

• By default, JavaScript compares strings by their UTF-16 code units. The rule is exact and fast, but often not the order people expect.
• Use localeCompare to compare one pair with a language's rules.
• Make one Intl.Collator when you sort many strings with the same rules.
• Capital letters can depend on the language: Turkish has two i letters, and German ß becomes SS.
• A search that ignores capitals and accents needs clear choices: normalize the text, remove the marks, and pick a locale.

To compare text well, use the rule your users expect, not just the rule JavaScript uses by default.

Up next: Destructuring arrays.