Ultratype

Get Started

Ultratype is a lightweight library for creating split text animations. It differs from other animation libraries because it acts only as a splitter of sorts. What this means is that it does no animating own its own, rather it splits the text and gives each element css custom properties that can be referenced in css. One of the main purposes of Ultratype is to leverage the cascade and power of modern css.

Installation

You can install Ultratype with the following methods.

NPM

npm i ultratype

How it works

In order to create split text animations and do it accessibly it requires a significant amount of markup.

Before

<h2>Heading</h2>

After

<h2 aria-label="heading">
    <span aria-hidden="true">
        <span>H<span>
        <span>e<span>
        <span>a<span>
        <span>d<span>
        <span>i<span>
        <span>n<span>
        <span>g<span>
    </span>    
<h2>

If you're only splitting one or two elements manually doing this isn't so bad. The real issue comes when you have to split multiple elements or if your text is coming from an external source like a CMS. Ultratype essentially acts as a way to automate this proccess while adding some extra goodies along the way.

Options

By adding the following data-attributes to your element you can change the way custom properties are assigned to it.

data-delay

• Accepts a number greater than 0
• This will be the delay between the split elements in seconds (default: 0)
• If no delay is specified the elements will not stagger
• This is accessed in css as var(--delay)

<!-- The delay between each letter will be 0.4s -->
<h2 class="split-by-letter" data-delay="0.4"><h2>

data-initial-delay

• Accepts a number greater than 0
• Added to each elements var(--delay)

<!-- The total delay for each element will be it's staggered value + 1s -->
<h2 class="split-by-letter" data-delay="0.4" data-initial-delay="1">Heading</h2>

data-stagger-mode

• Changes the direction that the delay is added to each element
• Options: left, right, center
• Defaults to left

<!-- The element's letters will have the shortest delay starting from the right  -->
<h2 class="splt-by-letter" data-delay="0.2" data-stagger-mode="right">Heading</h2>

Custom Properties

In Ultratype everytime an element is split, the following custom properties are added to be referenced in css.

• delay - value in seconds, can be used to create staggering effects with your elements
• content - the content of the split element (ex. if the element is 'l' then the value of var(--content) would also be 'l')

Split by letter

A built-in function that will split you element's text into letters. It accepts one element as an argument. Once the element is split, it will assign each letter a class of letter to reference in css.

Example

<h2 class="split-by-letter" data-delay="0.1">Heading</h2>

// Only required if you are using npm, otherwise you can just call splitByLetter()
import {splitByLetter} from 'ultratype/lib';

const splitElement = document.querySelector('.split-by-letter');

splitByLetter(splitElement);

.split-by-letter{
    font-size: 2em;
}

.split-by-letter .letter{
    /* Adding var(--delay) here creates the staggered animation  */
    animation: fade 0.4s var(--delay) linear both;
}

@keyframes fade{
    from{
        opacity: 0;
    }
}

Split by word

A built-in function that will separate you element's text by words. It accepts one element as an argument. Once the element is split, it will assign each word a class of word to reference in css.

Example

<h2 class="split-by-word" data-delay="0.1">Split By Word</h2>

// Only required if you are using npm, otherwise you can just call splitByWord()
import {splitByWord} from 'ultratype/lib';

const splitElement = document.querySelector('.split-by-word');

splitByWord(splitElement);

.split-by-word{
    font-size: 2em;
}

.split-by-word .word{
    /* Adding var(--delay) here creates the staggered animation  */
    animation: slideIn 0.4s var(--delay) linear both;
}

@keyframes slideIn{
    from{
        transform: translate3d(0, 20px, 0);
        opacity: 0;
    }
}

Ultratype Group

By adding data-ultratype-group to the parent of split elements, it will make the elements play in the order that they appear in the markup.

Note: At the moment only direct siblings will play in order and the next element won't animation if the sibling before it has an infinite play state.

Example

<div data-ultratype-group>
    <h2 class="split-by-letter" data-initial-delay="2" data-delay="0.04">First</h2>
    <h2 class="split-by-letter" data-delay="0.2">Second</h2>
    <h2 class="split-by-word" data-delay="0.05">Third Option</h2>
</div>