A creative developer helper library
npm install situs-kitA zero-dependency creative developer toolkit
- SplitText
- SmoothScroll
- Ticker
---
Split text into characters, words, and lines while preserving inline HTML elements like , , , and .
``ts
import { SplitText } from "situs-kit/split-text";
const split = new SplitText("#my-text", {
type: ["chars", "words", "lines"],
});
split.chars; // HTMLElement[]
split.words; // HTMLElement[]
split.lines; // HTMLElement[]
`
`ts`
new SplitText(
element: HTMLElement | HTMLElement[] | ArrayLike
options?: SplitTextOptions
)
The element parameter accepts:
- A CSS selector string (e.g. "#my-text", ".my-class")HTMLElement
- A single
- An array or array-like collection of s (creates sub-instances, aggregating results)
`ts`
new SplitText(element, {
type: ["chars", "words", "lines"], // which levels to split
tag: "span", // wrapper element tag
children: true, // split children of the target
mask: ["chars", "lines"], // which levels to mask
resize: true, // auto-reflow lines on resize
style: {
chars: { color: "red" },
words: {},
lines: {},
mask: {}, // flat: applies to all masks
// mask: { chars: {}, lines: {} }, // per-type: target specific masks
},
class: {
chars: "my-char",
words: "my-word",
lines: "my-line",
mask: "my-mask", // flat: applies to all masks
// mask: { chars: "c", lines: "l" }, // per-type: target specific masks
},
});
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| type | SplitType \| SplitType[] | ["chars", "words", "lines"] | Split granularity |tag
| | string | "span" | Wrapper element tag |children
| | boolean | false | Split the target's child elements instead of the target itself |mask
| | boolean \| SplitType[] | false | Create overflow-hidden wrappers. true masks all requested types; array masks only specified types |resize
| | boolean | true | Auto-reflow lines on window resize (only applies when lines are split) |style
| | object | — | Inline styles per split type. mask accepts a flat object (all masks) or per-type { chars?, words?, lines? } |class
| | object | — | CSS classes per split type. mask accepts a string (all masks) or per-type { chars?, words?, lines? } |
> Type safety: style, class, and mask are constrained by type. Setting style: { words: {} } when type: ["chars"] is a compile-time error.
`ts
type SplitType = "chars" | "words" | "lines"
type SplitTypeOption =
| SplitType
| ["chars"]
| ["words"]
| ["lines"]
| ["chars", "words"]
| ["chars", "lines"]
| ["words", "lines"]
| ["chars", "words", "lines"]
`
| Property | Type | Description |
|----------|------|-------------|
| dom | HTMLElement \| HTMLElement[] | The original element(s) |chars
| | HTMLElement[] | Character wrapper elements |words
| | HTMLElement[] | Word wrapper elements |lines
| | HTMLElement[] | Line wrapper elements |masks
| | { chars: HTMLElement[], words: HTMLElement[], lines: HTMLElement[] } | Mask wrapper elements per split type |
Recalculate line groupings without re-splitting characters or words. Called automatically on resize when resize: true. Does nothing if lines weren't requested in type.
`ts`
split.reflow();
Restore the element to its original HTML. Clears all chars, words, lines, and masks arrays. Calls destroy() internally.
`ts`
split.revert();
Remove resize observers and cancel pending animation frames. Called automatically by revert(). Safe to call multiple times.
`ts`
split.destroy();
Split elements include data attributes for CSS targeting:
`css`
[data-char] { display: inline-block; }
[data-word] { display: inline-block; }
[data-line] { display: block; }
Mask elements use:
- data-maskChar
-
-
Inline elements like , , , , , , , , , and are preserved and cloned around split elements.
Opaque elements like
, ,