Atelier UI®

DocsCatalogPricingGithub
Docs 1.0.02.0 in development.

tools

  • Browse Catalog
  • Collage
    new

Documentation

  • How it works
  • License
  • MCP

Page Transition (04)

  • Clip Transition
  • Stripe Transition
  • Pixel Transition
  • Band Transition

Components (36)

  • Orbit Gallery
  • Sphere Gallery
  • Spiral Gallery
  • Glowing Fog
  • Gradient Flow
  • Halftone Glow
  • Scattered Grid
  • Tag Cloud
  • Edge Bounce
  • Fluid Distortion
  • Image Trail
  • Lens Media
  • Liquid Media
  • Magnetic Dot Grid
  • Pixel Media
  • Pixel Trail
  • Dither Cursor
  • Hover Burst
  • Image Bloom
  • Curve Media
  • Infinite Gallery
  • Infinite Parallax
  • Infinite Zoom
  • Pixel Scroll
  • Scattered Scroll
  • Elastic Stick
  • Letter Swarm
  • Magnify Trail
  • Stacking Grid
  • Wavy Scroll
  • Pixelated Text
  • Text Bounce
  • Text Fluid
  • Text Scramble
  • Falling Text
  • Text Roll

Foundation Blocks (07)

  • Smooth Scroll
  • Text Split
  • WebGL Image
  • WebGL Provider
  • WebGL Scene
  • WebGL Text
  • WebGL Video
Atelier UI 1.0.0 ©2026
Star on githubBuy me a coffee
  1. Docs
  2. /
  3. Components
  4. /
  5. Text Roll

Text Roll

Interactive rolling text effect on hover, mount and scroll.

https://atelier-ui.com/text-roll
axis
mode
direction
stagger
0.010
duration
0.8
cycles
2
play-on-hover
play-on-scroll
play-on-mount
axis
mode
direction
stagger
0.010
duration
0.8
cycles
2
play-on-hover
play-on-scroll
play-on-mount
Prompt
Add Atelier's Text Roll to my app.

If there is no components.json, run: npx shadcn@latest init -d
Then run: npx shadcn@latest add @atelier/text-roll
That writes the atelier-ui skill under .agents/skills and .claude/skills. Follow it.

Props: axis="y" mode="letters" direction="forward" stagger={0.01} duration={0.8} cycles={2} playOnHover={true} playOnScroll={true} playOnMount={true}

Just into your favorite coding agent and let Atelier do its magic. Live props are included.


This command will install all the dependencies this component uses.

npx shadcn@latest add @atelier/text-roll

Install the dependencies first, then feel free to copy the files into your project as you see fit.

npm install motion
text-roll.tsx
"use client"

import { animate, type Easing } from "motion"

const EASE: Easing = [0.84, 0, 0.22, 1]

import { type ComponentRef, useCallback, useEffect, useImperativeHandle, useRef } from "react"
import { type RenderProp, useRender } from "../../hooks/use-render"
import { TextSplit } from "../text-split/text-split"

type AnimationProps = {
    axis: "x" | "y"
    direction: "forward" | "backward" | "random"
    stagger: number
    duration: number
    cycles: number
}

export type TextRollProps = {
    children: string
    mode?: "letters" | "group"
    playOnScroll?: boolean
    playOnMount?: boolean
    playOnHover?: boolean
    render?: RenderProp
} & Partial<AnimationProps>

type DisplaceLetterProps = {
    ref: React.Ref<DisplaceLetterHandle>
    char: string
    enableHover: boolean
    onComplete?: () => void
} & Omit<AnimationProps, "stagger">

export type DisplaceLetterHandle = {
    play: (delay?: number) => void
}

function getDir(dir: TextRollProps["direction"]): 1 | -1 {
    if (dir === "random") return Math.random() > 0.5 ? 1 : -1
    if (dir === "forward") return 1
    return -1
}

