tailwind-typewriter v1.0.1

tailwind-typewriter

A plugin for Tailwind CSS that generates typewriter style text animations in pure CSS (no JavaScript required) ✨

Support

This plugin has been tested with Tailwind CSS v3. Previous releases may also work but are not officially supported.

Demo

Installation

Install the plugin:

# Using npm
npm install tailwind-typewriter

# Using Yarn
yarn add tailwind-typewriter

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-typewriter')
        // ...
    ]
};

Usage

The quickest, dirtiest way to get started is to insert a <span> with the type-example utility class somewhere in your markup. This will let you verify that everything is working with a built-in example:

<span class="type-example"></span>

Styling

You can style the animation text with the usual Tailwind utilities:

<span class="type-example text-lg text-rose-500"></span>

🗒️ Note: The blinking caret can only be styled using the configuration options below.

Customizing

The above example is essentially useless on its own. In a real world application, you'll probably want to provide your own text etc 😎. If, for example, you want to create an animation that cycles between names of fruit (with a 3 second delay) - you can do the following:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-typewriter')({
            wordsets: {
                fruit: {
                    words: ['apple', 'banana', 'orange', 'pear', 'strawberry'],
                    delay: 3
                }
            }
        })
    ]
};

<span class="type-fruit"></span>

🗒️ Note: The animation is generated in the ::after pseudo-element so it will be appended to any text inserted inside the <span>. This may or may not be desirable depending on your project.

Multiple Animations

You can create multiple animations in a single project. Each animation is called a 'wordset'. Each wordset has a name, a set of words/phrases, and its own configuration options (see the full API below).

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-typewriter')({
            wordsets: {
                fruit: {
                    words: ['apple', 'banana', 'orange', 'pear', 'strawberry'],
                    delay: 3
                },
                vegetables: {
                    words: ['carrot', 'celery', 'corn', 'potato'],
                    pauseBetween: 5
                }
            }
        })
    ]
};

A unique class is generated for each set as type-{wordset}. For example, to reference the Vegetables animation instead of Fruit, you would use the following:

<span class="type-vegetables"></span>

Singular Animations

This plugin was originally designed to create animations that cycled through a set of words. Sometimes however, you may need to create a simple effect for a single word or phrase. You probably also want this animation to output in a forwards direction, stopping after the last character.

To do this, choose your phrase, then set repeat and eraseSpeed to 0:

// tailwind.config.js
module.exports = {
    theme: {
        // ...
    },
    plugins: [
        require('tailwind-typewriter')({
            wordsets: {
                fruit: {
                    words: ['Your clever phrase'],
                    repeat: 0,
                    eraseSpeed: 0
                }
            }
        })
    ]
};

A word about performance

Generally speaking, CSS animations are very performant (certainly compared with JavaScript). However, it is worth noting that every letter in a wordset generates a CSS keyframe. This means that if you have a wordset with a large amount of text, this will have some impact on file size and possibly renderer performance. This wont be a problem in most use cases, but in large projects, discretion is strongly advised.

Configuration

wordsets

Currently, this is the only available top-level property. It serves as a wrapper for each wordset grouping. A wordset in essence, is just an object literal with a unique name for the key that contains the necessary configuration options for each animation:

wordsets: {
    fruit: {
        words: ['apple', 'banana', 'orange'],
        // ..
    },
    vegetables: {
        words: ['carrot', 'celery', 'corn'],
        // ...
    }
}

Options

The following options are also available to each individual wordset.