Class SplitText

SplitText splits text within a container into individual lines, words, and letters.

Features:

Supports resizing, HTML content, and special symbols like emojis.
Handles multi-line breaks and non-breaking spaces.
Saves initial nodes for easy restoration.
Allows splitting into lines, words, or letters as needed.

Note: Apply fontKerning: none to prevent layout shifts.

Documentation

Hierarchy (View Summary)

Module<TC, TS, TM>
- SplitText

Index

Constructors

constructor

new SplitText(
    props?: ISplitTextStaticProps & ISplitTextMutableProps & Partial<
        {
            onBeforeSplit: (data: undefined, ctx: SplitText) => void;
            onDestroy: (data: undefined, ctx: SplitText) => void;
            onProps: (data: Partial, ctx: SplitText) => void;
            onSplit: (data: undefined, ctx: SplitText) => void;
        },
    >,
    onCallbacks?: Partial<
        {
            onBeforeSplit: (data: undefined, ctx: SplitText) => void;
            onDestroy: (data: undefined, ctx: SplitText) => void;
            onProps: (data: Partial, ctx: SplitText) => void;
            onSplit: (data: undefined, ctx: SplitText) => void;
        },
    >,
): SplitText
Initializes the SplitText instance and saves the initial state.
Parameters
- Optionalprops: ISplitTextStaticProps & ISplitTextMutableProps & Partial<
      {
          onBeforeSplit: (data: undefined, ctx: SplitText) => void;
          onDestroy: (data: undefined, ctx: SplitText) => void;
          onProps: (data: Partial, ctx: SplitText) => void;
          onSplit: (data: undefined, ctx: SplitText) => void;
      },
  >
- OptionalonCallbacks: Partial<
      {
          onBeforeSplit: (data: undefined, ctx: SplitText) => void;
          onDestroy: (data: undefined, ctx: SplitText) => void;
          onProps: (data: Partial, ctx: SplitText) => void;
          onSplit: (data: undefined, ctx: SplitText) => void;
      },
  >
Returns SplitText
Overrides Module.constructor
- Defined in src/components/SplitText/index.ts:85

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:76

isDestroyed

get isDestroyed(): boolean
Checks if the module has been destroyed.

Returns boolean
Inherited from Module.isDestroyed
- Defined in src/base/Module/index.ts:66

letters

get letters(): HTMLElement[]
Retrieves an array of letter elements.

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

lettersMeta

get lettersMeta(): ISplitTextLetterMeta[]
Retrieves an array of letters metadata.

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

lines

get lines(): HTMLElement[]
Retrieves an array of line elements.

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

linesMeta

get linesMeta(): ISplitTextLineMeta[]
Retrieves an array of lines metadata.

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

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:56

prefix

get prefix(): string
Classname prefix for styling elements.

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

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:46

words

get words(): HTMLElement[]
Retrieves an array of word elements.

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

wordsMeta

get wordsMeta(): ISplitTextWordMeta[]
Retrieves an array of words metadata.

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

Methods

`Protected`_addTempClassName

_addTempClassName(element: Element, className: string): void
Adds a class name on an element, and keeps track of it for removal when the module is destroyed.
Parameters
- element: Element
  The target DOM element.
- className: string
  The class name to toggle.
Returns void
Inherited from Module._addTempClassName
- Defined in src/base/Module/index.ts:209

`Protected`_cn

_cn(...classNames: string[]): string
Helper function to generate classnames with the module's prefix.
Parameters
- ...classNames: string[]
  The class names to generate.
Returns string
A string of class names with the module's prefix applied.
Inherited from Module._cn
- Defined in src/base/Module/index.ts:199

`Protected`_destroy

_destroy(): void
Destroys the component. This method does not restore the initial nodes. For this purpose, use restore().

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

_getMutable

_getMutable(): { __mutableProp: true }
Get default mutable properties.

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

_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 properties.

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
  Allow aria-label. false prevents adding aria-label attributes to container. String value overrides the default aria-label.
  Default
  true
- container: HTMLElement
  The text container where the text will be split.
- ignore: string | HTMLElement[] | (element: HTMLElement) => boolean
  Do not split certain elements. Supports string selectors, array of elements, or function.
  Default
  null
- letterClass: string
  Letter class name.
  
  Default
  v-split-text__letter
- letters: boolean
  Specifies whether the text should be split into individual letters.
  Default
  false
- letterTag: keyof HTMLElementTagNameMap
  HTML tag to wrap each letter.
  
  Default
  span
- lineClass: string
  Line class name.
  
  Default
  v-split-text__line
- lines: boolean
  Specifies whether the text should be split into lines.
  Default
  false
- linesWrapper: boolean
  Specifies whether to wrap each line in an additional container.
  Default
  false
- lineTag: keyof HTMLElementTagNameMap
  HTML tag to wrap each line.
  
  Default
  span
- lineWrapperClass: string
  Line wrapper class name.
  
  Default
  v-split-text__line-wrapper
- prepareText: (text: string) => string
  Optional callback to preprocess text before it is split into words. This function receives the original text and should return the modified text. It is useful for languages like Chinese where standard word splitting may not work correctly.
  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
  The debounce delay for the resize event in milliseconds.
  Default
  0
- wordClass: string
  Word class name.
  
  Default
  v-split-text__word
- wordDelimiter: string
  Specifies a custom delimiter used to split text into words. By default, splitting occurs on regular whitespace.
  Default
  " "
- wordDelimiterOutput: string
  Provides an alternative delimiter to use when outputting the split words. Useful when a custom input delimiter is used but the output should differ.
  Default
  null
- wordTag: keyof HTMLElementTagNameMap
  HTML tag to wrap each word.
  
  Default
  span
Overrides Module._getStatic
- Defined in src/components/SplitText/index.ts:43

`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:131

destroy

destroy(): void
Destroys the module, cleaning up resources, callbacks, and event listeners.

Returns void
Inherited from Module.destroy
- Defined in src/base/Module/index.ts:223

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:185

onDestroy

onDestroy(action: () => void): void
Adds a callback on the module's destruction.
Parameters
- action: () => void
  The function to execute during destruction.
Returns void
Inherited from Module.onDestroy
- Defined in src/base/Module/index.ts:167

split

split(): void
Splits the text into letters, words, and optionally lines based on configuration.

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

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:137

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

_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

Default

wordTag: keyof HTMLElementTagNameMap

Default

Protected_handleProps

`Protected`_addTempClassName

`Protected`_cn

`Protected`_destroy

`Protected`_handleProps