SplitType

SplitType

SplitType is a small javascript library that splits HTML text into elements so that lines, words, and characters can be animated independently. It was inspired by GSAP's SplitText plugin, and can be used with any animation library.

Under the hood, SplitType changes the html structure of the target elements, wrapping each line, word, and/or character in a element.

• Features
• Supported Browsers
• Installation
• Usage
  • Splitting Text
  • The types option
  • Accessing split text nodes
  • Reverting Split Text
  • Nested Elements
  • Absolute vs Relative position
  • Responsive Text
• API Reference
  • SplitType(target, [options])
  • Instance Properties
  • Static Properties
• Examples

Features

• Splits text into lines, words, and/or characters
• Customizable class names for split text elements
• Detects natural lines breaks in the text
• Preserves explicit lines breaks ( tags)
• Preserves nested HTML elements inside the target elements
• Supports unicode symbols such as emojis

Supported Browsers

SplitType works in all modern browsers. Internet Explorer is no longer supported.

• ✅ Chrome
• ✅ Firefox
• ✅ Edge
• ✅ Safari
• ❌ Internet Explorer

Installation

Yarn/NPM

You can install SplitType as a dependency using yarn or npm.

yarn add 'split-type'

import SplitType from 'split-type'

CDN

Or, include the following `

## Usage

### Splitting Text

The SplitType class "splits" the text content of the target elements using the provided options. It returns a `SplitType` instance which provides access to the split text nodes. By default, text will be split into lines, words, and characters, using relative position.

Because SplitType is a class, it cannot be called without the `new` keyword. As an alternative, you can use the static method `SplitType.create().`

```js
const text = new SplitType('#target')
// or
const text = SplitType.create('#target')

// Array of line elements
text.lines
// Array of word elements
text.words
// Array of character elements
text.chars

Important: The following style should be applied to all target elements. This prevents the characters from shifting slightly when text is split/reverted.

.target {
  font-kerning: none;
}

Also, if the target elements are inside a flex container, they need to have a defined width to prevent the text from moving when it gets split.

The types option

The types option lets you specify which units the text will be broken up into. There are three types: lines, words, and characters. You can specify any combination of these types. However, splitting text into only characters is not recommended. To maintain normal line breaks, you need to include words and/or lines.

// Splits text into lines, words, characters (default)
const text = new SplitType('#target')
// Splits text into words and characters
const text = new SplitType('#target', { types: 'words, chars' })
// Splits text into lines
const text = new SplitType('#target', { types: 'words' })

Accessing split text nodes

You can access the split lines/words/characters via properties on the SplitType instance.

// Splits text in element with ID="target"
const text = new SplitType('#target')

// An array of the all line elements
console.log(text.lines)
// An array of all word elements
console.log(text.words)
// An array of all character elements
console.log(text.chars)

You can also use selectors to access split text elements

const text = new SplitType('#target')
const words = document.querySelectorAll('#target .word')

Reverting Split Text

The revert method will restore the target element(s) to their original html content. It also removes all data associated with the target elements from SplitType's internal data store. It is recommended to revert split text once it is no longer needed (for example at the end of an animation, or before the component is unmounted).

Text can be reverted using the instance method:

instance.revert()

Or using the static method, and specify the target elements to revert.

SplitType.revert('#target')

Nested Elements

As of v0.3, nested elements inside the target elements will be preserved when text is split. This makes it possible to:

• Apply custom styles to specific parts of the test
• Include interactive elements such links are buttons inside split text.

Foo Bar

SplitType.create('#target')

Result

…

js
const text = new SplitType('#target')

// Reposition text after the container is resized (simplified version)
// This example uses lodash#debounce to ensure the split method only
// gets called once after the resize is complete.
const resizeObserver = new ResizeObserver(
  debounce(([entry]) => {
    // Note: you should add additional logic so the `split` method is only
    // called when the **width** of the container element has changed.
    text.split()
  }, 500)
)
resizeObserver.observe(containerElement)

…

js
// Split text into words and characters
const text = new SplitType('#target', { types: 'words, chars' })

// Animate characters into view with a stagger effect
gsap.from(text.chars, {
  opacity: 0,
  y: 20,
  duration: 0.5,
  stagger: { amount: 0.1 },
})