Split Text

Use Split Text to reveal a short heading or statement by characters, words, or lines. It uses GSAP splitting and waits for fonts before it measures line-based text.

Preview

Reduce motion:Off

Tune:Off

Inspect

Split and reveal your text with GSAP.

Installation

GSAP

npx shadcn@latest add @sona-ui/split-text

Basic usage

split-heading.tsx

import SplitText from "@/components/ui/split-text/split-text";
 
export function SplitHeading() {
return <SplitText variant="words"><h2>Build with care.</h2></SplitText>;
}

Examples

Use words or lines for longer text and characters for short Latin phrases. Set scrollTrigger when the reveal should begin as the text enters the viewport.

Usage


export default function SplitTextExample() {
  return (
    <SplitText
      variant="words"
      className="max-w-md text-center"
      animationProps={{ duration: 0.3, stagger: 0.1 }}
    >
      <h2 className="font-semibold text-4xl lg:text-5xl text-foreground">
        Text that reveals itself, one word at a time.
      </h2>
    </SplitText>
  );
}

API

Property	Type	Default	Description
`children`	`ReactNode`	`required`	A single text element (e.g. a heading or paragraph) to split and animate.
`className`	`string`	`—`	Additional CSS classes for the wrapper.
`variant`	`SplitUnit`	`"words"`	Which unit the text is split into and animated.
`mask`	`boolean`	`true`	Mask each split piece (clip it) so it reveals from behind an edge instead of animating in fully visible. Masks by the same unit set in `variant`.
`animationProps`	`gsap.TweenVars`	`{ yPercent: 120, rotate: 5, stagger: 0.2, duration: 0.4 }`	GSAP tween vars merged over the defaults, e.g. `{ duration: 1.2 }`.
`scrollTrigger`	`boolean`	`false`	Play the animation when the element scrolls into view instead of on mount.
`start`	`string`	`"top 85%"`	ScrollTrigger start position (only used when `scrollTrigger` is true).
`autoSplit`	`boolean`	`false`	Re-split on resize so line breaks stay correct. Note: this replays the animation on every resize, so it suits looping reveals more than one-shot entrances. Font-load correctness is handled automatically either way.
`markers`	`boolean`	`false`	Show ScrollTrigger debug markers.

Accessibility

Pass one element as the child so the component can split it safely. Reduced-motion preferences render the final text immediately.

Styling

Use a block element with a defined width for line splitting. AutoSplit remeasures lines after a resize when the layout can change.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Sona UI