- Docs
- API reference
API reference
Every @samline/string function with its input and output, from camelCase and slugify to truncate, initials, convert and the HTML layer.
Identifiers
| Function | 'XMLHttp request_id' becomes |
|---|---|
camelCase(text, options?) |
xmlHttpRequestId |
pascalCase(text, options?) |
XmlHttpRequestId |
kebabCase(text, options?) |
xml-http-request-id |
snakeCase(text, options?) |
xml_http_request_id |
dotCase(text, options?) |
xml.http.request.id |
pathCase(text, options?) |
xml/http/request/id |
constantCase(text, options?) |
XML_HTTP_REQUEST_ID |
trainCase(text, options?) |
Xml-Http-Request-Id |
These functions rebuild the text from its words, so separators and punctuation are dropped and accents are kept: camelCase('año nuevo') is añoNuevo.
Human text
| Function | Example |
|---|---|
titleCase(text, options?) |
'the lord of the rings' → 'The Lord Of The Rings' |
sentenceCase(text, options?) |
'HELLO World' → 'Hello world' |
capitalize(text, options?) |
'hello World' → 'Hello World' (rest untouched) |
uncapitalize(text, options?) |
'Hello World' → 'hello World' (rest untouched) |
titleCase keeps the original spacing and punctuation; pass smallWords to keep words such as of or de lower case.
URLs and search
slugify(text, options?):'¡Hola, Ñandú & Café!'→'hola-nandu-cafe'. See options.uniqueSlug(text, taken, options?):('Hola', ['hola', 'hola-2'])→'hola-3'.takenis a list, aSetor a(slug) => booleanfunction; the number is joined with the separator and kept insidemaxLength. Leave the current record’s own slug out oftakenwhen editing it.removeAccents(text, options?):'Ñandú Straße'→'Nandu Strasse'. Removes diacritics and transliterates ß, æ, œ, ø, đ, ł, þ, ð and ı;charMapadds more.CYRILLIC,GREEK,GERMAN: transliteration presets forcharMap('Щука'→'Shchuka','Αθήνα'→'Athina','Müller'→'Mueller').CHAR_MAPSholds them by name. Combine them with your own:{ ...CYRILLIC, ...GERMAN, '№': 'no' }.
Display
truncate(text, length, options?):('The quick brown fox jumps', 15)→'The quick…'. Counts graphemes, so emoji (👨👩👧, 🇲🇽) and accented letters are never split.{ position: 'middle' }keeps both ends ('annual-report-2026-final.pdf'at 19 →'annual-re…final.pdf') and{ position: 'start' }keeps the ending ('…fox jumps').initials(text, options?):'Samuel Olvera'→'SO'.hashColor(text, options?):'Ana López'→'hsl(… 55% 45%)', the same hue every time for the same name, ignoring case and accents. Lightness is lowered as needed so white text keeps a 4.5:1 contrast. See options.graphemes(text):'🇲🇽é'→['🇲🇽', 'é']. UsesIntl.Segmenter, with code points as the fallback.
Text
wordCount(text, options?):"¡Hola, mundo! It's 2026."→4.readingTime(text, options?):{ words, minutes }, minutes rounded up at 200 words per minute.pluralize(count, forms, options?):(1234, { one: '# file', other: '# files' })→'1,234 files'.formstakes theIntl.PluralRulescategories (zero,one,two,few,many,other);#becomes the formatted count;zerowins for0when given.template(text, values, options?):('Hola {user.name}', { user: { name: 'Ana' } })→'Hola Ana'.{{and}}are literal braces; missing values keep their placeholder unless you passmissing.escapeHtml(text):'<b>'→'<b>', for text and quoted attributes.unescapeHtml(text): numeric entities and&,<,>,",', ,©,®,…,—,–,«and»back to characters. Other named entities stay as they are.stripTags(html): plain text from HTML, without comments, scripts or styles. It is not a sanitizer; insert the result withtextContent.
Conversions by name
convert(text, to, options?):('content type', 'train')→'Content-Type'.tois one ofCONVERSIONS; options go to the underlying function (see options). An unknown name returns the text unchanged.CONVERSIONS:camel,pascal,kebab,snake,dot,path,constant,train,title,sentence,capitalize,uncapitalize,lower,upper,slug,accents,truncate,initials.isConversion(value):truefor a name inCONVERSIONS.
Search and comparison
See the search guide.
fold(text, options?):'Ñandú ABC Straße'→'nandu abc strasse'.contains(text, query, options?):('México: Café de olla', 'cafe mex')→true. Every query word must appear.highlight(text, query, options?):('Café de olla', 'cafe')→[{ text: 'Café', match: true }, { text: ' de olla', match: false }].compareNatural(a, b, options?):['file10', 'file2'].sort(compareNatural)→['file2', 'file10'].distance(a, b):('kitten', 'sitting')→3.similarity(a, b, options?):('Mexico', 'México')→1.closest(input, candidates, options?):('mexcio', ['Chile', 'México'])→'México'. Withpartial(default) it also compares with the start of each word:('horchatta', ['Horchata de arroz'])→'Horchata de arroz'.
Building blocks
words(text):'XMLHttpRequest'→['XML', 'Http', 'Request'].
HTML layer
From @samline/string/vanilla (see the HTML attributes guide):
string(target?, options?): convertstarget(an element, selector or list; defaults to[data-string]) and returns{ refresh, destroy }.destroy()is idempotent and restores the original markup.autoString(options?): the same for every match inscope, including elements added later. Takesselector,scopeandobservebesides thestring()options.search(target?, options?): filters each list (defaults to[data-string-search]) as its field changes and returns{ refresh, destroy }.autoSearch(options?): the same for every list inscope, including lists added later.count(target?, options?)/autoCount: character or word counters for[data-string-count].fit(target?, options?)/autoFit: text that fits its box, for[data-string-fit].copy(target?, options?)/autoCopy: copy buttons for[data-string-copy].- Every one returns
{ refresh, destroy }and is inert without a DOM. See the HTML attributes guide. - Attribute, event and property names as constants:
ATTRIBUTE(data-string),STATE_ATTRIBUTE(data-string-state),CHANGE_EVENT(string:change),COLOR_PROPERTY(--string-color);SEARCH_ATTRIBUTE,SEARCH_STATE_ATTRIBUTE,SEARCH_EMPTY_ATTRIBUTE,SEARCH_EVENT(string:search);COUNT_ATTRIBUTE,COUNT_STATE_ATTRIBUTE,COUNT_EVENT(string:count);FIT_ATTRIBUTE,FIT_STATE_ATTRIBUTE;COPY_ATTRIBUTE,COPY_STATE_ATTRIBUTEandCOPY_EVENT(string:copy).
Browser global
The CDN bundle defines window.Strings with every function above, every HTML behavior and its auto*(), auto(options?) and controller. On load it starts every behavior unless the script tag has data-manual. auto() passes scope and locale to every behavior and takes each behavior’s own options under search, count, fit and copy: auto({ locale: 'es', search: { min: 2 } }).
Types
CaseOptions, TitleCaseOptions, SlugifyOptions, UniqueSlugOptions, Replacements, TakenSlugs, RemoveAccentsOptions, CharMap, CharMapName, TruncateOptions, TruncatePosition, InitialsOptions, WordCountOptions, ReadingTimeOptions, ReadingTime, PluralForms, PluralizeOptions, TemplateOptions, Conversion, ConvertOptions, FoldOptions, MatchOptions, HighlightSegment, CompareOptions, SimilarityOptions and ClosestOptions; from /vanilla also StringOptions, AutoStringOptions, StringController, StringState, SearchOptions, AutoSearchOptions, SearchController, SearchResult, SearchState, CountOptions, CountInfo, CountState, CountUnit, FitOptions, FitState, CopyOptions, CopyDetail, CopyState, AutoOptions and Controller; and HashColorOptions.