Text

April 30, 2025

Transform your static content into dynamic experiences with our Text component. This versatile animation tool brings elegance and motion to your words, making information more engaging and memorable without complex setup.

This text appears from below

./src/components/UI/ TextMain .astro

---
import { Text } from "@butter-js/ui";
---

<Text
  class="text-2xl font-normal"
  as="h2"
  y={100}
  duration={1}
  textType="chars"
  staggerAmount={0.5}
  staggerFrom="random"
>
  This text appears from below
</Text>

Features

Character, word, and line animations
Staggered animation effects
No conflicting animations
Text masking support
Font-loading aware
Reusable with unique instances

API Reference

Prop	Default	Type	Description
`as`	’p’	`string`	HTML element to render (`p`, `h1`, `span`, etc.).
`textType`	’chars’	`'chars' \| 'words' \| 'lines'`	Animation granularity.
`class`	-	`string`	Additional CSS classes to apply to the wrapper.
`mask`	’false’	`true \| false`	Enables text masking effect.
`tweenFrom`		`TweenAnimation`	Initial GSAP config (see TweenConfig ).
`duration`	0.7	`number`	Animation duration in seconds.
`opacity`	-	`number`	Initial opacity (0–1).
`y`	-	`number`	Initial vertical offset in pixels.
`x`	-	`number`	Initial horizontal offset in pixels.
`delay`	-	`number`	Delay before animation starts, in seconds.
`ease`	’power4.out’	`string`	GSAP easing type.
`staggerAmount`	0.1	`number`	Time (in seconds) between each element’s animation.
`staggerFrom`	’start’	`string`	Starting point for stagger (see stagger docs ).

Examples

Words + Mask

A mask effect is implemented that allows text to gradually emerge from below, revealing individual words in a random yet staggered sequence.

Text separated word by word in random order

./src/components/UI/ TextWords .astro

---
import { Text } from "@butter-js/ui";
---

<Text
  class="text-2xl"
  as="p"
  textType="words"
  mask="true"
  tweenFrom={{
    y: 30,
    duration: 0.7,
    ease: "power4.out",
    stagger: {
      amount: 0.2,
      from: "random",
    },
  }}
>
  Text separated word by word in random order
</Text>

Lines

In this example, we can see five span elements that animate one by one in a staggered sequence. This creates a flowing effect ideal for multi-line text blocks where you want each line to appear with precise timing and movement control.

Text separated line by line Text separated line by line Text separated line by line Text separated line by line Text separated line by line

./src/components/UI/ TextLines .astro

---
import { Text } from "@butter-js/ui";
---

<Text
  class="text-2xl font-light flex flex-col"
  as="p"
  textType="lines"
  mask="true"
  tweenFrom={{
    y: 100,
    duration: 0.7,
    ease: "power4.out",
    stagger: {
      amount: 0.4,
      from: "start",
    },
  }}
>
  <span>Text separated line by line</span>
  <span>Text separated line by line</span>
  <span>Text separated line by line</span>
  <span>Text separated line by line</span>
  <span>Text separated line by line</span>
</Text>

Bonus Text

Hacker

A scramble text effect that creates a “decoding” animation, perfect for displaying dates or numerical information with a technical, cyberpunk feel.

April 30, 2025

./src/components/UI/ TextHackerMain .astro

---
import { TextHacker } from "@butter-js/ui";

const defaultChars =
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
---

<TextHacker
  class="text-2xl font-geist-code"
  stagger={0.1}
  duration={0.5}
  delay={0.5}
  scrambleChars={defaultChars}>April 30, 2025</TextHacker
>

API Reference

Prop	Default	Type	Description
`as`	’p’	`string`	HTML element to render (e.g. `p`, `h1`, `a`, etc.).
`href`	-	`string`	URL to use when `as="a"`.
`class`	-	`string`	Additional CSS classes to apply to the wrapper.
`tweenFrom`	`{}`	`object`	TweenAnimation Additional GSAP config for the initial animation state.
`duration`	0.7	`number`	Animation duration in seconds.
`ease`	’none’	`string`	GSAP easing function.
`delay`	-	`number`	Delay before the animation starts, in seconds.
`stagger`	0.1	`number`	Time between each character’s animation in seconds (see stagger docs ).
`scrambleChars`	’upperCase’	`'upperCase' \| 'lowerCase' \| 'upperCase' \| 'upperAndLowerCase'`	Characters or mode used for the scramble effect (see ScrambleTextPlugin ).