---
url: https://react-native-text-motion.pages.dev/guide/getting-started/overview.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Overview
`@react-native-motion-kit/text-motion` creates reusable animated text components for React Native. Compose text splitting, rendering, timing, effects, and accessibility in a recipe, then render the result as a component.
```txt
split → layout(renderer) → timeline → effect → motion/accessibility → component
```
This documentation describes the current `0.1.0` public API.
## Choose your starting point
Use a [preset](https://react-native-text-motion.pages.dev/guide/usage/presets.md) for common title, label, and product-copy animation. Use a [custom recipe](https://react-native-text-motion.pages.dev/guide/usage/recipes.md) when you need to choose the motion unit, timing, or effects.
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroTitle = editorialRise().component();
export function Hero() {
return Design motion that feels native;
}
```
The component accepts a plain string child. Define it outside your React render function so a parent rerender reuses the same component type.
## What you can build
| Need | Public API |
| -------------------------------------------------------------- | ------------------------------------------------------------- |
| Animate words or user-perceived characters | `words()` or `graphemes()` with `nativeText()` |
| Reveal the lines React Native actually wraps | `overlayText()` with `lineReveal()`, without `.split(...)` |
| Reveal characters while reserving the complete phrase's layout | `graphemes()`, `nativeText()`, and `typewriter()` |
| Replay after a button or another app event | `useTextMotionControls()` and the `controls` prop |
| Follow scroll, gestures, or another app-owned animation | A Reanimated shared value passed as `progress` |
| Keep the phrase readable to screen readers | Parent-label accessibility with decorative token nodes hidden |
`controls` sends playback commands; `progress` supplies the current visual state. An instance accepts one of these playback inputs at a time.
## Scope and limits
The intended workloads are short titles, headings, labels, onboarding copy, and product descriptions. Measure long paragraphs, many rows, and large grapheme counts on your target devices before adopting them.
`nativeText()` uses containers around moving tokens and does not reproduce every behavior of a single native `Text`. Rich nested children, inline links, selectable text, and text `onPress` are outside the component contract. `lines()` splits explicit `\n` characters only; use `overlayText()` for automatic wrapping.
The current public API does not include custom effect factories, a renderer-extension SDK, Skia effects, `pause`/`seek`/`reverse`, or built-in scroll, gesture, screen-focus, and in-view drivers. Apps can connect their own events through `controls` and continuous shared values through `progress`. Text changes are enter-only; the library does not retain old text for exit animation or provide a streaming-text API.
Continue with [installation](https://react-native-text-motion.pages.dev/guide/getting-started/installation.md), then create your first component in the [quick start](https://react-native-text-motion.pages.dev/guide/getting-started/quick-start.md).
For the library's development priorities and design boundaries, see the [roadmap](https://react-native-text-motion.pages.dev/guide/getting-started/roadmap.md).
---
url: https://react-native-text-motion.pages.dev/guide/getting-started/installation.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Installation
Text Motion uses React Native Reanimated and React Native Worklets. Set up compatible versions of these dependencies in your app before rendering animated text.
## Requirements
The package declares these peer dependency minimums:
| Dependency | Declared range |
| ------------------------- | -------------- |
| `react` | `>=18.0.0` |
| `react-native` | `>=0.76.0` |
| `react-native-reanimated` | `>=4.0.0` |
| `react-native-worklets` | `>=0.5.0` |
These ranges are not a compatibility matrix. Choose a React Native, Reanimated, and Worklets combination supported by the [Reanimated compatibility table](https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/). Reanimated 4 requires the React Native New Architecture.
## Install the packages
For an existing React Native app:
```sh
pnpm add @react-native-motion-kit/text-motion react-native-reanimated react-native-worklets
```
With npm or Yarn, use the equivalent `npm install` or `yarn add` command.
For an Expo app, let Expo choose the Reanimated and Worklets versions for your SDK:
```sh
npx expo install react-native-reanimated react-native-worklets
pnpm add @react-native-motion-kit/text-motion
```
Check that your SDK's selected versions satisfy the peer ranges above. Follow the [Expo Reanimated guide](https://docs.expo.dev/versions/latest/sdk/reanimated/) for the setup required by your SDK and build type.
## Configure Worklets
Follow the official [Reanimated getting-started guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) and [Worklets getting-started guide](https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started/) for your environment.
In a bare React Native app using Babel, add the Worklets plugin as the **last** plugin in the existing configuration:
```js
module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: ['react-native-worklets/plugin'],
};
```
Preserve any other presets and plugins your app needs. Expo's Babel preset may configure this for your SDK; use the SDK-specific setup rather than adding a duplicate plugin.
After adding native dependencies, install iOS pods through your app's existing CocoaPods workflow and rebuild the native app. Restart Metro with its cache reset if the Babel configuration changed. Text Motion itself does not require an additional Babel plugin, provider, or native configuration.
## Import from the public entrypoints
```tsx
import {
defineTextMotion,
fade,
nativeText,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
```
Built-in primitives come from the package root. The three presets come from `/presets`. Do not import internal renderer or descriptor files.
Continue to the [quick start](https://react-native-text-motion.pages.dev/guide/getting-started/quick-start.md).
---
url: https://react-native-text-motion.pages.dev/guide/getting-started/quick-start.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Quick Start
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Complete [installation](https://react-native-text-motion.pages.dev/guide/getting-started/installation.md), then choose a preset or create a recipe. Both approaches return a reusable React component.
## Start with a preset
`editorialRise()`React Native Web
Run example
View code
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroReveal = editorialRise().component();
export function HeroTitle() {
return (
Design motion that feels native
);
}
```
`editorialRise()` uses word tokens, a centered stagger, and combined rise, fade, and scale effects. The component autoplays when it mounts.
## Create a word reveal
`words()`React Native Web
Run example
View code
```tsx
import {
defineTextMotion,
fade,
nativeText,
parentLabelPolicy,
rise,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const WordReveal = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(fade().and(rise({ y: 12 })))
.motion({ kind: 'timing', options: { duration: 420 } })
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function Headline() {
return Make every word count;
}
```
The timeline uses **seconds**: `stagger(0.04)` starts visible words 40ms apart. Motion `duration` uses **milliseconds**: each token animates for 420ms after its delay. Whitespace keeps its layout space without taking a delay slot. The accessibility policy exposes the complete phrase once and shows the final state when reduced motion is enabled.
## Reveal actual rendered lines
`overlayText() + lineReveal()`iOS recording
View code
Use `overlayText()` when width and font settings should determine the animated lines. This renderer owns line measurement, so omit `.split(...)`.
```tsx
import {
defineTextMotion,
lineReveal,
overlayText,
stagger,
} from '@react-native-motion-kit/text-motion';
const LineTitle = defineTextMotion()
.layout(overlayText())
.timeline(stagger(0.08))
.effect(lineReveal({ y: 18 }))
.motion({ kind: 'timing', options: { duration: 420 } })
.component();
export function ResponsiveTitle() {
return (
Motion follows the lines your layout creates
);
}
```
`lines()` is different: it splits only explicit newline characters and does not measure wrapping.
## Next steps
- Learn how [recipes](https://react-native-text-motion.pages.dev/guide/usage/recipes.md) compose and how to customize [presets](https://react-native-text-motion.pages.dev/guide/usage/presets.md).
- Add [playback controls or external progress](https://react-native-text-motion.pages.dev/guide/usage/playback.md).
- Compare [renderers](https://react-native-text-motion.pages.dev/api/renderers.md), [effects](https://react-native-text-motion.pages.dev/api/effects.md), and [component props](https://react-native-text-motion.pages.dev/api/component-props.md).
---
url: https://react-native-text-motion.pages.dev/guide/getting-started/ai.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# AI
Give your AI assistant the Text Motion documentation when asking for help with recipes, presets, playback, or troubleshooting.
## llms.txt
This site publishes two files for AI tools:
- [llms.txt](https://react-native-text-motion.pages.dev/llms.txt): a structured index with links to individual documentation pages. Use it when your assistant can fetch the pages it needs, keeping context small.
- [llms-full.txt](https://react-native-text-motion.pages.dev/llms-full.txt): the complete English documentation in one file. Use it for questions spanning several features or larger refactors, with a higher context cost.
Copy the URL that fits your task:
```txt
https://react-native-text-motion.pages.dev/llms.txt
https://react-native-text-motion.pages.dev/llms-full.txt
```
## Markdown docs
Every documentation page also has a Markdown version. For help with one feature, provide only the relevant page:
```txt
https://react-native-text-motion.pages.dev/guide/getting-started/quick-start.md
https://react-native-text-motion.pages.dev/guide/usage/recipes.md
https://react-native-text-motion.pages.dev/guide/usage/playback.md
```
If your assistant cannot fetch URLs, open the file and paste its contents or attach it as context.
## Example prompt
```txt
Read https://react-native-text-motion.pages.dev/guide/getting-started/quick-start.md.
Create a React Native word reveal using defineTextMotion(), words(), nativeText(),
stagger(), and fade().and(rise()). Include the imports and an accessible example.
Use the documented API and explain the timing units.
```
## Library development context
For changes to Text Motion itself, start with the [roadmap guide](https://react-native-text-motion.pages.dev/guide/getting-started/roadmap.md), which links to the repository's project context and planning sections. It records current priorities, design boundaries and deferred candidates; deferred items are not release promises.
For ongoing proposals and the reasoning behind priorities, consult the [roadmap discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10).
---
url: https://react-native-text-motion.pages.dev/guide/getting-started/roadmap.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Roadmap
Join the [project direction and roadmap discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10) to propose features, compare priorities and discuss design decisions.
The library's priorities, scope and design decisions are maintained in the repository's [project context and roadmap](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md).
The current priority is verifying renderer performance and platform behavior on iOS and Android, then using that evidence to decide which additional APIs belong in the library.
## Find the development context
| Topic | Source |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What to work on next | [Current priority](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md#current-priority) |
| How to measure and classify performance evidence | [Renderer performance checkpoint](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md#renderer-performance-checkpoint) |
| Implemented public scope | [Stable MVP](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md#stable-mvp) |
| Deferred candidates and deliberately excluded APIs | [Deferred](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md#deferred) |
| What belongs in Text Motion or a separate package | [Scope and roadmap](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.md#scope--roadmap) |
Deferred candidates are not release promises. For implemented behavior and supported APIs, use this site's [API reference](https://react-native-text-motion.pages.dev/api/recipe.md).
The repository roadmap preserves the original README context and links to its source revision. Keep detailed planning there so it can evolve in one place.
---
url: https://react-native-text-motion.pages.dev/guide/usage/recipes.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Recipes
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
`defineTextMotion()` starts an immutable builder. Each chain method returns a new builder, so you can share a base recipe and create variations without changing the base.
## Build a component
```tsx
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const base = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(fade());
const SoftTitle = base
.motion({ kind: 'timing', options: { duration: 360 } })
.component();
const RisingTitle = base
.effect(rise({ y: 12 }))
.motion({ kind: 'spring', options: { damping: 16, stiffness: 140 } })
.component();
export function Titles() {
return (
<>
A soft entranceA little more movement
>
);
}
```
Define generated components at module scope. Calling `.component()` during render creates a new component type and can cause remounts and unintended autoplay.
## What each stage controls
| Stage | Responsibility |
| --------------------- | ----------------------------------------------------------------- |
| `.split(...)` | Source token boundaries for `nativeText()` |
| `.layout(...)` | Renderer and its supported motion units/effects |
| `.timeline(...)` | Per-token start delays, in seconds |
| `.effect(...)` | Add an effect; repeated calls accumulate effects |
| `.motion(...)` | Internal autoplay and controls-driven timing or spring playback |
| `.accessibility(...)` | Parent label, decorative tokens, and reduced-motion policy |
| `.component()` | Produce a React component that accepts a string child |
| `.recipe()` | Read a recipe configuration snapshot without creating a component |
Calling `.split()`, `.layout()`, `.timeline()`, `.motion()`, or `.accessibility()` again replaces that setting on the new builder. `.effect()` adds to the existing effects instead. `.recipe()` can be used before layout; treat its returned configuration as a snapshot rather than mutating it to update a component.
## Choose a renderer first
TypeScript exposes `.component()` only after `.layout(...)` selects a renderer. Choose the renderer before `.effect(...)` so its capability constraints guide effect selection.
With `nativeText()`, an explicit splitter chooses words, graphemes, custom tokens, or authored newline units. Without a splitter, the entire input is one source token. The default is not word splitting.
With `overlayText()`, the renderer derives units from measured native lines. Do not add `.split(...)`, even if you want to animate lines. The type system prevents the incompatible chain and runtime checks also reject it.
## Compose compatible effects
`fade().and(rise()).and(scale())`React Native Web
Run example
View code
Both `.effect(fade().and(rise()))` and `.effect(fade()).effect(rise())` add fade and rise behavior. Built-in `fade`, `rise`, `slide`, `scale`, `pulse`, and `shake` work with both renderers. `typewriter()` requires `nativeText()`; `lineReveal()` requires `overlayText()`.
Splitters, timelines, effects, and renderers are opaque public handles. Pass them to the builder rather than accessing internal descriptors. The root API does not export custom effect factories or a renderer-extension SDK.
## Configure playback
`.motion({ kind: 'spring' })`React Native Web
Run example
View code
```tsx
import { defineTextMotion, fade, nativeText } from '@react-native-motion-kit/text-motion';
const TimedText = defineTextMotion()
.layout(nativeText())
.effect(fade())
.motion({ kind: 'timing', options: { duration: 400 } })
.component();
const SpringText = defineTextMotion()
.layout(nativeText())
.effect(fade())
.motion({ kind: 'spring', options: { damping: 16, stiffness: 140 } })
.component();
export function Message() {
return (
<>
The whole phrase fades togetherThe same unit follows a spring
>
);
}
```
Motion options follow the relevant Reanimated timing or spring configuration, except `reduceMotion`, which belongs to the accessibility policy. Timeline delays use seconds; timing `duration` uses milliseconds. Function-valued options such as easing are compared by reference: reuse the same function when rerenders should preserve playback.
Passing `progress` to an instance gives the app ownership of playback and bypasses `.motion()` for that instance. Use `controls` for discrete commands while retaining recipe-owned playback. See [playback](https://react-native-text-motion.pages.dev/guide/usage/playback.md) and the [recipe API](https://react-native-text-motion.pages.dev/api/recipe.md).
---
url: https://react-native-text-motion.pages.dev/guide/usage/presets.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Presets
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Presets are recipe factories from `@react-native-motion-kit/text-motion/presets`. Each factory returns a builder with words, `nativeText()`, a timeline, and effects already selected. Call `.component()` to create a component, or customize the builder first.
```tsx
import {
editorialRise,
gentleEmphasis,
softWave,
} from '@react-native-motion-kit/text-motion/presets';
const HeroTitle = editorialRise().component();
const ProductCopy = softWave().component();
const Label = gentleEmphasis().component();
export function ProductHeader() {
return (
<>
Give your words a little motionReusable animation for short product copy
>
);
}
```
## Built-in recipes
| Factory | Timeline | Effects |
| ------------------ | ------------------------------------------ | ---------------------------------------------------- |
| `editorialRise()` | `stagger(0.032, { from: 'center' })` | `rise({ y: 14 })`, `fade()`, `scale({ from: 0.98 })` |
| `softWave()` | `wave({ amplitude: 0.06, wavelength: 5 })` | `fade()`, `rise({ y: 8 })` |
| `gentleEmphasis()` | `stagger(0.024)` | `pulse({ scale: 1.06 })`, `fade()` |
All three factories take no arguments. Their delay values use seconds. They do not select a custom `.motion()` or accessibility policy, so the renderer defaults apply unless you configure them.
`editorialRise()` suits titles that should unfold from the center. `softWave()` varies word start times for a softer rhythm. `gentleEmphasis()` briefly scales tokens near the midpoint and returns to the final scale; it does not loop.
## Preview the presets
### `editorialRise()`
`editorialRise()`React Native Web
Run example
View code
### `softWave()`
`softWave()`React Native Web
Run example
View code
### `gentleEmphasis()`
`gentleEmphasis()`React Native Web
Run example
View code
## Customize a preset
```tsx
import {
parentLabelPolicy,
stagger,
} from '@react-native-motion-kit/text-motion';
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const base = editorialRise();
const StandardTitle = base.component();
const SlowerTitle = base
.timeline(stagger(0.06, { from: 'start' }))
.motion({ kind: 'timing', options: { duration: 500 } })
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function Titles() {
return (
<>
Centered by defaultA slower entrance from the start
>
);
}
```
Builders are immutable, so the customized variation does not change `StandardTitle`. A later `.timeline(...)` replaces the preset timeline. A later `.effect(...)` adds to its effects instead of replacing them. Start with `defineTextMotion()` when you want a different effect set or a rendered-line recipe with `overlayText()`.
Presets use the same [component props](https://react-native-text-motion.pages.dev/api/component-props.md) and [playback inputs](https://react-native-text-motion.pages.dev/guide/usage/playback.md) as custom recipes. Keep generated components outside render functions and pass text as a plain string child.
---
url: https://react-native-text-motion.pages.dev/guide/usage/playback.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Playback
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Choose who owns playback: the component, an event, or an app-owned Reanimated shared value.
| Mode | Input | Playback owner |
| ----------------- | --------------------- | --------------------------------------------------------- |
| Autoplay | No playback prop | Text Motion starts playback when inputs change. |
| Commands | `controls={controls}` | Your app sends commands; Text Motion executes the recipe. |
| External progress | `progress={progress}` | Your app owns the value and its animation curve. |
## Autoplay and text updates
`Autoplay`React Native Web
Run example
View code
On mount, visible animated tokens play from their initial styles to their final styles. Passing `controls` keeps this mount autoplay; it does not make a component wait for its first command.
- Rerendering the same text with the same recipe preserves playback already in progress.
- Changing text replays the affected token animations, including replacements with the same token shape.
- Changing effective effects, timing, or motion configuration resets affected tokens and uses the new configuration. Function-valued motion options, such as easing functions, are reference-sensitive; reuse their references when playback should continue.
- Whitespace and static tokens keep their layout but do not animate or consume a motion index.
Text changes are enter-only. There is no exit animation, crossfade, or old/new token transition. In external-progress mode, new text uses the current shared value instead of starting autoplay. Commands always target the currently rendered text.
Create recipe components outside render so React can preserve their identity. See [Recipes](https://react-native-text-motion.pages.dev/guide/usage/recipes.md).
## Event-driven controls
`play() / replay() / reset() / stop()`React Native Web
Run example
View code
`useTextMotionControls()` returns a stable command channel. Pass it explicitly to each component that should receive commands.
```tsx
import { Button, View } from 'react-native';
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
useTextMotionControls,
words,
} from '@react-native-motion-kit/text-motion';
const Reveal = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(fade().and(rise({ y: 12 })))
.motion({ kind: 'timing', options: { duration: 420 } })
.component();
export function Headlines() {
const controls = useTextMotionControls();
return (
A title with shared playbackA subtitle with the same command channel
);
}
```
| Command | Behavior |
| ---------- | ------------------------------------------------------------------------- |
| `play()` | Plays from the current progress toward the final state. |
| `replay()` | Resets and plays again with the recipe timeline and motion configuration. |
| `reset()` | Cancels playback and returns to the initial state. |
| `stop()` | Cancels playback and keeps the current visual state. |
Commands broadcast to every mounted component attached to that controls object; each uses its own recipe. Commands are not a stored playback state or a queue for future mounts. Components unsubscribe when detached or unmounted.
`stop()` followed by `play()` is not a precise pause/resume API and does not promise the original remaining schedule. Use `replay()` for a complete restart. With the explicit reduced-motion final-state policy active, the final visible state takes priority over reset and replay.
Use controls for buttons, screen-focus events wired by your app, or onboarding steps. There is no provider/context playback API or public component-ref playback API.
## App-owned progress
`progress`React Native Web
Run example
View code
Use a Reanimated `SharedValue` when text should follow another animation, a scroll value, or a gesture value your app already owns.
```tsx
import { Button, View } from 'react-native';
import { useSharedValue, withTiming } from 'react-native-reanimated';
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const ProgressReveal = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.08))
.effect(fade().and(rise({ y: 12 })))
.component();
export function ProgressExample() {
const progress = useSharedValue(0);
return (
Progress drives the whole phrase
);
}
```
`0` renders initial styles and `1` renders final styles. Finite values outside that range are clamped; non-finite values are treated as `0`. Passing `progress` disables internal autoplay and ignores the recipe's `.motion()` configuration for that instance. Set duration and easing where you update the shared value.
The value represents the whole effect timeline. For a token delay `d` and largest token delay `D` in seconds, the current mapping uses a fixed per-token span of `1.0`:
```txt
localProgress = clamp(progress * (D + 1) - d, 0, 1)
```
Timelines still shape when each token starts. Whitespace does not take a delay slot. This is not a per-token duration API.
### Typewriter progress
`typewriter() + progress`React Native Web
Run example
View code
The preview shows **timeline progress** and **visible characters** separately. The character count excludes spaces and includes punctuation and emoji; it updates during playback and when you move progress backward.
`typewriter()` shows a token once its local progress is greater than zero. Progress is **not the fraction of characters visible**: for ten visible characters with `stagger(0.05)`, all are visible just after about `0.310345`. Moving progress backward across a start threshold hides that character again. Use a linear external timing curve for evenly spaced threshold crossings in time.
The effect preserves the completed phrase's layout. It does not add a cursor or provide text streaming. See [Effects](https://react-native-text-motion.pages.dev/api/effects.md) and [Examples](https://react-native-text-motion.pages.dev/guide/usage/examples.md).
## Boundaries
`controls` and `progress` are mutually exclusive in TypeScript and at runtime. There are no first-class `pause`, `seek`, `reverse`, scroll, gesture, in-view, or screen-focus drivers. Integrate your own events with controls or your own continuous values with progress.
For reduced-motion behavior, see [Accessibility](https://react-native-text-motion.pages.dev/guide/usage/accessibility.md). For supported text and accessibility props, see [Component props](https://react-native-text-motion.pages.dev/api/component-props.md).
---
url: https://react-native-text-motion.pages.dev/guide/usage/accessibility.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Accessibility
Text Motion treats animated token nodes as decoration. By default, the parent exposes the complete phrase as one accessible label and the individual animated nodes are hidden from accessibility tools. A screen reader should read the phrase once, rather than announcing each word or character.
## Parent-label policy
`parentLabelPolicy(options?)` configures this behavior for a recipe. Its only option is `reducedMotion`.
| Option | Default | Meaning |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------- |
| `reducedMotion` | `'system'` | Uses Reanimated's system reduced-motion behavior for internal animations. |
| `reducedMotion: 'final-state'` | Opt-in | When system reduced motion is enabled, renders the final visual state immediately. |
```tsx
import {
defineTextMotion,
fade,
nativeText,
parentLabelPolicy,
rise,
words,
} from '@react-native-motion-kit/text-motion';
const AccessibleTitle = defineTextMotion()
.split(words())
.layout(nativeText())
.effect(fade().and(rise({ y: 10 })))
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function Title() {
return (
Motion that keeps the message readable
);
}
```
`'final-state'` does not disable motion for everyone. It skips to the final state when the device's reduced-motion setting is enabled. That visual state also takes priority over controls and external progress, so a Typewriter phrase remains fully readable even when the app's shared value is still `0`.
With `nativeText()` and the default `'system'` policy, an external `progress` value remains app-owned. Configure its animation curve to respect the user's preference, or choose `'final-state'` when the rendered text must immediately show the complete result.
`overlayText()` has an additional renderer-level fallback: whenever system reduced motion is enabled, it renders the original final paragraph instead of animated line overlays. This applies with either policy and with external progress, and does not change the app's shared value.
Do not pass `reduceMotion` to `.motion()` options. Text Motion exposes reduced-motion behavior through `.accessibility(...)` instead.
## Labels and text props
The string child supplies the default accessible label. An explicit `accessibilityLabel` can describe text whose visual wording is abbreviated. Supported accessibility props also include `accessibilityHint`, `accessibilityRole`, `accessibilityState`, `accessibilityValue`, `accessibilityActions`, `accessibilityLanguage`, and `onAccessibilityAction`.
`allowFontScaling` and `maxFontSizeMultiplier` are supported. Verify larger font scales and narrow widths in your app, especially for rendered-line motion. See [Component props](https://react-native-text-motion.pages.dev/api/component-props.md) for the complete prop contract and [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md) for layout differences.
## Check in your app
- Read the phrase using VoiceOver and TalkBack; confirm that decorative words and characters are not announced separately.
- Enable reduced motion and check the initial frame, replay, reset, and externally controlled states.
- Check your supported font scales, languages, widths, and contrast in the surrounding UI.
- Keep essential information readable independently of the decorative motion. Typewriter does not emit per-character announcements.
---
url: https://react-native-text-motion.pages.dev/guide/usage/segmentation.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Text segmentation
Choose token boundaries before choosing their motion. A JavaScript code unit is not necessarily a visible character: emoji, combining accents, and decomposed Hangul can contain several code points.
## Built-in splitting
| Splitter | Unit | When to use it |
| ------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `words()` | Word, punctuation, and spacing tokens | Readable word-based headings and product copy. |
| `graphemes()` | Grapheme-aware tokens | Short character-level reveals and Typewriter. |
| `lines()` | Explicit newline-separated source units | Experimental hard-newline motion; it does not detect wrapping. |
| `custom(fn)` | App-defined strings or token objects | Product-specific boundaries or a different segmentation implementation. |
Whitespace keeps its layout space without consuming an animation delay slot. Punctuation can be a visible animated unit. See [Splitters](https://react-native-text-motion.pages.dev/api/splitters.md) for signatures and token metadata.
For automatic wrapping based on width and fonts, use `overlayText()` without `.split(...)`. See [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md).
## `Intl.Segmenter` and fallback behavior
`words()` and `graphemes()` use `Intl.Segmenter` when the runtime provides it. React Native/Hermes availability varies, so the package also includes a small fallback tokenizer. Your app does not need a polyfill merely to avoid a startup crash when `Intl.Segmenter` is absent.
The fallback preserves decomposed Hangul syllable sequences such as `한`, including relevant precomposed-Hangul/Jamo boundaries, without normalizing or rewriting the input. It handles common combining marks and emoji sequences, but it is not a complete implementation of Unicode grapheme or locale-aware word-boundary rules. Some Indic conjuncts, such as `क्ष`, can still split; scripts without spaces may need more precise word segmentation.
If exact boundaries matter, provide an `Intl.Segmenter` implementation in your app entrypoint before rendering Text Motion, or use `custom()` with an app-chosen tokenizer. An app may choose a polyfill such as `@formatjs/intl-segmenter`; it is not installed by this library.
## Preserve the original text
Custom splitters should preserve spacing and token order. For example, a product may choose whitespace-delimited units while keeping each whitespace run:
```tsx
import {
custom,
defineTextMotion,
fade,
nativeText,
stagger,
} from '@react-native-motion-kit/text-motion';
const PhraseReveal = defineTextMotion()
.split(custom((input) => input.match(/\S+|\s+/gu) ?? []))
.layout(nativeText())
.timeline(stagger(0.06))
.effect(fade())
.component();
export function Phrase() {
return Keep the original spacing.;
}
```
This example groups punctuation with its neighboring non-whitespace text. It is a deliberate app rule, not full linguistic word segmentation. `custom()` also accepts token objects with explicit source ranges and metadata when that information matters.
Correct segmentation alone does not make per-token rendering equivalent to a single native `Text`. Shaping, ligatures, bidirectional text, wrapping, and complex scripts need visual verification with the chosen renderer. See [Performance](https://react-native-text-motion.pages.dev/guide/usage/performance.md) for the example app's layout probes.
---
url: https://react-native-text-motion.pages.dev/guide/usage/performance.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Performance
Text Motion is intended for short, high-value UI text: titles, labels, onboarding copy, and concise product copy. Performance depends on the number of animated units, effects, simultaneous components, device, and playback mode. This documentation does not promise an FPS target or a universal safe character count.
## Choose the unit deliberately
`nativeText()` uses an animated `View` container with an inner `Text` for each animated token. Static tokens remain plain text. This makes token transforms visible, but a grapheme split can create many more animated units than a word split.
- Prefer `words()` when whole-word motion communicates the intent.
- Use `graphemes()` or `typewriter()` for short character-level reveals and measure larger workloads.
- Keep recipe components outside render. Replay existing components with controls instead of repeatedly remounting them solely to restart motion.
- Test shared controls with the actual number of mounted rows: one command broadcasts to all attached components.
- Use `overlayText()` when the motion should follow rendered lines. It measures native text and renders clipped paragraph copies per line; fewer motion units alone do not establish that it will be faster for your layout.
See [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md) for the layout tradeoffs and [Playback](https://react-native-text-motion.pages.dev/guide/usage/playback.md) for command and progress ownership.
## Profile the example app
Run the repository example on the platform you want to measure. See [Examples](https://react-native-text-motion.pages.dev/guide/usage/examples.md) for commands.
Open **Playback → Renderer Performance**. The probe includes word and grapheme workloads, Typewriter, repeated replay, shared rows, and externally driven progress. **Playback → Controls Stress** provides additional command fan-out cases. **Layout → Line Reveal** and **Layout → Line Layout Probe** help inspect width, alignment, font-scale, hard-newline, and language behavior.
The case labels `normal`, `caution`, and `stress` describe probe workloads. They are not measured performance grades or supported token limits. Token/node estimates in the UI are diagnostics, not a public implementation contract.
Use a real FPS/profiling source such as React Native Perf Monitor, Xcode Instruments, Android Studio Profiler, or Flashlight. Record device and OS, platform, build mode, text/splitter, effect, number of components and motion units, playback mode, and visible jank alongside the measurement. Development and simulator results should be identified as such.
## Report evidence consistently
| Status | Required evidence |
| ------------- | --------------------------------------------------------------------------------------------- |
| `measured` | The same case family has both iOS and Android evidence. |
| `provisional` | Only one platform was checked, or evidence is limited to simulator/emulator/development mode. |
| `unknown` | That case family has not been measured. |
This site does not claim that a workload has been measured unless platform evidence accompanies that result.
If normal title and label workloads are smooth, keep the default renderer and document the boundary for heavier text. If normal workloads jank, investigate renderer costs before adding more effects. A failing grapheme stress case alone does not prove that ordinary word-based headings need a different renderer.
## Validate layout as well as frames
`nativeText()` trades exact single-`Text` shaping and wrapping for per-token transforms. `overlayText()` follows native rendered lines but should still be checked with the fonts, scale, width, alignment, and scripts your app uses. Frame rate cannot establish correct wrapping, accessible reading order, or reduced-motion behavior. See [Segmentation](https://react-native-text-motion.pages.dev/guide/usage/segmentation.md) and [Accessibility](https://react-native-text-motion.pages.dev/guide/usage/accessibility.md).
---
url: https://react-native-text-motion.pages.dev/guide/usage/examples.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Examples
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
These examples use the current public API. Run them in a React Native app after [installation](https://react-native-text-motion.pages.dev/guide/getting-started/installation.md). Use each preview to inspect the motion and replay it alongside the code.
## Start with a preset
`editorialRise()`React Native Web
Run example
View code
Presets are recipe factories imported from the `/presets` subpath. Create the component once outside render.
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroTitle = editorialRise().component();
export function Hero() {
return (
Design motion that feels native
);
}
```
See [Presets](https://react-native-text-motion.pages.dev/guide/usage/presets.md) for `softWave()` and `gentleEmphasis()`.
## Word reveal with replay
`play() / replay() / reset() / stop()`React Native Web
Run example
View code
```tsx
import { Button, View } from 'react-native';
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
useTextMotionControls,
words,
} from '@react-native-motion-kit/text-motion';
const WordReveal = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(fade().and(rise({ y: 10 })))
.motion({ kind: 'timing', options: { duration: 360 } })
.component();
export function ReplayExample() {
const controls = useTextMotionControls();
return (
A little motion, word by word.
);
}
```
`stagger(0.04)` sets starts 40ms apart; `duration: 360` controls each token's motion in milliseconds. Mount autoplay remains enabled with controls. See [Playback](https://react-native-text-motion.pages.dev/guide/usage/playback.md) for external progress and the full command set.
## Reveal rendered lines
`overlayText() + lineReveal()`iOS recording
View code
Use native rendered lines when a title should wrap with the available width. Do not add a splitter to this recipe.
```tsx
import { View } from 'react-native';
import {
defineTextMotion,
lineReveal,
overlayText,
parentLabelPolicy,
stagger,
} from '@react-native-motion-kit/text-motion';
const LineTitle = defineTextMotion()
.layout(overlayText())
.timeline(stagger(0.08))
.effect(lineReveal({ y: 18 }))
.motion({ kind: 'timing', options: { duration: 420 } })
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function RenderedLinesExample() {
return (
Let the title follow the lines your layout actually renders
);
}
```
`overlayText()` measures the paragraph after width, font, font scale, and shaping are applied. `lines()` only splits explicit newline characters. See [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md).
## Keep progress while the paragraph reflows
`overlayText() · width reflow`iOS recording
View code
The iOS recording uses a long English paragraph with no explicit newlines. In the native example, **Narrow** and **Wide** switch between React Native layout widths of `220` and `320`. Progress controls hold `progress` at `0.5` across the width change, then replay at each width so you can inspect the masks against the newly measured source paragraph.
## Typewriter with fixed layout
`typewriter()`React Native Web
Run example
View code
```tsx
import { Button, View } from 'react-native';
import {
defineTextMotion,
graphemes,
nativeText,
parentLabelPolicy,
stagger,
typewriter,
useTextMotionControls,
} from '@react-native-motion-kit/text-motion';
const TypewriterText = defineTextMotion()
.split(graphemes())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(typewriter())
.motion({ kind: 'timing', options: { duration: 0 } })
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function Greeting() {
const controls = useTextMotionControls();
return (
Hello, 한글! 👩🏽💻
);
}
```
The complete phrase reserves its space from the start. Each visible token is revealed at its timeline start; spaces and hard newlines keep their space without taking a delay slot. `duration: 0` makes the per-token reveal instant. Typewriter requires `nativeText()` and does not provide a cursor, streaming, or exact single-`Text` wrapping.
For a different phrase that must type from the beginning, remount it with a new React `key`. Appending text is not a streaming API. See [Effects](https://react-native-text-motion.pages.dev/api/effects.md) for composition and [Segmentation](https://react-native-text-motion.pages.dev/guide/usage/segmentation.md) for grapheme fallback limits.
## Run the repository example
From the repository root, use the pinned Node and pnpm versions in `.nvmrc` and `package.json`:
```sh
pnpm install
pnpm example start
# Or build and launch the native app:
pnpm example ios
pnpm example android
# Optional browser development:
pnpm example web
```
Native build commands require the platform's normal development tools. Browser rendering is useful for inspection but is not evidence of iOS or Android layout and performance.
The example groups demos under **Presets**, **Splitters**, **Effects**, **Timelines**, **Layout**, and **Playback**. Try **Line Reveal**, **Typewriter Controls**, **Controlled Progress**, and **Renderer Performance** to inspect the corresponding APIs. See [Performance](https://react-native-text-motion.pages.dev/guide/usage/performance.md) for how to record measurements.
---
url: https://react-native-text-motion.pages.dev/api/recipe.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Recipe API
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Import the public factories from `@react-native-motion-kit/text-motion`. Presets are exported separately from `@react-native-motion-kit/text-motion/presets`.
## `defineTextMotion()`
`fade().and(rise()).and(scale())`React Native Web
Run example
View code
Starts a recipe builder. Every configuration method returns a new builder, so a base recipe can be reused without changing earlier recipes.
```tsx
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const base = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04));
const FadeTitle = base.effect(fade()).component();
const RisingTitle = base.effect(fade().and(rise({ y: 12 }))).component();
export function Heading() {
return Motion made for text;
}
```
Create recipe components outside the rendering function so ordinary rerenders preserve their React identity.
## Builder methods
| Method | Input | Behavior |
| ------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `.split(splitter)` | A [splitter](https://react-native-text-motion.pages.dev/api/splitters.md) | Chooses source tokens. Omit this for `overlayText()`. |
| `.layout(renderer)` | A [renderer](https://react-native-text-motion.pages.dev/api/renderers.md) | Selects how text is laid out and rendered. Required before `.component()`. |
| `.timeline(timeline)` | A [timeline](https://react-native-text-motion.pages.dev/api/timelines.md) | Chooses each visible motion unit's start delay. |
| `.effect(effect)` | A compatible [effect](https://react-native-text-motion.pages.dev/api/effects.md) | Appends an effect; repeated calls accumulate effects. |
| `.motion(config)` | `TextMotionMotionConfig` | Configures autoplay and controls-driven playback. |
| `.accessibility(policy)` | `TextMotionAccessibilityPolicy` | Configures parent labeling and reduced motion. |
| `.recipe()` | None | Returns a configuration snapshot; allowed before a renderer is chosen. |
| `.component()` | None | Creates a React component accepting [text-motion props](https://react-native-text-motion.pages.dev/api/component-props.md). |
Repeated `.split()`, `.layout()`, `.timeline()`, `.motion()`, and `.accessibility()` calls replace that part of the new recipe. Select the renderer before adding effects so TypeScript can check its capabilities. A rendered-line recipe cannot use `.split(...)`; that combination is also rejected at runtime.
With `nativeText()` and no splitter, the whole string is one token. With no timeline, all animated units start together. With no effects, their visual style stays unchanged.
## `.motion(config)`
`.motion({ kind: 'spring' })`React Native Web
Run example
View code
```tsx
.motion({ kind: 'timing', options: { duration: 420 } })
.motion({ kind: 'spring', options: { damping: 14, stiffness: 160 } })
```
`TextMotionMotionConfig` is a discriminated union:
```ts
type TextMotionMotionConfig =
| { kind: 'timing'; options?: TextMotionTimingOptions }
| { kind: 'spring'; options?: TextMotionSpringOptions };
```
`TextMotionTimingOptions` follows Reanimated's `WithTimingConfig` and `TextMotionSpringOptions` follows `WithSpringConfig`, with `reduceMotion` excluded from both. Configure reduced motion through `.accessibility(...)`. The installed Reanimated version determines the remaining supported options. Numeric motion options must be finite.
The default internal animation is timing with a **300ms** duration. Timeline inputs use **seconds**; `duration` uses **milliseconds**. Function-valued options such as `easing` are compared by reference: reuse the same function when a rerender should preserve playback.
Passing a component an external `progress` shared value disables internal autoplay and ignores `.motion()` for that instance. See [Playback](https://react-native-text-motion.pages.dev/guide/usage/playback.md).
## `.accessibility(parentLabelPolicy(options))`
```tsx
import { parentLabelPolicy } from '@react-native-motion-kit/text-motion';
const policy = parentLabelPolicy({ reducedMotion: 'final-state' });
```
`ParentLabelPolicyOptions` has one option, `reducedMotion?: 'system' | 'final-state'`, defaulting to `'system'`. The returned policy exposes one full-text accessible parent label and hides decorative token nodes. Both renderers use `parentLabelPolicy()` when no policy is supplied. See [Accessibility](https://react-native-text-motion.pages.dev/guide/usage/accessibility.md) for renderer behavior and recommended usage.
## Public handles and types
`TextMotionSplitter`, `TextMotionRenderer`, `TextMotionTimeline`, and `TextMotionEffect` are opaque handles returned by the public factories. Pass them to the builder; use `.and(...)` to compose effects. Their internal `kind`, `name`, `options`, `delayFor`, `Component`, and capability arrays are not a supported inspection or extension API.
The root also exports `TextMotionRendererCapability`, `TextMotionRendererProps`, and `TextMotionToken` as types. Exported types do not make internal factory functions public. Custom effect factories, custom renderer factories, descriptor readers, and capability factories are outside the current root API.
---
url: https://react-native-text-motion.pages.dev/api/splitters.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Splitters
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Splitters choose source-text tokens for `nativeText()`. They return an opaque `TextMotionSplitter` handle used by `.split(...)`.
```tsx
import {
custom,
defineTextMotion,
fade,
graphemes,
lines,
nativeText,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const WordTitle = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(fade())
.component();
```
`overlayText()` owns actual rendered-line measurement and cannot be combined with any splitter. See [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md).
## `words()`
`words()`React Native Web
Run example
View code
Takes no options. Produces word, spacing, and punctuation tokens using `Intl.Segmenter` when available, with an internal fallback otherwise. Whitespace preserves layout but does not consume a motion index; visible punctuation can consume one.
Words follow the runtime's segmentation rules. This is not a promise that every language separates words by spaces. The generated token metadata includes `isWordLike`.
## `graphemes()`
`graphemes()`React Native Web
Run example
View code
Takes no options. Produces grapheme-aware tokens for character-level motion. Prefer it over `text.split('')`, which can break surrogate pairs and combining sequences.
The fallback handles common emoji sequences and decomposed Hangul such as `한` without normalizing the source, but does not implement every Unicode grapheme rule. Some complex-script conjuncts can still split. See [Segmentation](https://react-native-text-motion.pages.dev/guide/usage/segmentation.md) before relying on exact locale boundaries.
## `lines()` — experimental
`lines()`React Native Web
Run example
View code
Takes no options. Splits at explicit `\n` boundaries and preserves newline text in the token's source range. It **does not** measure automatic wrapping caused by width, fonts, or font scaling.
```tsx
const AuthoredLines = defineTextMotion()
.split(lines())
.layout(nativeText())
.effect(fade())
.component();
export function Heading() {
return {'First line\nSecond line'};
}
```
Tokens have `metadata: { experimental: true, mapping: 'newline-only' }`. Use `overlayText()` and `lineReveal()` when you need the lines React Native actually rendered.
## `custom(split)`
`custom()`React Native Web
Run example
View code
```ts
type TextMotionCustomSplit = (
input: string,
context?: { locale?: string | string[] },
) => readonly TextMotionCustomSplitResult[];
type TextMotionCustomSplitResult = string | TextMotionCustomSplitToken;
type TextMotionCustomSplitToken = {
text: string;
sourceRange?: { start: number; end: number };
metadata?: Record;
};
```
Return strings or token objects. String results get inferred source ranges by searching forward from the previous token's end. Return explicit ranges when matching is ambiguous or metadata matters. Ranges use JavaScript string indices (UTF-16 code units), with an exclusive `end`.
```tsx
const phrases = custom((input) => {
const separator = input.indexOf(' / ');
if (separator < 0) return [input];
return [
{ text: input.slice(0, separator), sourceRange: { start: 0, end: separator } },
{ text: ' / ', sourceRange: { start: separator, end: separator + 3 } },
{
text: input.slice(separator + 3),
sourceRange: { start: separator + 3, end: input.length },
},
];
});
```
Preserve all characters and spacing that should remain visible. A custom splitter does not repair or validate product-specific segmentation decisions. The optional context is part of the callback shape; recipe components currently call splitters without passing a locale, so there is no component `locale` prop.
## Token type
`TextMotionToken` is exported for typed integrations:
```ts
type TextMotionToken = {
id: string;
text: string;
index: number;
unit: 'grapheme' | 'word' | 'line' | 'custom';
sourceRange: { start: number; end: number };
metadata?: Record;
};
```
A splitter handle does not expose a public `.split()` method or its internal descriptor. Pass the handle to the recipe builder instead.
---
url: https://react-native-text-motion.pages.dev/api/renderers.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Renderers
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Choose a renderer with `.layout(...)` before calling `.component()`. Both factories return opaque handles, not React components.
| Renderer | Motion unit | Splitter | Supported effects |
| --------------- | ----------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `nativeText()` | Source word, grapheme, authored line, or custom token | Optional | `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`, `typewriter` |
| `overlayText()` | Actual React Native rendered line | Not allowed | `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`, `lineReveal` |
## `nativeText(options?)`
`words()`React Native Web
Run example
View code
```ts
type NativeTextRendererOptions = {
testIDPrefix?: string;
};
```
The stable default choice for short titles, labels, onboarding text, and product copy. It renders animated tokens inside animated `View` containers with inner `Text` nodes so transforms are visible. Static tokens remain plain text nodes. Explicit newlines preserve authored line breaks without consuming motion timing slots.
```tsx
import {
defineTextMotion,
fade,
nativeText,
rise,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const WordReveal = defineTextMotion()
.split(words())
.layout(nativeText({ testIDPrefix: 'title-word' }))
.timeline(stagger(0.04))
.effect(fade().and(rise({ y: 12 })))
.component();
export function Heading() {
return Make words move;
}
```
`testIDPrefix` has no default. It creates generated token test IDs; an animated token's ID belongs to its animated container. The component's `testID` identifies the parent. Typography props such as `allowFontScaling` reach the inner text.
This renderer uses a wrapping token layout, so exact single-`Text` shaping, kerning, ligatures, and automatic line wrapping are not guaranteed. `textAlign` maps to token-row alignment; it does not turn the renderer into a full native paragraph implementation. Use `overlayText()` for actual rendered-line motion, and ordinary React Native `Text` for rich inline content or exact text-node behavior.
## `overlayText(options?)`
`overlayText() + lineReveal()`iOS recording
View code
```ts
type OverlayTextRendererOptions = {
testIDPrefix?: string;
};
```
Measures one native paragraph and animates masks for each actual rendered line. Use this when line breaks depend on available width, font, font scale, alignment, or language shaping. **Do not call `.split(...)`.** TypeScript and runtime checks reject that combination.
```tsx
import {
defineTextMotion,
lineReveal,
overlayText,
scale,
stagger,
} from '@react-native-motion-kit/text-motion';
import { View } from 'react-native';
const HeroLines = defineTextMotion()
.layout(overlayText({ testIDPrefix: 'hero-line' }))
.timeline(stagger(0.08))
.effect(lineReveal({ y: 18 }).and(scale({ from: 0.98 })))
.motion({ kind: 'timing', options: { duration: 420 } })
.component();
export function Hero() {
return (
A responsive title that reveals one rendered line at a time
);
}
```
Give the paragraph a meaningful available width. Measurement is based on native text layout, not a guessed character count. Changes to text or layout inputs trigger measurement updates. If usable line mapping is unavailable, the renderer keeps readable source text instead of animating guessed line geometry. When system reduced motion is enabled, it renders the final source paragraph directly.
`testIDPrefix` has no default and prefixes generated overlay/line-mask IDs. `lineReveal()` moves the paragraph copy inside each mask while applying its opacity to the line frame. Other transform effects operate on the measured line frame, so a composed `scale()` or `pulse()` can grow around the line center without being clipped by the renderer's own reveal mask.
This is rendered-line motion, not word-in-line or character-in-line mapping. It does not expose `onTextLayout`, `numberOfLines`, text selection, or inline links as component props.
### Reflow at different widths
`overlayText() · width reflow`iOS recording
View code
This iOS recording shows a long English paragraph without explicit newlines at React Native layout widths of `220` and `320`. The native example's **Narrow** and **Wide** buttons change the available width; its progress controls hold `progress` at `0.5` during the change, then replay at each width. The line masks follow the source paragraph's native measurements after reflow.
## Shared playback and accessibility
Both renderers support autoplay, explicit [controls](https://react-native-text-motion.pages.dev/guide/usage/playback.md), and app-owned `progress`. Never pass both `controls` and `progress`. The default accessibility policy exposes the complete phrase once and hides decorative nodes; a component-level `accessibilityLabel` overrides the spoken label.
Read [Component Props](https://react-native-text-motion.pages.dev/api/component-props.md), [Accessibility](https://react-native-text-motion.pages.dev/guide/usage/accessibility.md), and [Performance](https://react-native-text-motion.pages.dev/guide/usage/performance.md) before using many tokens or rows. Browser rendering is not evidence of iOS/Android layout or performance.
## Renderer types
The root exports `NativeTextRendererOptions`, `OverlayTextRendererOptions`, `TextMotionRenderer`, `TextMotionRendererCapability`, and `TextMotionRendererProps`. Renderer descriptors, implementation `Component` fields, and capability factories remain internal. A public renderer-extension SDK is outside the current API.
---
url: https://react-native-text-motion.pages.dev/api/timelines.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Timelines
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Timelines assign start delays to visible motion units: source tokens for `nativeText()` and measured lines for `overlayText()`. **All timeline delays are in seconds.** Whitespace and non-animated layout units do not consume motion indices.
```tsx
import {
defineTextMotion,
fade,
nativeText,
parallel,
sequence,
stagger,
wave,
words,
} from '@react-native-motion-kit/text-motion';
const Title = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04, { from: 'center' }))
.effect(fade())
.motion({ kind: 'timing', options: { duration: 300 } })
.component();
```
Here `0.04` means a 40ms delay step. The `300` motion duration is **milliseconds** per animated unit. Without a timeline, every unit has zero delay.
## `stagger(step, options?)`
`stagger()`React Native Web
Originstartcenterendedges
Run example
View code
Choose **start**, **center**, **end**, or **edges** above to compare reveal order. Each selection switches the actual React Native Web recipe and replays it. The **Recipe** source and copy controls follow the selected direction.
```ts
type TextMotionStaggerFrom = 'start' | 'center' | 'end' | 'edges' | number;
type TextMotionStaggerOptions = { from?: TextMotionStaggerFrom };
```
`step` is required, finite, and non-negative. `from` defaults to `'start'`. A numeric origin is a finite token index, not a percentage; it may be fractional.
For unit index `i` and total count `n`, the delay is `step × distance`:
| `from` | Distance | Pattern |
| ------------ | ---------------------- | ---------------------- |
| `'start'` | `i` | First to last |
| `'end'` | `n - 1 - i` | Last to first |
| `'center'` | `abs(i - (n - 1) / 2)` | Middle outward |
| `'edges'` | `min(i, n - 1 - i)` | Both ends inward |
| A number `k` | `abs(i - k)` | Outward from index `k` |
```tsx
stagger(0.04);
stagger(0.04, { from: 'end' });
stagger(0.04, { from: 'edges' });
stagger(0.04, { from: 2 });
```
## `wave(options?)`
`wave()`React Native Web
Run example
View code
```ts
type TextMotionWaveOptions = {
amplitude?: number;
wavelength?: number;
};
```
| Option | Default | Constraint | Meaning |
| ------------ | ------- | -------------- | ------------------------------------------ |
| `amplitude` | `0.08` | Finite, `>= 0` | Maximum delay in seconds |
| `wavelength` | `4` | Finite, `> 0` | Number of motion units per sine-wave cycle |
The delay for index `i` is `((sin(i / wavelength × 2π) + 1) / 2) × amplitude`. The first unit therefore starts at half the amplitude; a wave does not promise left-to-right reveal order.
```tsx
wave();
wave({ amplitude: 0.06, wavelength: 5 });
```
## `sequence(...timelines)`
`sequence()`React Native Web
Run example
View code
Accepts zero or more timeline handles and **adds their delays for each unit**. This composes delay patterns; it does not wait for one whole animation to finish before starting another.
```tsx
sequence(stagger(0.02), wave({ amplitude: 0.04, wavelength: 4 }));
```
`sequence()` with no arguments produces zero delay.
## `parallel(...timelines)`
`parallel()`React Native Web
Run example
View code
Accepts zero or more timeline handles and chooses the **earliest delay for each unit**.
```tsx
parallel(stagger(0.08), wave({ amplitude: 0.05, wavelength: 3 }));
```
`parallel()` with no arguments produces zero delay. It does not create independent playback tracks.
## Controlled progress
In [external progress mode](https://react-native-text-motion.pages.dev/guide/usage/playback.md), timeline delays still shape each unit's local progress. The app controls the shared value's timing curve; `.motion()` does not run. A timeline is a delay pattern, not a separate playback controller.
## Handles and validation
The root exports `TextMotionTimeline`, `TextMotionStaggerFrom`, `TextMotionStaggerOptions`, and `TextMotionWaveOptions`. Numeric factory inputs are validated as described above. Returned timelines are opaque handles: `delayFor`, `name`, and `options` are not public properties. Pass timelines to `.timeline(...)`, `sequence(...)`, or `parallel(...)`.
---
url: https://react-native-text-motion.pages.dev/api/effects.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Effects
Live previews run the actual library through React Native Web. Examples that need native line measurements use an iOS recording.
Effects describe the visual change of each motion unit. Import them from `@react-native-motion-kit/text-motion` and pass a compatible effect to `.effect(...)` after selecting a renderer.
## Factories and defaults
Every option is optional; `typewriter()` takes no options. All numeric effect inputs must be finite. Directional offsets can be negative. Offsets use React Native layout units, opacity is a scalar, and scale values are multipliers.
| Factory | Options and defaults | Behavior | Renderer |
| ---------------------- | ------------------------- | ------------------------------------------------------------------- | --------------- |
| `fade(options?)` | `from: 0`, `to: 1` | Changes opacity from `from` to `to` | Both |
| `rise(options?)` | `y: 12` | Starts offset downward by `y`, then moves into place | Both |
| `slide(options?)` | `x: 0`, `y: 12` | Starts at an x/y offset, then moves into place | Both |
| `scale(options?)` | `from: 0.96`, `to: 1` | Changes the scale multiplier | Both |
| `pulse(options?)` | `scale: 1.04` | Peaks around the midpoint, then returns to the composed final scale | Both |
| `shake(options?)` | `x: 4` | Starts with a horizontal offset for a shake-like entrance | Both |
| `lineReveal(options?)` | `y: 16`, `fromOpacity: 0` | Reveals rendered lines through masks | `overlayText()` |
| `typewriter()` | None | Hides a token until its local progress becomes positive | `nativeText()` |
`shake()` is an entrance offset; it does not create a repeating oscillation. `pulse()` provides midpoint emphasis; use `scale()` when the starting or ending size should change.
The root exports `FadeOptions`, `RiseOptions`, `SlideOptions`, `ScaleOptions`, `PulseOptions`, `ShakeOptions`, and `LineRevealOptions`. Their properties match the table above.
## Try each effect
Replay each demo to compare its starting position, opacity, and scale.
### `fade()`
`fade()`React Native Web
Run example
View code
### `rise()`
`rise()`React Native Web
Run example
View code
### `slide()`
`slide()`React Native Web
Run example
View code
### `scale()`
`scale()`React Native Web
Run example
View code
### `pulse()`
`pulse()`React Native Web
Run example
View code
### `shake()`
`shake()`React Native Web
Run example
View code
## Compose with `.and(...)`
`fade().and(rise()).and(scale())`React Native Web
Run example
View code
```tsx
import {
defineTextMotion,
fade,
nativeText,
rise,
scale,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
const HeroTitle = defineTextMotion()
.split(words())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(rise({ y: 14 }).and(fade()).and(scale({ from: 0.98 })))
.component();
export function Heading() {
return A little motion, a clear message;
}
```
`.and(...)` returns a composed `TextMotionEffect`. Repeated `.effect(...)` calls also append effects. Transform offsets accumulate and scale multipliers multiply; opacity-setting effects are applied in composition order. Prefer one clear opacity effect when combining recipes.
Effects require compatible renderer capabilities. `lineReveal()` cannot be used with `nativeText()`, and `typewriter()` cannot be used with `overlayText()`. TypeScript checks valid combinations; runtime checks also reject incompatible effects.
## `lineReveal()`
`overlayText() + lineReveal()`iOS recording
View code
```tsx
import {
defineTextMotion,
lineReveal,
overlayText,
stagger,
} from '@react-native-motion-kit/text-motion';
const HeroLines = defineTextMotion()
.layout(overlayText())
.timeline(stagger(0.08))
.effect(lineReveal({ y: 18, fromOpacity: 0 }))
.motion({ kind: 'timing', options: { duration: 420 } })
.component();
```
Do not add a splitter. The renderer measures actual wrapped lines. The reveal offset moves the paragraph copy inside each mask, while opacity applies to the line frame. Composed `scale()` and `pulse()` transform the measured line frame. See [Renderers](https://react-native-text-motion.pages.dev/api/renderers.md) for layout and measurement behavior.
## `typewriter()`
`typewriter()`React Native Web
Run example
View code
Use this for fixed-layout character reveals. The splitter chooses the reveal unit, the timeline chooses its start, and `.motion()` chooses any subsequent movement.
```tsx
import {
defineTextMotion,
graphemes,
nativeText,
parentLabelPolicy,
stagger,
typewriter,
} from '@react-native-motion-kit/text-motion';
const TypewriterText = defineTextMotion()
.split(graphemes())
.layout(nativeText())
.timeline(stagger(0.04))
.effect(typewriter())
.motion({ kind: 'timing', options: { duration: 0 } })
.accessibility(parentLabelPolicy({ reducedMotion: 'final-state' }))
.component();
export function Greeting() {
return 안녕 세계! 👩🏽💻;
}
```
The completed phrase's space and line breaks remain in place from the start. Visible graphemes get delay slots 40ms apart; whitespace and explicit newlines keep their layout without taking a slot. Punctuation takes a slot like other visible characters. The first character appears on the first playback update, and display timing follows device frames.
`duration: 0` makes each reveal instant in autoplay or controls mode. To move a character after it appears, use a nonzero duration and compose an effect such as `typewriter().and(rise({ y: 6 }))`. Composing `fade()` intentionally makes appearance gradual. The visibility gate works in either composition order; adding `typewriter()` twice does not add another clock.
Use [controls](https://react-native-text-motion.pages.dev/guide/usage/playback.md) for replay/reset/stop. `stop()` preserves the current state; a later `play()` does not promise exact continuation of the remaining typing schedule. To type a new phrase fully from its start, remount with a new React `key`. Appending text is not a streaming API.
With external `progress`, `0` hides the animated characters and `1` shows the final state. **Progress is timeline progress, not the percentage of characters shown.** For maximum delay `D` and a character's delay `d`, local progress is `clamp(progress × (D + 1) - d, 0, 1)`. A character becomes visible when this is greater than zero. Decreasing progress past its start hides it again. `.motion()` is ignored in external-progress mode.
This effect does not grow or delete the underlying string, provide a cursor, guarantee single-`Text` shaping, or implement streaming. Use it with short UI copy and measure larger workloads.
## Public scope
Effect handles expose `.and(...)`; internal `name`, `options`, and `requiredCapabilities` fields are not public. Custom effect factories, `wipe`, `scramble`, and Skia effects are outside the current API.
---
url: https://react-native-text-motion.pages.dev/api/component-props.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# Component Props
Calling a recipe's `.component()` returns a `TextMotionComponent`. Its props are `TextMotionComponentProps`, shared by both built-in renderers.
## Text and styling
| Prop | Type | Behavior |
| ----------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `children` | `string` | Required plain text. Nested elements, arrays, and rich text are not supported. |
| `style` | `StyleProp` | Text styling. `nativeText()` applies it to token text; `overlayText()` uses it for the measured paragraph. |
| `testID` | `string` | Identifies the parent container. |
| `nativeID` | `string` | Passed to the parent container. |
| `allowFontScaling` | React Native `TextProps['allowFontScaling']` | Forwarded to text rendering. |
| `maxFontSizeMultiplier` | React Native `TextProps['maxFontSizeMultiplier']` | Forwarded to text rendering. |
The component requires a string at runtime as well as in TypeScript. To include authored newlines, use a string expression such as `{'First line\nSecond line'}`. Use a surrounding `View` for external layout constraints instead of assuming all `Text` or `View` props are forwarded.
```tsx
import {
defineTextMotion,
fade,
nativeText,
words,
} from '@react-native-motion-kit/text-motion';
import { View } from 'react-native';
const Title = defineTextMotion()
.split(words())
.layout(nativeText())
.effect(fade())
.component();
export function Heading() {
return (
Make room for readable motion
);
}
```
## Playback
| Prop | Type | Behavior |
| ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `controls` | `TextMotionControls` | Event-driven `play`, `replay`, `reset`, and `stop`; internal playback uses the recipe's `.motion()` config. |
| `progress` | Reanimated `SharedValue` | App-owned whole-text progress; internal autoplay and `.motion()` do not drive that instance. |
**`controls` and `progress` are mutually exclusive.** TypeScript rejects the combination and both renderers also throw at runtime. With neither prop, animated content autoplays on mount.
`progress` is normalized: `0` is initial and `1` is final. Finite values outside that range are clamped, and non-finite values are treated as `0`. Timeline delays map it to per-unit progress, so it is not a visible-character percentage. See [Playback](https://react-native-text-motion.pages.dev/guide/usage/playback.md) for complete controls and progress examples.
## Accessibility
The supported accessibility props are:
- `accessibilityLabel`
- `accessibilityHint`
- `accessibilityRole`
- `accessibilityState`
- `accessibilityValue`
- `accessibilityActions`
- `accessibilityLanguage`
- `onAccessibilityAction`
The default parent label is the complete original string; `accessibilityLabel` overrides it. The policy owns whether the parent is accessible and whether decorative nodes are hidden. Configure it through `.accessibility(parentLabelPolicy(...))`, rather than passing an `accessible` prop. See [Accessibility](https://react-native-text-motion.pages.dev/guide/usage/accessibility.md).
## Lifecycle
Ordinary parent rerenders with the same text and recipe preserve in-flight playback. Text changes are enter-only: old content is not retained for an exit, crossfade, or token diff. In controls mode, later commands target the current text. In external-progress mode, the current shared value determines the new text's state.
Changes to effect, timeline, or motion configuration can reset affected animations. Keep recipe components and function-valued motion options stable when playback should survive parent rerenders.
## Deliberately narrow surface
These components are not full React Native `Text` replacements. Props such as `numberOfLines`, `ellipsizeMode`, `lineBreakMode`, `onTextLayout`, `selectable`, text `onPress`, and nested styled text are outside the current contract. Put interaction or external layout on an appropriate surrounding component.
`TextMotionComponent`, `TextMotionComponentProps`, `TextMotionComponentTextProps`, and `TextMotionComponentAccessibilityProps` are exported from the root for typed application code. Controls use `useTextMotionControls()` and the exported `TextMotionControls` type; there is no public component-ref or context/provider playback API.
---
url: https://react-native-text-motion.pages.dev/index.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/llms-full.txt.
# React Native Text Motion
Give your words a rhythm.
> Compose reusable text animations with splitters, renderers, timelines, and effects.
[Quick Start](/guide/getting-started/quick-start.html) | [Explore Examples](/guide/usage/examples.html)
## Features
- ✨ **Start with a preset**: Turn editorialRise, softWave, or gentleEmphasis into a reusable component in a few lines.
- 🧩 **Compose your own recipe**: Choose how text splits, how tokens render, when they start, and how they move.
- 📐 **Reveal rendered lines**: Use overlayText and lineReveal to animate the lines React Native actually lays out.
- ⌨️ **Type without shifting layout**: Reveal graphemes while preserving the completed phrase's token layout.
- 🎛️ **Own playback**: Replay from events with explicit controls or drive motion from your Reanimated shared value.
- ♿ **Keep text readable**: Expose the full phrase once to screen readers and choose a reduced-motion policy.