SplitTextPlugin

SplitText makes it easy to break apart the text in an HTML element so that each character, word, and/or line is in its own <div>, making complex animation simple.

For example, maybe you’d like to make each character or word fade into place in a staggered fashion. SplitText automatically works around various browser inconsistencies and recognizes line breaks appropriately. Plus it is highly configurable.

Watch overview video

Features

There are a few things about SplitText that set it apart from some of the other popular libraries and plugins out there:

• No dependencies - no jQuery dependency. Keep things lightweight (less than 2k gzipped and minified).

• Compatibility - It supports IE9+! Plus it doesn’t force non-breaking spaces into the divs like many other solutions on the web do, because those can alter the line breaks in some situations.

• Uses divs, not spans - Some browsers won’t render transforms like rotation, scale, skew, etc. on <span>s. Actually, it’s related to display: inline (the default for <span>s) which is why we’re using divs with display: inline-block for better animation flexibility.

• Nested elements - The element you are splitting can contain nested elements such as <span>, <strong>, <a>, etc. Works for words and chars, not lines (see this for a workaround for lines).

• Permits position: absolute - This can improve performance and enable effects that would otherwise be impossible. With SplitText, you can choose if you want the divs to remain in the document flow or not.

• Honors line breaks - Some other libraries force you to use a <br> to define line breaks, but SplitText doesn’t. Of course you’re welcome to use those if you prefer, but SplitText can recognize natural line breaks in the normal document flow. That’s handy because you don’t always know how the text will flow in every environment at various sizes.

• Extremely flexible class assignment - Use no classes at all, or define a different one for characters, words, and/or lines. They don’t need to be incremented (like “char1”, “char2”, “char3”…) but they can if you prefer (simply append "++" to the class name like charsClass: "yourCharClass++").

• Works with arrays and selectors - A single SplitText instance can manage multiple elements. You can feed in a regular array like new SplitText([element1, element2]) or a selector object (think jQuery), like new SplitText( $(".yourClass") ). For example, new SplitText("#yourID", {wordsClass: "word"}) would find the element with the ID "yourID" and split its text, applying a "word" class to every resulting word.

• revert() anytime - Allows you to get back to the original content (swaps in the innerHTML that was recorded when the split occurred).

Basic Usage

Start by creating a new SplitText instance and pass any of the following to the constructor to indicate which element(s) to split apart: a DOM element, an array of DOM elements, a selector object (like a jQuery object), or selector text. For example:

//a DOM element:
var yourElement = document.getElementById("yourID");
var split = new SplitText(yourElement);
//or selector text which will use jQuery by default (if loaded) to get the selection:
var split = new SplitText("#yourID");
//or a selector object, like jQuery:
var split = new SplitText( $(".yourClass") );
//or an array of DOM elements:
var split = new SplitText([element1, element2, element3]);

Configuration

By default, SplitText will split by characters, words, and lines which may be overkill for you. To control exactly which components are split apart (chars, words, and/or lines), or apply your own classes or set positioning to absolute, pass a vars configuration object as the second parameter to the constructor like new SplitText("#yourID", {type: "words,lines", wordsClass: "word++", position: "absolute"}).

• charsClass : String - A CSS class to apply to each character’s <div>, making it easy to select. If you add "++" to the end of the class name, SplitText will append an incremented number to each character’s <div>, starting at 1. For example, if charsClass is "char++", the div’s class for the first character would be "char1", the next would be "char2", then "char3", etc. [default: undefined]

• linesClass : String - A CSS class to apply to each line’s <div>, making it easy to select. If you add "++" to the end of the class name, SplitText will append an incremented number to each line’s <div>, starting at 1. For example, if linesClass is "line++", the div’s class for the first line would be "line1", the next would be "line2", then "line3", etc. [default: undefined]

• position : String - If "absolute", the position CSS style for all of the resulting <div> elements will be absolute and their top, left, width, and height CSS properties will be calculated and applied inline which can be useful for certain effects. It costs a bit more to split initially performance-wise, but it can improve performance during animation because the browser doesn’t have to do as many reflow calculations (in most cases). Keep in mind that once you split things using position: "absolute", if the containing element is resized, the split text chunks won’t reflow. [default: "relative"]

• reduceWhiteSpace : Boolean - Collapses white space characters into one, as most browsers typically do. Set to false if you prefer to maintain multiple white space characters in a row. [default: true]

• specialChars : [Array | Function] - Allows you to protect certain characters that are actually composed of multiple (combined) characters, like Hindi/Devanagari ones. SplitText has built-in support for emojis but it’s the same idea, where 2 or 4 characters in the string are combined to form a single one in the browser. When JavaScript splits a string into individual characters, it doesn’t recognize those combinations, thus a single emoji or Hindi character may actually, when split like string.split("") would have a length of 2 (or 4). So when SplitText does its magic (without specialChars), the single character would no longer show up. Instead, each of its parts would be treated as individual characters. To solve this, you can pass in an array of those special characters to specialChars. Advanced: if you want finer control, you can define a function instead of an array. As SplitText iterates through the characters, it feeds the REMAINING text to the function and then you return a number corresponding to how many characters should be grouped in that iteration. So technically you could apply whatever logic you want! So, for example, if the string is "ABCDE", the function would receive "ABCDE" as the parameter and if you returned 1 or 0 or null, then it’d take "A" as the character and the next time the function gets called, it’d receive "BCDE" and if you return 3, it would tell SplitText to group "BCD" as if it were a single character, so the next time the function gets called, it’d receive "E". Demo here.

• type : String - A comma-delimited list of the split type(s) which can be any of the following: chars, words, or lines. This indicates the type of components you’d like split apart into distinct <div> elements. For example, to split apart the characters and words (not lines), you’d use type: "chars,words" or to only split apart lines, you’d do type: "lines". In order to avoid odd line breaks, it is best to not split by chars alone (always include words or lines too if you’re splitting by characters). Note: Spaces are not considered characters. [default: "chars,words,lines"]

• wordDelimiter : String - normally words are split at every space character. The wordDelimiter property allows you to specify your own delimiter. If you want to split a hashtag like #IReallyLoveGSAP into words you could format the text like: #IReallyLoveGSAP and set `wordDelimiter:”“in the SplitTextconfig` object.

• wordsClass : String - A CSS class to apply to each word’s <div>, making it easy to select. If you add "++" to the end of the class name, SplitText will append an incremented number to each word’s <div>, starting at 1. For example, if wordsClass is "word++", the div’s class for the first word would be "word1", the next would be "word2", then "word3", etc. [default: undefined]

Then, once the SplitText has been created, you can access an array of the split-apart

//create a SplitText instance for the element with ID "yourElementID" that splits apart characters, words, and lines, and uses absolute positioning:
var split = new SplitText("#yourElementID", {type: "chars,words,lines", position: "absolute"});
//now animate each character into place from 100px above, fading in:
gsap.from(split.chars, {duration: 1, y: 100, autoAlpha: 0, stagger: 0.05});
//or animate each word
gsap.from(split.words, {duration: 1, x: 200, autoAlpha: 0, ease: "Elastic.easeOut", stagger: 0.05});
//or animate each line
gsap.from(split.lines, {duration: 1, x: 200, autoAlpha: 0, ease: "Power3.easeOut", stagger: 0.05});