SplitText

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/plugins out there:

  • No dependencies - no jQuery dependency. Keep things lightweight (less than 2k gzipped and minified).
  • Compatibility - even works in IE8! 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 spans. Actually, it's related to display:inline (the default for spans) 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. Requires version 0.5.4+.
  • 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") ). In fact, you can define a SplitText.selector just like TweenLite.selector so that you can feed in selector text directly and have it use whatever selector you want! It will use jQuery by default (if it is loaded), or whatever window.$ is. 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"}).

Then, once the SplitText has been created, you can access an array of the split-apart <div> elements of each type by using the SplitText's "chars""words", and/or "lines" properties. For example:

//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:
TweenMax.staggerFrom(split.chars, 1, {y:100, autoAlpha:0}, 0.05);
 
//or animate each word
TweenMax.staggerFrom(split.words, 1, {x:200, autoAlpha:0, ease:Elastic.easeOut}, 0.1);
 
//or animate each line
TweenMax.staggerFrom(split.lines, 1, {x:200, autoAlpha:0, ease:Power3.easeOut}, 0.1);

NESTED ELEMENTS AND EMOJI

SplitText (version 0.5.4+) will honor nested elements such as <span>, <strong>, <a>, etc. Want to have some fun with emoji? No problem: 🐳 🍔 ❤️. Watch the video below.

CUSTOM WORD DELIMITERS
Ever need to split a long string of text into words but didn't want any spaces? Custom word delimiters to the rescue! As of SplitText version 0.4.0, you can place any character you want to mark where words should be split and SplitText will remove them during the split. #AwesomeForLongHashTags.

NOTES / LIMITATIONS

  • In order to maintain proper line breaks, don't just split the characters - split by words too and/or lines.
  • If you are using custom fonts, make sure they load BEFORE you split (otherwise all the splitting will be based on the default font which could throw off how things get aligned and sized)
  • If your goal is to animate 2D transforms in IE8, make sure you set position:"absolute" because otherwise IE will clip the content using the original size of the character/word/line.
  • Some inline css styles are set on the resulting div elements in order to position them correctly, so if you apply classes and don't see some styles taking effect, that could be why (the inline styles are overriding the class styles). Feel free to clear those inline styles manually or use TweenLite.set([elements], {clearProps:"all"}) to clear them (of course that would affect positioning, so beware).
  • To maximize performance, only split the components you need. Don't split characters if you don't need to.
  • IE8 doesn't allow <div> tags to be nested inside <p> elements, so if you need IE8 compatability, don't try splitting <p> elements. Instead, build your HTML using <div> tags.
  • If the element uses justified text (text-align:justify), you must use position:"absolute" for the SplitText because divs that remain in the document flow cannot be justified.
  • Some browsers (like Safari) apply custom kerning by default between letters, so when characters are split apart and put into their own divs, the spacing is slightly different. A bug has been filed with the Safari team (it's a browser issue, not SplitText) but you can typically eliminate the differences by setting these CSS properties:
    font-kerning: none;
    -webkit-text-rendering: optimizeSpeed;
    text-rendering: optimizeSpeed;
    -webkit-transform: translateZ(0);
    transform: translateZ(0);

  • SplitText is not designed to work with SVG <text> nodes.

GETTING ODD LINEBREAKS WITH NESTED ELEMENTS?

Nested elements can produce some odd results when you split text into lines. The issue arises when a nested elements like <span> wrap onto multiple lines. SplitText must place the entire nested elements within the line that first appears on. At times this can make it appear that lines are breaking in the wrong place.

In most cases adding display:inline-block to the nested element will yield better results. For a detailed explanation watch the video below.

Please visit our SplitText Codepen Collection for more demos of SplitText in action.

SplitText is a Club GreenSock membership benefit. You must have a valid membership to use this class without violating the terms of use. Visit http://greensock.com/club/ to sign up or get more details.

Constructor

SplitText ;

Creates a SplitText object.

Properties

chars : Array

An array containing all of the characters' raw DOM elements that were split apart.

lines : Array

An array containing all of the lines' raw DOM element that were split apart.

selector : *

[static] When you pass a string to a SplitText (as the first parameter), it will feed that to its selector engine internally to find the element(s), and jQuery is used by default if it happens to be loaded.

words : Array

An array containing all of the words' raw DOM elements that were split apart.

Methods

revert :

Reverts to the original content (the innerHTML before the split).

split :

[static] Splits the text in the target element(s) according to the provided config properties.

Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.

Get GSAP

Version: 1.20.3 updated 2017-10-02

Core

    Extras

      Plugins

        By using GreenSock code, you agree to the terms of use.

        For an all-access pass to premium content

        Join Club GreenSock