- Docs
- HTML attributes
HTML attributes
Convert text and fields with data-string, follow another field, count characters, fit text to its box, copy converted text and color avatars.
The HTML layer runs every conversion from attributes. The browser bundle starts it on its own; with a bundler, call string() or autoString() from @samline/string/vanilla.
<h2 data-string="title" data-string-small-words="de, la">la casa de papel</h2>
<input id="title" value="Café & Té" />
<input data-string="slug" data-string-source="#title" data-string-replacements='{"&": "y"}' />
import { autoString, string } from '@samline/string/vanilla'
const controller = string() // every [data-string] element now
const auto = autoString() // the same, and elements added later
controller.refresh() // read the attributes again
controller.destroy() // remove listeners and restore the original markup
Without a DOM both return an inert controller, so they are safe to import on the server.
Elements
data-string="<conversion>" replaces the element’s text with the converted text. The value is any name from CONVERSIONS: camel, pascal, kebab, snake, dot, path, constant, train, title, sentence, capitalize, uncapitalize, lower, upper, slug, accents, truncate and initials. Write the readable text in the HTML: it stays visible without JavaScript and for search engines.
- The original child nodes come back on
destroy(). When the text is already converted, the markup is left untouched. truncateputs the full text intitle;initialssetsrole="img"andaria-labelto the full name. An attribute you wrote yourself always wins and is never removed.
Fields
On an <input> or <textarea> the value is converted while the user types and once more on blur.
- A separator the user just typed is kept until blur, so
kebabshowshello-and thenhello-world, andslugusestrim: falsewhile typing. - The caret keeps its distance from the end of the value, and nothing is converted during IME composition.
data-string-live="false"converts on blur only.truncateandinitialsalways wait for blur.- Blur is used instead of
changebecause Safari skipschangewhen a script edited the value during input.
Following another field
data-string-source="<selector>" feeds the element from another input, textarea or element.
- A field fills itself from the source while
data-string-state="following". Typing in it switches toedited, and the source no longer overwrites it. Emptying it goes back tofollowing, and blur fills it again. - A field that starts with its own value, different from the converted source, starts as
edited. - A preview element (
<code>,<span>) shows the converted source as it changes. - Sources chain: a preview can follow a slug field that follows a title.
Options
Attributes win over JavaScript options. Every option of convert is available:
| Attribute | Option | Applies to |
|---|---|---|
data-string |
to |
Every element. |
data-string-source |
source |
Every element. |
data-string-live |
live |
Fields. |
data-string-locale |
locale |
Every conversion. |
data-string-small-words |
smallWords |
title. |
data-string-separator |
separator |
slug. |
data-string-lower |
lower |
slug. |
data-string-max-length |
maxLength |
slug. |
data-string-replacements |
replacements |
slug, as JSON. |
data-string-preserve |
preserve |
slug. |
data-string-taken |
taken |
slug, as a JSON array or a comma list. |
data-string-transliterate |
charMap |
slug, accents: cyrillic, greek, german. |
data-string-length |
length |
truncate. |
data-string-position |
position |
truncate. |
data-string-ellipsis |
ellipsis |
truncate. |
data-string-word-boundary |
wordBoundary |
truncate. |
data-string-max |
max |
initials. |
Without data-string-locale or a locale option, the element uses the lang of its closest ancestor, so <html lang="tr"> makes istanbul upper-case to İSTANBUL. smallWords accepts commas or spaces. Invalid JSON in data-string-replacements is ignored. A field with data-string-taken keeps what the user types while they type and moves to the first free slug on blur; while it follows its source, it is always free.
State and events
data-string-stateisready,followingoredited. Style or test against it.- Every conversion that changes the text dispatches a bubbling
string:changeevent withdetail: { value, state }, and calls theonChange(value, element)option.
slug.addEventListener('string:change', event => {
save.disabled = event.detail.value === ''
})
Colors
data-string-color (or { color: true }) sets the --string-color custom property to a stable color for the element’s original text, so every “Ana López” avatar gets the same hue. Use it in CSS with a fallback: background: var(--string-color, #475569). Lightness is lowered as needed so white text on it keeps a 4.5:1 contrast. Pass { color: { saturation, lightness, contrast } } to tune it; hashColor(text) returns the same color in code.
Counters
data-string-count="<field selector>" shows how many characters or words a field has, or how many are left.
<textarea id="bio" maxlength="160"></textarea>
<output data-string-count="#bio" data-string-count-format="{remaining} characters left"></output>
- Characters are graphemes, so 😀 counts as one.
maxlengthcounts UTF-16 units, so an emoji uses two of the field’s limit; setdata-string-count-maxto count against your own limit instead. data-string-count-unit="words"counts words withIntl.Segmenter.data-string-count-formatis a template with{count},{max}and{remaining}; the default is{remaining}with a maximum and{count}without. Theformatoption also takes a function.data-string-count-stateisok,near(at mostdata-string-count-nearleft, 10% of the maximum by default) orover.- Every update dispatches
string:countwith{ count, max, remaining, state }and callsonCount. <output>is announced politely by screen readers; on another element, addaria-live="polite"yourself if you want every change announced.
Fitting text to its box
data-string-fit shortens text until it fits the element’s width, cutting in the middle by default, and fits again when the element resizes (ResizeObserver, or window resize as the fallback) and when web fonts load.
<span data-string-fit style="display: block">annual-report-2026-final-version.pdf</span>
<span data-string-fit="end" data-string-fit-ellipsis="...">A long title</span>
- The value is the position:
middle(default),endorstart. - The element needs a width: a block, inline-block, flex or grid item. Without one, the text is left whole. Flex items also need
min-width: 0. - The full text goes to
title,data-string-fit-stateisfullortruncated, andwhite-space: nowrapandoverflow: hiddenare set inline.destroy()restores the text, the title and thestyleattribute.
Copy buttons
data-string-copy="<source selector>" copies the source’s text (a field’s value) to the clipboard on click, converted with data-string-copy-as="<conversion>" when given.
<input id="name" value="Ana María López" />
<button type="button" data-string-copy="#name" data-string-copy-as="slug">Copy handle</button>
- Without the Clipboard API (plain HTTP, some iframes), or when it refuses, the text is copied from a hidden selection instead.
- The button gets
data-string-copy-state="copied", orerrorwhen no copy succeeded, fordata-string-copy-resetmilliseconds (2000). Style it:[data-string-copy-state='copied']::after { content: ' · Copied' }. - Every click dispatches
string:copywith{ value, ok }and callsonCopy. - The clipboard needs a secure context (HTTPS or localhost).
Browser bundle
The classic script starts every [data-string], [data-string-search], [data-string-count], [data-string-fit] and [data-string-copy] element when the DOM is ready, including elements added later, and keeps the controller in Strings.controller. Add data-manual to the script tag to start it yourself; scope and locale go to every behavior, and each takes its own options under search, count, fit and copy:
<script
data-manual
src="https://cdn.jsdelivr.net/npm/@samline/string@2.0.1/dist/browser/string.global.js"
></script>
<script>
Strings.auto({ locale: 'es', count: { near: 5 }, copy: { reset: 1000 } })
</script>