Get GSAP

Version: 1.13.1 updated 2014-07-22

Core

    Extras

      Plugins

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

        SplitTextField

        Looking for an HTML5 solution? This page pertains to the ActionScript-based Flash tool that breaks apart TextFields, but GreenSock has a newer version that's built for HTML5 (splitting apart HTML text into <div> elements by character, word, and/or line). Read more here.

        Description

        What if you could take the existing text in a TextField and dynamically break it apart into individual TextFields for each character, word, or line so that you could animate them separately? Maybe your goal is to explode the characters apart or have words fall into place while fading in or blur sequentially. There are lots of great tools out there for creating interesting text effects but maybe you don't want an all-in-one solution with a new interface or API to learn. Maybe you're comfortable with the GreenSock Animation Platform and you want to control all the animation yourself and minimize file size. That was the idea behind SplitTextField. It isn't meant to be a text effects engine - it simply breaks apart a TextField instance and swaps itself (a Sprite) into place where the original TextField was in the display list, retaining the same scale/position/rotation so things appear relatively seamless. The SplitTextField has a "textFields" property which is an Array containing all the child TextFields it created (one for each character, word, or line based on the splitType property). Then you can animate to your heart's content.

        Interactive demo

        Getting started

        Carl Schooff did a great video tutorial here.

        Documentation

        View ASDoc documentation here.

        Sample AS3 code

        import com.greensock.text.SplitTextField;
        import com.greensock.TweenMax;
        import com.greensock.easing.Elastic;
        import com.greensock.plugins.*;
        import flash.geom.Point;
        
        //split myTextField1 by characters (the default type of split)
        var stf1:SplitTextField = new SplitTextField(myTextField1);
        
        //tween each character down from 100 pixels above while fading in, and offset the start times by 0.05 seconds
        TweenMax.allFrom(stf1.textFields, 1, {y:"-=100", autoAlpha:0, ease:Elastic.easeOut}, 0.05);
        
        //split myTextField2 by words
        var stf2:SplitTextField = new SplitTextField(myTextField2, SplitTextField.TYPE_WORDS);
        
        //explode the words outward using the physics2D feature of TweenLite/Max
        TweenPlugin.activate([Physics2DPlugin]);
        var i:int = stf2.textFields.length;
        var explodeOrigin:Point = new Point(stf2.width * 0.4, stf2.height + 100);
        while (i--) {
        	var angle:Number = Math.atan2(stf2.textFields[i].y - explodeOrigin.y, stf2.textFields[i].x - explodeOrigin.x) * 180 / Math.PI;
        	TweenMax.to(stf2.textFields[i], 2, {physics2D:{angle:angle, velocity:Math.random() * 200 + 150, gravity:400}, scaleX:Math.random() * 4 - 2, scaleY:Math.random() * 4 - 2, rotation:Math.random() * 100 - 50, autoAlpha:0, delay:1 + Math.random()});
        }
        
        //split myTextField3 by lines
        var stf3:SplitTextField = new SplitTextField(myTextField3, SplitTextField.TYPE_LINES);
        
        //slide each line in from the right, fading it in over 1 second and staggering the start times by 0.5 seconds. Then swap the original TextField back in.
        TweenMax.allFrom(stf3.textFields, 1, {x:200, autoAlpha:0, onComplete:stf3.deactivate}, 0.5);
        
        

        Notes / Limitations

        • Does not recognize "Auto kern" feature in Flash, nor can it accommodate justified text or the new TLF type of TextFields in CS5.
        • Positioning may be incorrect when non-standard anti-aliasing is used (like "anti-alias for readability"). Even with standard anti-aliasing, depending on the specific font you use positioning may be slightly off.
        • Does not work with htmlText
        • To improve performance, mouseChildren is set to false by default (you're welcome to set it to true if you need the TextFields to receive MouseEvents)
        • To avoid some bugs in the way Flash renders TextFields, when creating TextField instances dynamically make sure you set the various properties of the TextField BEFORE adding the actual text. For example, set the width, height, embedFonts, autoSize, multiline, and other properties before setting the text property.
        • Flex users should use FlexSplitTextField instead which extends UIComponent
        • SplitTextField and FlexSplitTextField are membership benefits of Club GreenSock ("Shockingly Green" and Business members only).

        Tips

        • It's usually best to embed your font in the TextField. It's not mandatory, but you won't be able to have smooth, anti-aliased text or use alpha effects without it (this is a Flash Player limitation, not SplitTextField).
        • You can swap the original TextField back into place anytime by calling deactivate(). destroy() has the same effect but it also clears all the TextFields in the "textFields" array and eliminates the reference to the source TextField, making it eligible for garbage collection. So if you want to tween the TextField into place, you could use the last tween's onComplete to call destroy() or deactivate().
        • You can optionally offset the SplitTextField's registration point by a certain number of pixels on its local x- or y-axis which can be useful if, for example, you want to be able to scale the whole SplitTextField from its center instead of its upper left corner. Use the regOffsetX and regOffsetY parameters/properties to do this.
        • To easily animate characters/words/lines into place, use TweenMax.staggerFrom() with the SplitTextField's textFields property like
          TweenMax.staggerFrom(mySTF.textFields, 1, {y:"-100", autoAlpha:0, ease:Elastic.easeOut}, 0.05);

        FAQ

        1. Where do I get SplitTextField? It's not in the tween platform downloads.
          SplitTextField is a membership benefit of Club GreenSock ("Shockingly Green" and Business members only). It's a way I say "thanks" to those who support the project. You can sign up for Club GreenSock here.
        2. Is there an AS2 version of SplitTextField? If not, are there plans to create one?
          No. Sorry, AS3 only. (and there are no plans to create an AS2 version)
        3. My animated text looks ugly and won't fade properly - what's the problem?
          You probably just forgot to embed the fonts in the TextField. This isn't a SplitTextField requirement at all - it's just that Flash won't allow transparency effects or anti-aliasing unless the fonts are embedded in the TextField.
        4. Does SplitTextField alter my original source TextField? What happens to it?
          No, the source TextField remains completely untouched except that it is removed from the display list. You can swap it back in using the deactivate() or destroy() methods of SplitTextField and you can reference it via the source property.
        5. Does SplitTextField work in Flex?
          Yes and no. It is pure AS3 and can work in Flex on regular TextFields, but most Flex users work with components like Label, Text, and TextArea instead. FlexSplitTextField attempts to accommodate Flex components by automatically looping through the UIComponent's children to find a TextField and work its magic there. So FlexSplitTextField is intended for use in Flex, although not all Flex components are guaranteed to work perfectly with it.
        6. Does SplitTextField eliminate the need for high-end text effects components like FlashEff?
          Absolutely not. SplitTextField doesn't have prebuilt animation effects or a fancy user interface. Tools like FlashEff are fantastic for quick, high-quality text animations that are easy for even novices to build. In fact, FlashEff uses TweenLite to do its animation.

        Need help?

        Feel free to post your question on the forums. You'll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.