Class SplitText

Splits text in a container into words, letters, and optionally lines.

Preserves inline HTML, supports resize-driven line reflow, and restores the original DOM on destroy.

Apply font-kerning: none on the container to reduce layout shift.

Documentation

Hierarchy (View Summary)

Module<TC, TS, TM>
- SplitText

Index

Constructors

constructor

new SplitText(
    props?: TModuleProps<
        ISplitTextCallbacksMap,
        ISplitTextStaticProps,
        ISplitTextMutableProps,
        SplitText,
    >,
): SplitText
Parameters
- Optionalprops: TModuleProps<
      ISplitTextCallbacksMap,
      ISplitTextStaticProps,
      ISplitTextMutableProps,
      SplitText,
  >
Returns SplitText
Overrides Module.constructor
- Defined in src/components/SplitText/index.ts:58

Accessors

callbacks

get callbacks(): Callbacks<CallbacksMap, this>
Retrieves the module's callbacks instance.

Returns Callbacks<CallbacksMap, this>
Inherited from Module.callbacks
- Defined in src/base/Module/index.ts:64

isDestroyed

get isDestroyed(): boolean
Indicates whether the instance has been destroyed.

After destruction, destroy is a no-op.

Returns boolean
Inherited from Module.isDestroyed
- Defined in src/internal/Destroyable/index.ts:24

letters

get letters(): HTMLElement[]
Letter elements from the last split.

Returns HTMLElement[]
- Defined in src/components/SplitText/index.ts:96

lettersMeta

get lettersMeta(): ISplitTextLetterMeta[]
Letter metadata from the last split.

Returns ISplitTextLetterMeta[]
- Defined in src/components/SplitText/index.ts:91

lines

get lines(): HTMLElement[]
Line elements from the last split (empty when lines is false).

Returns HTMLElement[]
- Defined in src/components/SplitText/index.ts:116

linesMeta

get linesMeta(): ISplitTextLineMeta[]
Line metadata from the last split (empty when lines is false).

Returns ISplitTextLineMeta[]
- Defined in src/components/SplitText/index.ts:111

name

get name(): string
The name of the module, derived from the class name

Returns string
Inherited from Module.name
- Defined in src/base/Module/index.ts:57

prefix

get prefix(): string
Class name prefix for split elements ({corePrefix}split-text).

Returns string
Overrides Module.prefix
- Defined in src/components/SplitText/index.ts:86

props

get props(): TRequiredProps<MutableProps & StaticProps>
Current properties. Do not mutate these directly, use updateProps instead.

Returns TRequiredProps<MutableProps & StaticProps>
Inherited from Module.props
- Defined in src/base/Module/index.ts:47

words

get words(): HTMLElement[]
Word elements from the last split.

Returns HTMLElement[]
- Defined in src/components/SplitText/index.ts:106

wordsMeta

get wordsMeta(): ISplitTextWordMeta[]
Word metadata from the last split.

Returns ISplitTextWordMeta[]
- Defined in src/components/SplitText/index.ts:101

Methods

`Protected`_addTempClassName

_addTempClassName(element: Element, ...classes: string[]): void
Adds prefixed classes to an element and removes them on destroy.

Skips classes that are already present on the element.
Parameters
- element: Element
  Target DOM element.
- ...classes: string[]
  Unprefixed class name segments.
Returns void
Inherited from Module._addTempClassName
- Defined in src/base/Module/index.ts:139

`Protected`_cn

_cn(...classes: string[]): string
Builds one or more prefixed class names.
Parameters
- ...classes: string[]
  Unprefixed class name segments.
Returns string
Space-separated prefixed class string.
Inherited from Module._cn
- Defined in src/base/Module/index.ts:127

`Protected`_destroy

_destroy(): void
Stops listeners, unwraps lines when possible, and restores saved DOM.

Returns void
Overrides Module._destroy
- Defined in src/components/SplitText/index.ts:231

`Protected`_emit

