StringSplit

StringSplit rebuilds text into line, word, and character wrapper spans, each with CSS variables you can use for animation. It preserves inline HTML inside the split, handles kerning, and can optionally scale text to fill the container width.

Registration

import StringTune, { StringSplit } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();
stringTune.use(StringSplit);
stringTune.start(60);

Attributes

Grammar

The string-split attribute controls what gets generated. Full reference: Split Grammar.

Tokens are separated by |. Each token enables a wrapper level and accepts an optional alignment parameter in []:

string-split="char[start]"
string-split="word[start]|char-word[start]"
string-split="line[center]|char-line[center]"
string-split="line[start]|fit"

Available tokens:

Available alignment params: start, center, end, random(min,max).

Quick Example

<h1
  class="hero-title"
  string="split"
  string-split="line[center]|char-line[center]"
>
  Crafting<br />Digital<br />Experiences
</h1>

.hero-title .-s-line {
  overflow: hidden;
  padding-bottom: 0.1em;
}

.hero-title .-s-char {
  display: inline-block;
  transform: translateY(100%);
  animation: charReveal 0.8s cubic-bezier(0.2, 0, 0, 1) forwards;
  animation-delay: calc(
    var(--line-index, 0) * 0.15s + var(--char-index, 0) * 0.03s
  );
}

@keyframes charReveal {
  to { transform: translateY(0); }
}

CSS Variables

Full reference: DOM Output.

On .-s-line

Plus alignment variables when requested: --line-start, --line-center, --line-end, --line-random.

On .-s-word

Plus alignment variables: --word-start, --wordLine-start, etc.

On .-s-char

Plus alignment variables: --char-start, --charWord-start, --charLine-center, etc.

On the source element

Inline HTML

You can use standard inline elements inside split text:

<h1 string="split" string-split="word[start]|char-word[start]">
  Crafted for <em>motion</em> systems
</h1>

The module preserves your inline markup in the rebuilt DOM. <em>, <strong>, <a>, <span>, and other inline elements keep their tag and attributes so your CSS continues to work.

Elements like <img>, <svg>, and <table> are kept as-is without splitting.

<br> forces a line break.

Full details: Inline HTML.

split-class

<split-class> is a helper element for applying CSS classes to generated wrappers:

<h2 string="split" string-split="word[start]|char-word[start]">
  <split-class class="is-accent">Signal</split-class> Layer
</h2>

The <split-class> element itself does not appear in the output. Its classes are applied to the generated word or char wrappers that contain its children.

If every char in a word shares the same split-class, the classes are hoisted to the word wrapper.

Fit

Adding fit to string-split scales text to fill the container width:

<h1 string="split" string-split="line[start]|fit">
  Big Headline
</h1>

.headline .-s-line {
  font-size: calc(var(--fit-font-size) * 1px);
}

With line-level split, each line gets its own --fit-font-size. Without line-level split, the source element gets --fit-font-size, --fit-scale-y, and --fit-aspect-ratio.

Full details: Fit And Rebuild.

Lifecycle

When the DOM is rebuilt

• On initial connection
• On desktop width resize
• On reconnect

The module caches the original HTML on first split. On each rebuild, it starts from that cached original to produce a clean result.

Mobile

Mobile rebuild is disabled by default. The split DOM stays as initially built when the viewport height or width changes on mobile.

Restore After

<h1
  string="split"
  string-split="char[start]"
  string-split-restore-after="2000"
>
  Intro Text
</h1>

After 2000ms, the module restores the original HTML and adds class -restored. Useful for one-shot intro effects.

Accessibility

• All generated wrappers get aria-hidden="true"
• The source element gets aria-label with the original text
• Screen readers read the original content, not individual wrapper spans

Events

StringSplit does not emit module-specific events. Consume its output through CSS selectors and variables.

Deep Dives

• Split Grammar — full attribute reference
• DOM Output — wrappers, classes, variables, and nesting
• Inline HTML — how markup survives the split
• Fit And Rebuild — fit mode and rebuild timing