function DisplaceLetter({
    ref,
    char,
    enableHover,
    axis,
    direction,
    duration,
    cycles,
    onComplete,
}: DisplaceLetterProps) {
    const isPlayingRef = useRef(false)
    const clonedCharsRef = useRef<(ComponentRef<"span"> | null)[]>([])
    const currentCharRef = useRef<ComponentRef<"span"> | null>(null)

    const startPlay = useCallback(
        async (delay = 0) => {
            if (isPlayingRef.current) return
            isPlayingRef.current = true

            const dir = getDir(direction)

            clonedCharsRef.current.forEach((clone, i) => {
                if (!clone) return
                if (axis === "y") {
                    clone.style.top = `${(i + 1) * dir * -100}%`
                    clone.style.left = "0"
                } else {
                    clone.style.left = `${(i + 1) * dir * -100}%`
                    clone.style.top = "0"
                }
            })

            await animate(
                [currentCharRef.current, ...clonedCharsRef.current.filter((span) => span !== null)],
                axis === "y"
                    ? { y: [`${dir * cycles * 100}%`, "0%"] }
                    : { x: [`${dir * cycles * 100}%`, "0%"] },
                {
                    duration,
                    delay,
                    ease: EASE,
                },
            )
            isPlayingRef.current = false
            onComplete?.()
        },
        [axis, direction, duration, cycles, onComplete],
    )

    useImperativeHandle(ref, () => ({ play: startPlay }), [startPlay])

    const handleHover = useCallback(() => {
        startPlay()
    }, [startPlay])

    return (
        <span
            suppressHydrationWarning
            onMouseEnter={enableHover ? handleHover : undefined}
            className={`${axis === "y" ? "overflow-y-clip" : "overflow-x-clip"} inline-block relative whitespace-pre`}
        >
            {Array.from({ length: cycles }, (_, i) => (
                <span
                    key={i}
                    ref={(clone) => {
                        clonedCharsRef.current[i] = clone
                    }}
                    aria-hidden={true}
                    className="absolute"
                    style={
                        axis === "y"
                            ? { top: `${(i + 1) * -100}%`, left: 0 }
                            : { left: `${(i + 1) * -100}%`, top: 0 }
                    }
                >
                    {char}
                </span>
            ))}

            <span ref={currentCharRef} className="block">
                {char}
            </span>
        </span>
    )
}

export function TextRoll({
    children,
    axis = "y",
    mode = "letters",
    direction = "random",
    playOnScroll = true,
    playOnMount = true,
    playOnHover = true,
    stagger = 0,
    duration = 0.8,
    cycles = 2,
    render,
}: TextRollProps) {
    const containerRef = useRef<ComponentRef<"span">>(null)
    const letterRefs = useRef<(DisplaceLetterHandle | null)[]>([])
    const isPlayingRef = useRef(false)
    const completedRef = useRef(0)

    const staggerRef = useRef(stagger)
    useEffect(() => {
        staggerRef.current = stagger
    }, [stagger])

    const handleLetterComplete = useCallback(() => {
        if (!isPlayingRef.current) return
        completedRef.current++
        if (completedRef.current >= letterRefs.current.length) {
            isPlayingRef.current = false
            completedRef.current = 0
        }
    }, [])

    const triggerPlay = useCallback(() => {
        if (isPlayingRef.current) return
        isPlayingRef.current = true
        completedRef.current = 0

        letterRefs.current.forEach((letter, index) => {
            letter?.play(staggerRef.current * index)
        })
    }, [])

    useEffect(() => {
        if (playOnMount) triggerPlay()
    }, [playOnMount, triggerPlay])

    useEffect(() => {
        if (!playOnScroll) return
        const container = containerRef.current
        if (!container) return
        let isFirstRender = true
        const obs = new IntersectionObserver(([entry]) => {
            if (isFirstRender) {
                isFirstRender = false
                return
            }
            if (entry.isIntersecting) triggerPlay()
        })
        obs.observe(container)
        return () => obs.disconnect()
    }, [playOnScroll, triggerPlay])

    return useRender({
        render,
        defaultElement: <span />,
        props: {
            ref: containerRef,
            onMouseEnter: playOnHover && mode === "group" ? triggerPlay : undefined,
            children: (
                <TextSplit
                    showMask={false}
                    splitBy="letters"
                    renderItems={(char, index) => (
                        <DisplaceLetter
                            ref={(letter) => {
                                letterRefs.current[index] = letter
                            }}
                            char={char}
                            enableHover={playOnHover && mode === "letters"}
                            direction={direction}
                            axis={axis}
                            duration={duration}
                            cycles={cycles}
                            onComplete={handleLetterComplete}
                        />
                    )}
                >
                    {children}
                </TextSplit>
            ),
        },
    })
}
use-render.ts
// biome-ignore-all lint/suspicious/noExplicitAny: prop merging is inherently dynamic
/**
 * Inspired by Base UI's `useRender` + `mergeProps`, intentionally simplified for this
 * library's scope at the moment.
 *
 * Chosen over polymorphic prop: cleaner TypeScript, integrates better with other
 * component (Next/Image, design systems, third-party UI libraries)
 *
 * @see https://base-ui.com/react/utils/use-render
 * @see https://base-ui.com/react/utils/merge-props
 */
import { cloneElement, isValidElement, type ReactElement, type Ref } from "react"

type AnyProps = Record<string, any>

type RenderFunction<S> = (props: AnyProps, state: S) => ReactElement

export type RenderProp<S = void> = ReactElement | RenderFunction<S>

type UseRenderOptions<S> = {
    render: RenderProp<S> | undefined
    props: AnyProps
    state?: S
    defaultElement: ReactElement
}

