- Docs
- Search and comparison
Search and comparison
Accent-insensitive search with fold and contains, highlight without HTML strings, natural sorting, typo suggestions and list filtering with data-string-search.
People type cafe and expect Café, type file2 and expect it before file10, and make typos. These functions handle all three with the same folding rules as removeAccents.
Folding
fold(text, { locale }) lowers the case, removes accents, transliterates ß, æ, œ, ø, đ, ł and þ, and maps full-width forms to ASCII: 'Ñandú ABC Straße' → 'nandu abc strasse'. Fold both sides before comparing, or use the functions below, which do it for you.
Finding text
import { contains, highlight } from '@samline/string'
contains('México: Café de olla', 'cafe mex') // true: every word must appear
contains('México: Café de olla', 'olla cafe', { split: false }) // false: one phrase
highlight('Café de olla', 'cafe')
// [{ text: 'Café', match: true }, { text: ' de olla', match: false }]
- An empty query matches everything.
highlightreturns pieces of the original text, so you build the markup yourself withtextContentand stay safe from HTML injection. Any query word is highlighted; decomposed accents (e+◌́) stay with their letter.localechanges how upper-case letters fold: with{ locale: 'tr' },Ifolds likeı.
Sorting
compareNatural(a, b, { locale, sensitivity }) uses Intl.Collator with numeric ordering and a cached collator per locale. Pass it straight to sort:
;['file10', 'file2', 'File1'].sort(compareNatural) // ['File1', 'file2', 'file10']
;['zeta', 'Árbol', 'avión'].sort(compareNatural) // ['Árbol', 'avión', 'zeta']
sensitivity defaults to 'base' (accents and case are equal); use 'accent', 'case' or 'variant' to tell them apart.
Typos
distance(a, b): Levenshtein distance in code points.('kitten', 'sitting')→3.similarity(a, b, { fold }): from0to1, folded by default.('Mexico', 'México')→1.closest(input, candidates, { threshold }): the most similar candidate, orundefinedbelowthreshold(0.5).('te vrde', ['Café de olla', 'Té verde'])→'Té verde'.
closest also compares the input with the start of each word of longer candidates (partial, on by default, for inputs of three characters or more), so horchatta finds Horchata de arroz and limon finds Jamaica con limón. A whole match scores a little higher than a partial one. similarity alone always compares whole strings.
Filtering a list
data-string-search="<field selector>" filters a list as the user types. The browser bundle starts it on its own; with a bundler, call search() or autoSearch() from @samline/string/vanilla.
<input id="q" type="search" />
<ul data-string-search="#q">
<li>Café de olla</li>
<li>Té verde</li>
<li hidden data-string-search-empty>No results</li>
</ul>
- Items that do not match get
hidden; matching text is wrapped in<mark>, inside nested markup too. Style it with[data-string-search] mark. - Items are the list’s direct children, or
data-string-search-items=".row". Items hidden in the HTML stay hidden and are not searched. - The
data-string-search-emptychild (or theemptyoption) shows only when nothing matches. Hide it in the HTML so it stays hidden without JavaScript. data-string-search-stateisidle(query shorter thanmin),resultsorempty.- Every search dispatches a bubbling
string:searchevent and callsonSearch(result, list). The result hasquery,matches(the matching items),totalandstate. destroy()removes every mark, puts back the original text nodes and restores everyhiddenattribute.
| Attribute | Option | Default |
|---|---|---|
data-string-search |
input |
– |
data-string-search-items |
items |
Direct children |
data-string-search-highlight |
highlight |
true |
data-string-search-min |
min |
1 |
data-string-search-split |
split |
true |
data-string-search-locale |
locale |
Closest lang |
| – | empty |
Empty child |
| – | onSearch |
– |
Attributes win over options. refresh() collects the items again after you add or remove some.