_emit<E extends keyof ISplitTextCallbacksMap>(
event: E,
arg: ISplitTextCallbacksMap[E],
): void
Emits a callback event with a fixed payload.
Type Parameters
- E extends keyof ISplitTextCallbacksMap
Parameters
- event: E
- arg: ISplitTextCallbacksMap[E]
Returns void
Inherited from Module._emit
- Defined in src/base/Module/index.ts:107

_getMutable

_getMutable(): { __mutableProp: true }
Set default mutable props

Returns { __mutableProp: true }
Overrides Module._getMutable
- Defined in src/components/SplitText/index.ts:41

_getStatic

_getStatic(): {
    __staticProp: true;
    ariaLabel: string
    | boolean;
    container: HTMLElement;
    ignore: string | HTMLElement[] | (element: HTMLElement) => boolean;
    letterClass: string;
    letters: boolean;
    letterTag: keyof HTMLElementTagNameMap;
    lineClass: string;
    lines: boolean;
    linesWrapper: boolean;
    lineTag: keyof HTMLElementTagNameMap;
    lineWrapperClass: string;
    prepareText: (text: string) => string;
    resizeDebounce: number;
    wordClass: string;
    wordDelimiter: string;
    wordDelimiterOutput: string;
    wordTag: keyof HTMLElementTagNameMap;
}
Get default static props

Returns {
    __staticProp: true;
    ariaLabel: string | boolean;
    container: HTMLElement;
    ignore: string | HTMLElement[] | (element: HTMLElement) => boolean;
    letterClass: string;
    letters: boolean;
    letterTag: keyof HTMLElementTagNameMap;
    lineClass: string;
    lines: boolean;
    linesWrapper: boolean;
    lineTag: keyof HTMLElementTagNameMap;
    lineWrapperClass: string;
    prepareText: (text: string) => string;
    resizeDebounce: number;
    wordClass: string;
    wordDelimiter: string;
    wordDelimiterOutput: string;
    wordTag: keyof HTMLElementTagNameMap;
}
- __staticProp: true
- ariaLabel: string | boolean
  Accessible label for the container after splitting.
  - true — uses textContent as aria-label
  - false — does not set aria-label
  - string — uses the provided value
  Default
  true
- container: HTMLElement
  Container whose text content is split.
- ignore: string | HTMLElement[] | (element: HTMLElement) => boolean
  Elements excluded from splitting (selector, list, or predicate).
  Default
  null
- letterClass: string
  CSS class for letter elements.
  
  Default
  {prefix}__letter
- letters: boolean
  Split each word into individual letter elements.
  Default
  false
- letterTag: keyof HTMLElementTagNameMap
  HTML tag for letter wrappers.
  
  Default
  span
- lineClass: string
  CSS class for line elements.
  
  Default
  {prefix}__line
- lines: boolean
  Group words into line elements (reflows on resize).
  Default
  false
- linesWrapper: boolean
  Wrap each line in an extra element (useful for mask animations).
  Default
  false
- lineTag: keyof HTMLElementTagNameMap
  HTML tag for line wrappers.
  
  Default
  span
- lineWrapperClass: string
  CSS class for line wrapper elements.
  
  Default
  {prefix}__line-wrapper
- prepareText: (text: string) => string
  Preprocesses text before word splitting (e.g. CJK segmentation).
  Example
  const segmenter = new Intl.Segmenter('zh', { granularity: 'word' }); const instance = new SplitText({ container, prepareText: (source) => [...segmenter.segment(source)].map((s) => s.segment).join(' '), });
- resizeDebounce: number
  Debounce delay for resize-driven line reflow (ms).
  Default
  0
- wordClass: string
  CSS class for word elements.
  
  Default
  {prefix}__word
- wordDelimiter: string
  Delimiter used to split text into words.
  Default
  whitespace
- wordDelimiterOutput: string
  Delimiter inserted between words in the DOM (defaults to wordDelimiter).
  Default
  null