export function useRender<S = void>(options: UseRenderOptions<S>): ReactElement<AnyProps> {
    const { render, props, state, defaultElement } = options
    const target = render ?? defaultElement

    // Function form: consumer wires props themselves, no merging needed.
    if (typeof target === "function") {
        return target(props, state as S) as ReactElement<AnyProps>
    }

    // Element form: clone and merge our internal props with whatever the consumer set on the element.
    const targetProps = (isValidElement(target) ? target.props : {}) as AnyProps
    return cloneElement(target, mergeProps(props, targetProps)) as ReactElement<AnyProps>
}

function mergeProps(internal: AnyProps, external: AnyProps): AnyProps {
    const merged: AnyProps = { ...internal }

    for (const key in external) {
        const internalValue = internal[key]
        const externalValue = external[key]

        if (key === "className" && typeof externalValue === "string") {
            merged[key] = [internalValue, externalValue].filter(Boolean).join(" ")
        } else if (key === "style" && externalValue && typeof externalValue === "object") {
            merged[key] = { ...internalValue, ...externalValue }
        } else if (key === "ref") {
            merged[key] = composeRefs(internalValue, externalValue)
        } else if (
            key.startsWith("on") &&
            typeof internalValue === "function" &&
            typeof externalValue === "function"
        ) {
            // External handler runs first so consumers can stopPropagation before our logic fires.
            merged[key] = chainFunctions(externalValue, internalValue)
        } else {
            merged[key] = externalValue
        }
    }

    return merged
}

function chainFunctions(...fns: Array<(...args: any[]) => void>) {
    return (...args: any[]) => {
        for (const fn of fns) fn(...args)
    }
}

function composeRefs<T>(...refs: Array<Ref<T> | undefined>) {
    return (node: T) => {
        for (const ref of refs) {
            if (typeof ref === "function") ref(node)
            else if (ref != null) (ref as { current: T | null }).current = node
        }
    }
}
text-split.tsx
"use client"

import { Fragment, type ReactNode } from "react"
import { type RenderProp, useRender } from "../../hooks/use-render"

type SplitBy = "letters" | "words"

const NON_BREAKING_SPACE = " "

export type TextSplitProps = {
    children: string
    splitBy?: SplitBy
    showMask?: boolean
    renderItems?: (char: string, index: number) => ReactNode
    render?: RenderProp
}

function Mask({ children, showMask }: { children: ReactNode; showMask: boolean }) {
    if (!showMask) return children
    return <span className="overflow-clip">{children}</span>
}

export function TextSplit({
    children,
    splitBy = "letters",
    showMask = true,
    renderItems,
    render,
}: TextSplitProps) {
    const words = children.split(" ")
    let cursor = 0

    const content = words.map((word, wordIndex) => {
        const isLast = wordIndex === words.length - 1

        if (splitBy === "words") {
            return (
                <Mask showMask={showMask} key={wordIndex}>
                    {renderItems ? renderItems(word, wordIndex) : word}
                    {!isLast && " "}
                </Mask>
            )
        }

        const letters = Array.from(word).map((char) => {
            const index = cursor++
            return (
                <Mask showMask={showMask} key={index}>
                    {renderItems ? renderItems(char, index) : char}
                </Mask>
            )
        })

        let spacer: ReactNode = null
        if (!isLast) {
            const index = cursor++
            spacer = (
                <Mask showMask={showMask} key={index}>
                    {renderItems ? renderItems(" ", index) : NON_BREAKING_SPACE}
                </Mask>
            )
        }

        return (
            <Fragment key={wordIndex}>
                <span className="inline-block">
                    {letters}
                    {spacer}
                </span>
                {!isLast && <wbr />}
            </Fragment>
        )
    })

    return useRender({
        render,
        defaultElement: <span />,
        props: { children: content },
    })
}

Each letter rolls through its characters into place on hover, mount and scroll.

<TextRoll>Enter your text here</TextRoll>

Choose the wrapper element

Pass render to choose the wrapper element. Your props are merged with the component's, so it stays the right semantic tag while keeping the animation. Without render the text renders inside a <span>.

<TextRoll render={<p className="text-4xl" />}>Enter your text here</TextRoll>

Each letter is wrapped in an overflow-clip span. Some descenders and ascenders (g, p, t, f) can get clipped. Increase line-height / leading on the parent if needed.


NameTypeDefaultDescription
childrenstring—The text content to animate.
axis"x" | "y""y"Axis along which letters roll.
mode"letters" | "group""letters"Animate each letter independently on hover, or the entire group at once.
direction"forward" | "backward" | "random""forward"Roll direction.
playOnScrollbooleantrueTrigger the animation when the element enters the viewport.
playOnMountbooleantrueTrigger the animation on mount.
playOnHoverbooleantrueTrigger the animation on hover.
staggernumber0.01Delay in seconds between each letter's animation start.
durationnumber0.8Duration of each letter's roll animation in seconds.
cyclesnumber1Number of times the letter rolls before settling.
renderReactElement | function<span/>Override the wrapper element.

Motion
React animation library.

Text Split (Atelier)
A utility that splits text for animation.

Star on githubBuy me a coffee