AnimateSplit

A line of text arriving a word (or a letter) at a time. AnimateAppear walks down a list a child at a time; this walks along a sentence.

import { AnimateSplit } from 'neba';

<AnimateSplit render={<h1 />}>A line arriving a word at a time</AnimateSplit>;

Props

Prop	Type	Default	Description
text	string	—	The text, when it is easier to pass than to nest. Overrides children
by	'word' | 'character'	'word'	What one piece is. A heading of eight words is eight boxes; by character it is forty-six
effect	NebaAnimation	'slide'	Which effect each piece arrives on, in the library own vocabulary
from	'top' | 'right' | 'bottom' | 'left'	'bottom'	Which edge a slide piece comes from
distance	number | string	'0.4em'	How far a slide piece travels
locale	string	—	Which language the text is in, for the word and character boundaries: a word boundary is not a space in Japanese, Thai or Chinese
scale	number	—	Where a `grow` or `zoom` piece starts, as a multiple of its final size
angle	number	—	How far a `rotate` piece turns from, in degrees
side	'top' | 'right' | 'bottom' | 'left'	—	Which edge a `reveal` piece is wiped from
render	useRender.RenderProp	—	Renders something other than a div (render={<h1 />}). Base UI's own escape hatch
children	ReactNode	—	The text to split

Every other <div> attribute passes through to the root. The settings shared by every Animate* are defined in prop conventions.

Only text is split. Pass a string, or text; an element among the children contributes its words and nothing about its markup, because there is no honest way to animate half of a link.

Every piece is an inline-block (an inline box cannot be translated up), and each keeps the space that followed it, so a line still breaks between words and never inside the gap.

Examples

by and effect

by is what one piece is: word by default, because a heading of eight words is eight boxes and the same heading by character is forty-six. effect is which animation each piece arrives on, in the library's own vocabulary, so a split heading's fade and an AnimateFade are the same fade.

import { useState } from 'react';
import { AnimateSplit, Button, Typography } from 'neba';

export default function AnimateSplitBy() {
  const [run, setRun] = useState(0);

  return (
    <div className="flex w-full flex-col gap-4">
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Play again
      </Button>

      <div key={run} className="flex flex-col gap-5">
        <div className="flex flex-col gap-1">
          <Typography level="caption" color="secondary">
            by=&quot;word&quot; — the default
          </Typography>
          <AnimateSplit className="text-lg text-(--neba-fg)">
            Eight words is eight boxes on the page.
          </AnimateSplit>
        </div>

        <div className="flex flex-col gap-1">
          <Typography level="caption" color="secondary">
            by=&quot;character&quot; · effect=&quot;grow&quot;
          </Typography>
          <AnimateSplit
            by="character"
            effect="grow"
            stagger={28}
            className="text-lg text-(--neba-fg)"
          >
            Letter by letter
          </AnimateSplit>
        </div>
      </div>
    </div>
  );
}

stagger

stagger is how long after one piece the next one starts, and it is what the effect is made of: 45 milliseconds by default. durationStep lengthens each successive piece and reverse runs the line from the end.

locale

Which language the text is in, for finding the boundaries. A word boundary is not a space in Japanese, Thai or Chinese, and splitting those on whitespace produces one piece holding the whole sentence.

Accessibility

• The whole line is in the document once for a screen reader, in a clipped box, and the pieces are hidden from it. Without that a sentence is read as a list of forty-six separate letters and a find-in-page matches nothing.
• A reduced-motion preference switches the animation off and the line is drawn whole.