--- 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 entrance A 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 together The 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 motion Reusable 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 default A 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 playback A subtitle with the same command channel