` elements smoothly transition from their off-screen position (`y: 100`) to their final position (`y: 0`)
- This creates a "cutting" or "revealing" effect as each piece of text slides into view
- The animation can be staggered from different directions (first, last, center, or random) using the `staggerFrom` prop
A key implementation detail is that the component always maintains word boundaries, even when splitting by characters. There are two reason for this:
1. When dealing with multi-line text, each line maintains its own reveal animation starting point. This means if you have text that spans multiple lines, each line will animate independently from its own baseline, rather than all elements animating from a single point (like the bottom of the entire paragraph).
2. When using `characters` mode, characters from the same word stay together in a word container. This prevents unwanted line breaks in the middle of words - if a word needs to wrap to the next line, it will wrap as a complete unit rather than having some characters on one line and others on the next line. This maintains proper text flow and readability while still allowing character-by-character animation within each word.
## Examples
### splitBy variations
With the `splitBy` prop, you can control how the text is split into smaller pieces. It can be either `words`, `characters`, `lines`, or a custom `string` delimiter.
Example:
```tsx
import VerticalCutReveal from "@/components/fancy/text/vertical-cut-reveal"
export default function Preview() {
return (
{"β We're on a mission\nto make the π web \nsuper fun again! βΊ"}
)
}
```
Example:
```tsx
import VerticalCutReveal from "@/components/fancy/text/vertical-cut-reveal"
export default function Preview() {
return (
{`super cool & awesome example text`}
)
}
```
### staggerFrom variations
With the `staggerFrom` prop, you can control the starting index of the animation. It can be either `first`, `last`, `center`, a `number` (custom index).
Example:
```tsx
import VerticalCutReveal from "@/components/fancy/text/vertical-cut-reveal"
export default function Preview() {
return (
{`THIS STAGGERS FROM FIRST`}
{`THIS STAGGERS FROM LAST`}
{`THIS STAGGERS FROM CENTER`}
{`THIS ONE FROM THE 5TH CHARACTER`}
)
}
```
Or you can use the `random` option, which will animate the elements in a random order. You can see the multiline text in action here too:
Example:
```tsx
import VerticalCutReveal from "@/components/fancy/text/vertical-cut-reveal"
export default function Preview() {
return (
{`βWhen a small, unassuming object exceeds our expectations, we are not only surprised but pleased. Our usual reaction is something like, "That little thing did all that?" Simplicity is about the unexpected pleasure derived from what is likely to be insignificant and would otherwise go unnoticed. The smaller the object, the more forgiving we can be when it misbehaves.β
β John Maeda,`}
)
}
```
### No auto start
If you don't want the animation to start automatically, you can set the `autoStart` prop to `false`. In this case, you can call the `startAnimation` method exposed via a ref to start the animation manually. Here is an example demonstrating how to do this when the component is inside the viewport (with the `useInView` hook from framer motion):
Example:
```tsx
"use client"
import { useEffect, useRef } from "react"
import { useInView } from "motion/react"
import VerticalCutReveal, {
VerticalCutRevealRef,
} from "@/components/fancy/text/vertical-cut-reveal"
export default function Preview() {
const ref = useRef(null)
const textRef = useRef(null)
const isInView = useInView(ref, { once: false })
useEffect(() => {
if (isInView) {
textRef.current?.startAnimation()
} else {
textRef.current?.reset()
}
}, [isInView])
return (
)
}
```
## Notes
Since each element is "cutted" because of the `overflow-hidden` property, with some fonts and font-families (eg italic), parts of the letter may be cutoff. That's why you can use the `containerClassName` prop to style the container element, the `worldLeterLevelClassName` prop to style word level container, and the `elementLevelClassName` prop to style the individual split elements. You can add padding for example to accomodate more space for the text.
## Props
| Prop | Type | Default | Description |
|----------|----------|----------|----------|
| children* | `string` | - | The text to be displayed and animated |
| reverse | `boolean` | `true` | Direction of the animation (true: bottom to top, false: top to bottom) |
| transition | `AnimationOptions` | `{ type: "spring", damping: 30, stiffness: 300 }` | Animation configuration for each element. Refer to motion docs for more details |
| splitBy | `"words" | "characters" | "lines" | string` | `"words"` | The split method for the text |
| staggerDuration | `number` | `0.2` | Delay between each element's animation start |
| staggerFrom | `"first" | "last" | "center" | "random" | number` | `"first"` | Starting index of the animation |
| containerClassName | `string` | - | Additional CSS classes for styling the container |
| wordLevelClassName | `string` | - | Additional CSS classes for styling the word level container |
| elementLevelClassName | `string` | - | Additional CSS classes for styling the individual elements |
| onClick | `() => void` | - | Callback function for click events |
| onStart | `() => void` | - | Callback function for when the animation starts |
| onComplete | `() => void` | - | Callback function for when the animation completes |
| autoStart | `boolean` | `true` | Whether to start the animation automatically |
---
*This documentation is also available in [interactive format](https://fancycomponents.dev/docs/components/components/text/vertical-cut-reveal).*