- wordTag: keyof HTMLElementTagNameMap
  HTML tag for word wrappers.
  
  Default
  span
Overrides Module._getStatic
- Defined in src/components/SplitText/index.ts:37

`Protected`_handleProps

_handleProps(diff: Partial<ISplitTextMutableProps>): void
Method that is called when the module's properties mutate. In most cases, used to handle callbacks.
Parameters
- diff: Partial<ISplitTextMutableProps>
Returns void
Inherited from Module._handleProps
- Defined in src/base/Module/index.ts:117

destroy

destroy(): void
Destroys the instance and runs all registered cleanup actions.

Safe to call multiple times; subsequent calls are ignored.

Execution order:
1. _destroy
2. all onDestroy callbacks, in registration order
3. isDestroyed is set to true
Returns void
Inherited from Module.destroy
- Defined in src/internal/Destroyable/index.ts:46

on

on<T extends keyof ISplitTextCallbacksMap>(
    target: T,
    listener: TCallbacksAction<ISplitTextCallbacksMap[T], SplitText>,
    settings?: ICallbacksSettings,
): () => void
Adds a custom callback to the module.
Type Parameters
- T extends keyof ISplitTextCallbacksMap
Parameters
- target: T
  The event type to listen for (e.g., 'props', 'destroy').
- listener: TCallbacksAction<ISplitTextCallbacksMap[T], SplitText>
  The function to execute when the event is triggered.
- settings: ICallbacksSettings = {}
  Additional settings for the callback.
Returns () => void
Inherited from Module.on
- Defined in src/base/Module/index.ts:190

onDestroy

onDestroy(action: () => void): void
Registers a function to run when the instance is destroyed.

If the instance is already destroyed, action runs immediately.
Parameters
- action: () => void
  Cleanup function (for example remove listeners or DOM classes).
Returns void
Inherited from Module.onDestroy
- Defined in src/internal/Destroyable/index.ts:64

split

split(): void
Splits text into words, letters, and optionally lines.

Emits beforeSplit, performs DOM work, then emits split.

Returns void
- Defined in src/components/SplitText/index.ts:151

updateProps

updateProps(props: Partial<ISplitTextMutableProps>): void
Change module's mutable properties
Parameters
- props: Partial<ISplitTextMutableProps>
Returns void
Inherited from Module.updateProps
- Defined in src/base/Module/index.ts:157

Class SplitText

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns SplitText

Accessors

callbacks

Returns Callbacks<CallbacksMap, this>

isDestroyed

Returns boolean

letters

Returns HTMLElement[]

lettersMeta

Returns ISplitTextLetterMeta[]

lines

Returns HTMLElement[]

linesMeta

Returns ISplitTextLineMeta[]

name

Returns string

prefix

Returns string

props

Returns TRequiredProps<MutableProps & StaticProps>

words

Returns HTMLElement[]

wordsMeta

Returns ISplitTextWordMeta[]

Methods

Protected_addTempClassName

Parameters

Returns void

Protected_cn

Parameters

Returns string

Protected_destroy

Returns void

Protected_emit

Type Parameters

Parameters

Returns void

_getMutable

Returns { __mutableProp: true }

_getStatic

__staticProp: true

ariaLabel: string | boolean

Default

container: HTMLElement

ignore: string | HTMLElement[] | (element: HTMLElement) => boolean

Default

letterClass: string

Default

letters: boolean

Default

letterTag: keyof HTMLElementTagNameMap

Default

lineClass: string

Default

lines: boolean

Default

linesWrapper: boolean

Default

lineTag: keyof HTMLElementTagNameMap

Default

lineWrapperClass: string

Default

prepareText: (text: string) => string

Example

resizeDebounce: number

Default

wordClass: string

Default

wordDelimiter: string

Default

wordDelimiterOutput: string

`Protected`_addTempClassName

`Protected`_cn

`Protected`_destroy

`Protected`_emit

`Protected`_handleProps