---
url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/overview.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 소개
`@react-native-motion-kit/text-motion`은 React Native에서 재사용할 수 있는 텍스트 애니메이션 컴포넌트를 만듭니다. 텍스트 분할, 렌더링, 타이밍, 효과, 접근성을 레시피로 조합한 뒤 컴포넌트로 렌더링합니다.
```txt
split → layout(renderer) → timeline → effect → motion/accessibility → component
```
이 문서는 현재 `0.1.0`의 공개 API를 설명합니다.
## 시작 방법 선택하기
일반적인 제목, 라벨, 제품 설명 애니메이션은 [프리셋](https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md)으로 시작하세요. 애니메이션 단위, 타이밍, 효과를 직접 선택하려면 [커스텀 레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md)를 만드세요.
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroTitle = editorialRise().component();
export function Hero() {
return 자연스럽게 움직이는 텍스트;
}
```
컴포넌트의 자식에는 일반 문자열을 전달합니다. 부모가 다시 렌더링되어도 같은 컴포넌트 타입을 사용하도록 React 렌더 함수 밖에서 정의하세요.
## 만들 수 있는 기능
| 목적 | 공개 API |
| ------------------------------ | ------------------------------------------------ |
| 단어나 사용자가 인식하는 글자 단위로 움직이기 | `words()` 또는 `graphemes()`와 `nativeText()` |
| React Native가 실제로 줄바꿈한 줄을 드러내기 | `.split(...)` 없이 `overlayText()`와 `lineReveal()` |
| 완성된 문장의 공간을 유지하며 한 글자씩 드러내기 | `graphemes()`, `nativeText()`, `typewriter()` |
| 버튼이나 앱 이벤트에 맞춰 다시 재생하기 | `useTextMotionControls()`와 `controls` prop |
| 스크롤, 제스처, 앱이 관리하는 애니메이션 따라가기 | Reanimated shared value를 `progress`로 전달 |
| 스크린 리더가 문장을 읽을 수 있게 유지하기 | 부모 레이블을 사용하고 장식용 토큰 노드는 접근성 트리에서 숨기기 |
`controls`는 재생 명령을 보내고, `progress`는 현재 시각적 상태를 전달합니다. 한 인스턴스에서는 둘 중 하나만 사용할 수 있습니다.
## 범위와 제약
짧은 제목, 헤딩, 라벨, 온보딩 문구, 제품 설명을 대상으로 합니다. 긴 문단, 많은 행, 글자 수가 많은 grapheme 애니메이션은 도입 전에 대상 기기에서 성능을 측정하세요.
`nativeText()`는 움직이는 토큰을 컨테이너로 감싸므로 하나의 네이티브 `Text`가 제공하는 모든 동작을 재현하지 않습니다. 중첩된 리치 텍스트, 인라인 링크, 텍스트 선택, 텍스트 `onPress`는 컴포넌트 계약에 포함되지 않습니다. `lines()`는 명시적인 `\n`만 분할합니다. 자동 줄바꿈에는 `overlayText()`를 사용하세요.
현재 공개 API에는 커스텀 효과 팩토리, 렌더러 확장 SDK, Skia 효과, `pause`/`seek`/`reverse`, 스크롤·제스처·화면 포커스·in-view 전용 드라이버가 없습니다. 앱 이벤트는 `controls`로 연결하고 연속적인 shared value는 `progress`로 연결할 수 있습니다. 텍스트 변경은 새 텍스트의 등장만 처리합니다. 퇴장 애니메이션을 위해 이전 텍스트를 유지하거나 스트리밍 텍스트 API를 제공하지 않습니다.
[설치](https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md)를 마친 뒤 [빠른 시작](https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md)에서 첫 컴포넌트를 만들어 보세요.
라이브러리의 개발 우선순위와 설계 범위는 [로드맵](https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md)에서 확인할 수 있습니다.
---
url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 설치
Text Motion은 React Native Reanimated와 React Native Worklets를 사용합니다. 텍스트 애니메이션을 렌더링하기 전에 앱에서 서로 호환되는 버전으로 설정하세요.
## 요구 사항
패키지가 선언한 peer dependency 최소 버전은 다음과 같습니다.
| 의존성 | 선언된 범위 |
| ------------------------- | ---------- |
| `react` | `>=18.0.0` |
| `react-native` | `>=0.76.0` |
| `react-native-reanimated` | `>=4.0.0` |
| `react-native-worklets` | `>=0.5.0` |
이 범위가 모든 버전 조합의 호환성을 보장하지는 않습니다. [Reanimated 호환성 표](https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/)에서 지원하는 React Native, Reanimated, Worklets 조합을 선택하세요. Reanimated 4는 React Native New Architecture를 요구합니다.
## 패키지 설치
기존 React Native 앱에서는 다음과 같이 설치합니다.
```sh
pnpm add @react-native-motion-kit/text-motion react-native-reanimated react-native-worklets
```
npm이나 Yarn을 사용한다면 같은 패키지를 `npm install` 또는 `yarn add`로 설치하세요.
Expo 앱에서는 SDK에 맞는 Reanimated와 Worklets 버전을 Expo가 선택하도록 설치합니다.
```sh
npx expo install react-native-reanimated react-native-worklets
pnpm add @react-native-motion-kit/text-motion
```
SDK가 선택한 버전이 위의 peer dependency 범위를 만족하는지 확인하세요. SDK와 빌드 방식에 필요한 설정은 [Expo Reanimated 가이드](https://docs.expo.dev/versions/latest/sdk/reanimated/)를 따르세요.
## Worklets 설정
사용하는 환경에 맞춰 공식 [Reanimated 시작 가이드](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)와 [Worklets 시작 가이드](https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started/)를 따르세요.
Babel을 사용하는 bare React Native 앱에서는 기존 설정의 **마지막** 플러그인으로 Worklets 플러그인을 추가합니다.
```js
module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: ['react-native-worklets/plugin'],
};
```
앱에 필요한 다른 preset과 plugin은 유지하세요. Expo의 Babel preset이 해당 SDK에서 플러그인을 설정할 수 있으므로, 중복으로 추가하지 말고 SDK별 설정을 확인하세요.
네이티브 의존성을 추가한 뒤에는 앱에서 사용하는 CocoaPods 절차로 iOS pod를 설치하고 네이티브 앱을 다시 빌드하세요. Babel 설정을 바꿨다면 Metro 캐시를 초기화하고 다시 실행하세요. Text Motion 자체에는 별도 Babel 플러그인, provider, 네이티브 설정이 필요하지 않습니다.
## 공개 진입점에서 가져오기
```tsx
import {
defineTextMotion,
fade,
nativeText,
stagger,
words,
} from '@react-native-motion-kit/text-motion';
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
```
기본 구성 요소는 패키지 루트에서 가져옵니다. 세 가지 프리셋은 `/presets`에서 가져옵니다. 내부 렌더러나 descriptor 파일을 직접 가져오지 마세요.
[빠른 시작](https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md)으로 이어서 진행하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 빠른 시작
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
[설치](https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md)를 마친 뒤 프리셋을 선택하거나 레시피를 만드세요. 두 방식 모두 재사용할 수 있는 React 컴포넌트를 반환합니다.
## 프리셋으로 시작하기
`editorialRise()`React Native Web
예제 실행
코드 보기
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroReveal = editorialRise().component();
export function HeroTitle() {
return (
자연스럽게 움직이는 텍스트
);
}
```
`editorialRise()`는 단어 토큰, 중앙에서 시작하는 stagger, rise·fade·scale 조합을 사용합니다. 컴포넌트가 마운트되면 자동으로 재생합니다.
## 단어 등장 효과 만들기
`words()`React Native Web
예제 실행
코드 보기
```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 단어마다 움직임을 더하세요;
}
```
타임라인의 단위는 **초**입니다. `stagger(0.04)`는 보이는 단어를 40ms 간격으로 시작합니다. motion의 `duration` 단위는 **밀리초**입니다. 각 토큰은 자신의 지연 시간이 지난 뒤 420ms 동안 움직입니다. 공백은 레이아웃 공간을 유지하지만 지연 순번을 차지하지 않습니다. 위 접근성 정책은 전체 문장을 한 번 읽도록 제공하고, 동작 줄이기가 활성화되면 최종 상태를 보여 줍니다.
## 실제 렌더링된 줄 드러내기
`overlayText() + lineReveal()`iOS 녹화
코드 보기
폭과 글꼴 설정에 따라 애니메이션할 줄을 결정하려면 `overlayText()`를 사용하세요. 이 렌더러가 줄 측정을 담당하므로 `.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 (
레이아웃이 만든 줄을 따라 움직여요
);
}
```
`lines()`는 다른 용도입니다. 명시적인 줄바꿈 문자만 분할하며 자동 줄바꿈을 측정하지 않습니다.
## 다음 단계
- [레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md) 조합 방식과 [프리셋](https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md) 수정 방법을 알아보세요.
- [재생 제어 또는 외부 progress](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 연결하세요.
- [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md), [효과](https://react-native-text-motion.pages.dev/ko/api/effects.md), [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)를 비교하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/ai.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# AI
레시피, 프리셋, 재생 제어, 문제 해결을 AI에게 물어볼 때 Text Motion 문서를 함께 제공하세요.
## llms.txt
이 사이트는 AI 도구를 위한 두 가지 파일을 제공합니다.
- [llms.txt](https://react-native-text-motion.pages.dev/ko/llms.txt): 개별 문서 링크를 모은 구조화된 인덱스입니다. AI가 필요한 페이지를 직접 가져올 수 있을 때 사용하면 컨텍스트를 줄일 수 있습니다.
- [llms-full.txt](https://react-native-text-motion.pages.dev/ko/llms-full.txt): 한국어 문서 전체를 하나로 합친 파일입니다. 여러 기능에 걸친 질문이나 큰 리팩터링에 적합하지만 컨텍스트를 더 많이 사용합니다.
작업에 맞는 URL을 복사하세요.
```txt
https://react-native-text-motion.pages.dev/ko/llms.txt
https://react-native-text-motion.pages.dev/ko/llms-full.txt
```
## Markdown 문서
모든 문서 페이지는 Markdown 버전도 제공합니다. 특정 기능 하나만 질문할 때는 관련 페이지만 전달하세요.
```txt
https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md
https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md
https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md
```
AI가 URL을 직접 읽을 수 없다면 파일을 열어 내용을 붙여 넣거나 컨텍스트로 첨부하세요.
## 프롬프트 예시
```txt
https://react-native-text-motion.pages.dev/ko/guide/getting-started/quick-start.md를 읽어 주세요.
defineTextMotion(), words(), nativeText(), stagger(), fade().and(rise())를 사용해
React Native 단어 리빌을 만들어 주세요. import와 접근성을 고려한 사용 예시를 포함하고,
문서에 있는 API를 사용해 시간 단위를 설명해 주세요.
```
## 라이브러리 개발 맥락
Text Motion 자체를 수정할 때는 [로드맵 안내](https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md)에서 저장소의 프로젝트 맥락과 상세 계획으로 이동할 수 있습니다. 현재 우선순위, 설계 범위와 보류 후보를 기록한 문서이며, 보류 항목은 출시 약속이 아닙니다.
진행 중인 제안과 우선순위를 정한 이유는 [로드맵 Discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10)에서도 확인할 수 있습니다.
---
url: https://react-native-text-motion.pages.dev/ko/guide/getting-started/roadmap.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 로드맵
기능 제안, 우선순위와 설계 결정은 [프로젝트 방향·로드맵 Discussion](https://github.com/react-native-motion-kit/react-native-text-motion/discussions/10)에서 함께 논의합니다.
라이브러리의 우선순위, 범위와 설계 결정은 저장소의 [프로젝트 맥락과 로드맵](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md)에 기록합니다.
현재 우선순위는 iOS와 Android에서 렌더러 성능과 플랫폼 동작을 검증한 뒤, 그 근거로 추가 API를 라이브러리에 포함할지 판단하는 것입니다.
## 개발 맥락 찾아보기
| 확인할 내용 | 원문 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 다음에 진행할 작업 | [현재 우선순위](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#현재-우선순위) |
| 성능 측정과 검증 근거 분류 | [렌더러 성능 체크포인트](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#renderer-performance-checkpoint) |
| 구현된 공개 API 범위 | [Stable MVP](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#stable-mvp) |
| 보류 후보와 의도적으로 제외한 API | [Deferred](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#deferred) |
| Text Motion과 별도 패키지의 경계 | [범위와 로드맵](https://github.com/react-native-motion-kit/react-native-text-motion/blob/main/ROADMAP.ko.md#scope--roadmap) |
보류 후보는 출시 약속이 아닙니다. 구현된 동작과 지원 API는 이 사이트의 [API 레퍼런스](https://react-native-text-motion.pages.dev/ko/api/recipe.md)를 참고하세요.
저장소의 로드맵은 원래 README의 맥락과 원본 커밋 링크를 보존합니다. 상세 계획은 그 문서를 기준으로 관리해 여러 곳의 내용이 어긋나지 않게 유지합니다.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 레시피
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
`defineTextMotion()`은 불변 빌더를 만듭니다. 각 체인 메서드는 새로운 빌더를 반환하므로 기본 레시피를 공유하면서 원본을 바꾸지 않고 여러 변형을 만들 수 있습니다.
## 컴포넌트 만들기
```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 (
<>
부드럽게 등장해요움직임을 조금 더해요
>
);
}
```
생성한 컴포넌트는 모듈 최상위에서 정의하세요. 렌더 중 `.component()`를 호출하면 매번 새로운 컴포넌트 타입이 생겨 재마운트와 의도하지 않은 자동 재생이 발생할 수 있습니다.
## 각 단계가 결정하는 것
| 단계 | 역할 |
| --------------------- | ------------------------------------------- |
| `.split(...)` | `nativeText()`가 사용할 원문 토큰 경계 |
| `.layout(...)` | 렌더러와 지원하는 애니메이션 단위·효과 |
| `.timeline(...)` | 초 단위의 토큰별 시작 지연 |
| `.effect(...)` | 효과 추가. 여러 번 호출하면 누적됨 |
| `.motion(...)` | 내부 자동 재생과 controls 명령에 사용할 timing 또는 spring |
| `.accessibility(...)` | 부모 레이블, 장식용 토큰, 동작 줄이기 정책 |
| `.component()` | 문자열 자식을 받는 React 컴포넌트 생성 |
| `.recipe()` | 컴포넌트를 만들지 않고 레시피 설정 스냅샷 확인 |
`.split()`, `.layout()`, `.timeline()`, `.motion()`, `.accessibility()`를 다시 호출하면 새 빌더에서 해당 설정을 교체합니다. `.effect()`는 기존 효과에 추가합니다. `.recipe()`는 layout을 선택하기 전에도 사용할 수 있습니다. 반환값은 설정 스냅샷으로 취급하고, 컴포넌트를 갱신하려고 직접 수정하지 마세요.
## 렌더러 먼저 선택하기
TypeScript에서는 `.layout(...)`으로 렌더러를 선택한 뒤에만 `.component()`를 사용할 수 있습니다. `.effect(...)`보다 먼저 렌더러를 선택하면 타입이 지원 가능한 효과를 안내합니다.
`nativeText()`에서는 splitter를 명시해 단어, grapheme, 커스텀 토큰, 직접 작성한 줄바꿈 단위를 선택합니다. splitter를 생략하면 전체 입력이 하나의 원문 토큰이 됩니다. 기본 동작은 단어 분할이 아닙니다.
`overlayText()`는 측정한 네이티브 줄을 애니메이션 단위로 사용합니다. 줄을 움직이려는 경우에도 `.split(...)`을 추가하지 마세요. 타입 시스템이 호환되지 않는 체인을 막고, 런타임 검사도 같은 조합을 거부합니다.
## 호환되는 효과 조합하기
`fade().and(rise()).and(scale())`React Native Web
예제 실행
코드 보기
`.effect(fade().and(rise()))`와 `.effect(fade()).effect(rise())` 모두 fade와 rise를 추가합니다. 기본 효과인 `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`는 두 렌더러에서 사용할 수 있습니다. `typewriter()`는 `nativeText()`를, `lineReveal()`은 `overlayText()`를 요구합니다.
splitter, timeline, effect, renderer는 내부 구조를 숨긴 공개 핸들입니다. 내부 descriptor에 접근하는 대신 빌더에 전달하세요. 패키지 루트 API는 커스텀 효과 팩토리나 렌더러 확장 SDK를 내보내지 않습니다.
## 재생 방식 설정하기
`.motion({ kind: 'spring' })`React Native Web
예제 실행
코드 보기
```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 (
<>
문장 전체가 함께 나타나요같은 단위를 스프링으로 움직여요
>
);
}
```
motion 옵션은 Reanimated의 해당 timing 또는 spring 설정을 따릅니다. 단, `reduceMotion`은 접근성 정책에서 설정합니다. 타임라인 지연의 단위는 초이고 timing의 `duration`은 밀리초입니다. easing처럼 함수인 옵션은 참조로 비교합니다. 다시 렌더링할 때 재생을 유지하려면 같은 함수 참조를 재사용하세요.
인스턴스에 `progress`를 전달하면 앱이 재생을 담당하고 해당 인스턴스의 `.motion()`은 적용되지 않습니다. 레시피가 재생을 담당하면서 개별 명령을 받게 하려면 `controls`를 사용하세요. [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)와 [레시피 API](https://react-native-text-motion.pages.dev/ko/api/recipe.md)를 참고하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 프리셋
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
프리셋은 `@react-native-motion-kit/text-motion/presets`에서 가져오는 레시피 팩토리입니다. 각 팩토리는 단어 분할, `nativeText()`, 타임라인, 효과를 미리 선택한 빌더를 반환합니다. `.component()`로 컴포넌트를 만들거나 빌더를 먼저 수정할 수 있습니다.
```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 (
<>
단어에 움직임을 더하세요짧은 제품 설명을 위한 재사용 가능한 애니메이션
>
);
}
```
## 기본 레시피
| 팩토리 | 타임라인 | 효과 |
| ------------------ | ------------------------------------------ | ---------------------------------------------------- |
| `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()` |
세 팩토리는 모두 인수를 받지 않습니다. 지연 값의 단위는 초입니다. 별도의 `.motion()`이나 접근성 정책을 지정하지 않으므로 직접 설정하지 않으면 렌더러 기본값을 사용합니다.
`editorialRise()`는 중앙에서 펼쳐지는 제목에 어울립니다. `softWave()`는 단어의 시작 시간을 달리해 부드러운 리듬을 만듭니다. `gentleEmphasis()`는 애니메이션 중간 부근에서 토큰을 잠시 확대했다가 최종 크기로 돌아오며, 반복 재생하지 않습니다.
## 프리셋 미리보기
### `editorialRise()`
`editorialRise()`React Native Web
예제 실행
코드 보기
### `softWave()`
`softWave()`React Native Web
예제 실행
코드 보기
### `gentleEmphasis()`
`gentleEmphasis()`React Native Web
예제 실행
코드 보기
## 프리셋 수정하기
```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 (
<>
기본은 중앙에서 시작해요처음부터 천천히 나타나요
>
);
}
```
빌더는 불변이므로 수정한 변형이 `StandardTitle`을 바꾸지 않습니다. 뒤에서 호출한 `.timeline(...)`은 프리셋 타임라인을 교체합니다. `.effect(...)`는 기존 효과를 교체하지 않고 추가합니다. 효과 구성을 바꾸거나 `overlayText()`로 실제 줄 단위 레시피를 만들려면 `defineTextMotion()`에서 시작하세요.
프리셋도 커스텀 레시피와 같은 [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)와 [재생 입력](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)을 사용합니다. 생성한 컴포넌트는 렌더 함수 밖에 정의하고 자식으로 일반 문자열을 전달하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 재생 제어
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
컴포넌트의 자동 재생, 이벤트 기반 명령, 앱이 소유한 Reanimated 공유값 중 재생을 제어할 방식을 선택합니다.
| 방식 | 입력 | 재생 담당 |
| ------ | --------------------- | ----------------------------------- |
| 자동 재생 | 재생 관련 prop 없음 | Text Motion이 입력 변화에 따라 재생합니다. |
| 명령 | `controls={controls}` | 앱이 명령을 보내고 Text Motion이 레시피를 실행합니다. |
| 외부 진행률 | `progress={progress}` | 앱이 값과 애니메이션 곡선을 직접 제어합니다. |
## 자동 재생과 텍스트 변경
`Autoplay`React Native Web
예제 실행
코드 보기
마운트하면 화면에 보이는 애니메이션 토큰이 초기 스타일에서 최종 스타일로 재생됩니다. `controls`를 전달해도 마운트 시 자동 재생은 유지됩니다. 첫 명령을 기다리는 방식으로 바뀌지는 않습니다.
- 같은 텍스트와 레시피로 다시 렌더링하면 진행 중인 재생을 유지합니다.
- 텍스트가 바뀌면 토큰 형태가 같아도 변경된 토큰의 애니메이션을 다시 재생합니다.
- 실제 효과, 타이밍, 모션 설정이 바뀌면 관련 토큰을 초기화하고 새 설정을 적용합니다. easing 같은 함수 옵션은 참조로 비교하므로 재생을 유지하려면 같은 함수 참조를 사용하세요.
- 공백과 정적 토큰은 레이아웃을 유지하지만 애니메이션이나 모션 인덱스를 소비하지 않습니다.
텍스트 변경은 새 텍스트의 진입만 처리합니다. 이전 텍스트의 퇴장, 크로스페이드, 이전·새 토큰 간 전환은 제공하지 않습니다. 외부 진행률을 전달한 경우 새 텍스트도 현재 공유값을 사용하며 자동으로 처음부터 재생하지 않습니다. 명령은 현재 렌더링된 텍스트에 적용됩니다.
React가 컴포넌트 정체성을 유지할 수 있도록 레시피 컴포넌트는 렌더 함수 밖에서 만드세요. [레시피](https://react-native-text-motion.pages.dev/ko/guide/usage/recipes.md)를 참고하세요.
## 이벤트 기반 controls
`play() / replay() / reset() / stop()`React Native Web
예제 실행
코드 보기
`useTextMotionControls()`는 참조가 유지되는 명령 채널을 반환합니다. 명령을 받을 컴포넌트에 명시적으로 전달합니다.
```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 (
함께 재생하는 제목같은 명령 채널을 사용하는 부제목
);
}
```
| 명령 | 동작 |
| ---------- | ----------------------------------- |
| `play()` | 현재 진행 상태에서 최종 상태를 향해 재생합니다. |
| `replay()` | 초기화한 뒤 레시피의 타임라인과 모션 설정으로 다시 재생합니다. |
| `reset()` | 재생을 취소하고 초기 상태로 돌아갑니다. |
| `stop()` | 재생을 취소하고 현재 화면 상태를 유지합니다. |
명령은 같은 controls 객체에 연결된 모든 마운트된 컴포넌트에 전달되며, 각 컴포넌트는 자신의 레시피로 실행합니다. 명령은 저장된 재생 상태나 이후 마운트할 컴포넌트를 위한 대기열이 아닙니다. 연결이 해제되거나 언마운트되면 구독도 해제됩니다.
`stop()` 후 `play()`는 정확한 일시 정지·재개 API가 아니며 원래 일정의 남은 시간을 그대로 이어갈 것을 보장하지 않습니다. 처음부터 다시 시작하려면 `replay()`를 사용하세요. 명시적인 모션 감소 최종 상태 정책이 활성화돼 있으면 초기화나 다시 재생보다 최종 표시 상태가 우선합니다.
버튼, 앱에서 연결한 화면 포커스 이벤트, 온보딩 단계에는 controls를 사용하세요. 재생용 provider/context API나 공개 컴포넌트 ref API는 제공하지 않습니다.
## 앱이 소유한 progress
`progress`React Native Web
예제 실행
코드 보기
앱이 이미 소유한 다른 애니메이션, 스크롤 값, 제스처 값을 따라야 한다면 Reanimated의 `SharedValue`를 사용합니다.
```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 (
문장 전체를 하나의 진행률로 제어합니다
);
}
```
`0`은 초기 스타일, `1`은 최종 스타일입니다. 이 범위를 벗어난 유한한 값은 보정하고, 유한하지 않은 값은 `0`으로 처리합니다. `progress`를 전달하면 내부 자동 재생이 비활성화되고 해당 인스턴스에서는 레시피의 `.motion()` 설정을 사용하지 않습니다. 시간과 easing은 공유값을 갱신하는 곳에서 설정하세요.
이 값은 효과 타임라인 전체의 진행률입니다. 토큰 지연 `d`와 가장 큰 토큰 지연 `D`를 초 단위로 나타내면 현재 매핑은 토큰별 구간을 `1.0`으로 고정해 계산합니다.
```txt
localProgress = clamp(progress * (D + 1) - d, 0, 1)
```
타임라인은 각 토큰이 시작하는 시점을 계속 결정합니다. 공백은 지연 슬롯을 사용하지 않습니다. 이 매핑은 토큰별 재생 시간 API가 아닙니다.
### Typewriter의 진행률
`typewriter() + progress`React Native Web
예제 실행
코드 보기
미리보기는 **타임라인 진행률**과 **현재 표시된 글자 수**를 따로 보여줍니다. 글자 수는 공백을 제외하고 문장부호와 이모지를 포함하며, 재생 중이나 진행률을 되돌릴 때도 갱신됩니다.
`typewriter()`는 토큰의 로컬 진행률이 0보다 커지면 해당 토큰을 표시합니다. 진행률은 **표시된 문자 수의 비율이 아닙니다**. 보이는 문자 10개에 `stagger(0.05)`를 사용하면 약 `0.310345`를 넘는 시점에 모든 문자가 보입니다. 진행률을 줄여 시작 임계점을 다시 지나면 문자가 숨겨질 수 있습니다. 시간상 일정한 간격으로 임계점을 통과하려면 외부 타이밍 곡선을 선형으로 설정하세요.
이 효과는 완성된 문장의 레이아웃을 유지합니다. 커서나 스트리밍 텍스트 API는 제공하지 않습니다. [효과](https://react-native-text-motion.pages.dev/ko/api/effects.md)와 [예제](https://react-native-text-motion.pages.dev/ko/guide/usage/examples.md)를 참고하세요.
## 지원 범위
`controls`와 `progress`는 TypeScript와 런타임 모두에서 함께 사용할 수 없습니다. 전용 `pause`, `seek`, `reverse`, 스크롤, 제스처, in-view, 화면 포커스 드라이버는 제공하지 않습니다. 앱의 이벤트는 controls에, 연속적인 값은 progress에 연결하세요.
모션 감소 동작은 [접근성](https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md), 지원하는 텍스트·접근성 prop은 [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)를 참고하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 접근성
Text Motion은 애니메이션 토큰 노드를 장식 요소로 취급합니다. 기본적으로 부모는 문장 전체를 하나의 접근성 레이블로 제공하고, 개별 애니메이션 노드는 접근성 도구에서 숨깁니다. 화면 읽기 도구는 각 단어나 글자를 따로 읽는 대신 문장 전체를 한 번 읽습니다.
## 부모 레이블 정책
`parentLabelPolicy(options?)`로 레시피의 접근성 동작을 설정합니다. 옵션은 `reducedMotion` 하나입니다.
| 옵션 | 기본값 | 의미 |
| ------------------------------ | ---------- | ------------------------------------------ |
| `reducedMotion` | `'system'` | 내부 애니메이션에 Reanimated의 시스템 모션 감소 동작을 적용합니다. |
| `reducedMotion: 'final-state'` | 명시적으로 선택 | 시스템 모션 감소가 켜져 있으면 즉시 최종 화면 상태를 표시합니다. |
```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 (
메시지를 읽기 쉽게 유지하는 모션
);
}
```
`'final-state'`는 모든 사용자에게 모션을 비활성화하는 옵션이 아닙니다. 기기의 모션 감소 설정이 켜져 있을 때 최종 상태를 표시합니다. 이 표시 상태는 controls와 외부 progress보다 우선하므로, 앱의 공유값이 아직 `0`이어도 Typewriter 문장 전체가 읽을 수 있는 상태로 유지됩니다.
`nativeText()`의 기본 `'system'` 정책에서는 외부 `progress`를 앱이 계속 제어합니다. 값을 갱신하는 애니메이션도 사용자 설정을 존중하도록 구성하거나, 텍스트의 완성된 결과를 즉시 표시해야 한다면 `'final-state'`를 선택하세요.
`overlayText()`에는 별도의 렌더러 폴백도 있습니다. 시스템 모션 감소가 켜져 있으면 애니메이션 줄 오버레이 대신 원본 문단의 최종 상태를 표시합니다. 두 정책과 외부 progress 모두에 적용되며 앱의 공유값 자체는 바꾸지 않습니다.
`.motion()` 옵션에 `reduceMotion`을 전달하지 마세요. Text Motion의 모션 감소 동작은 `.accessibility(...)`로 설정합니다.
## 레이블과 텍스트 props
문자열 자식이 기본 접근성 레이블이 됩니다. 화면의 문구가 축약돼 있다면 `accessibilityLabel`로 설명을 지정할 수 있습니다. `accessibilityHint`, `accessibilityRole`, `accessibilityState`, `accessibilityValue`, `accessibilityActions`, `accessibilityLanguage`, `onAccessibilityAction`도 지원합니다.
`allowFontScaling`과 `maxFontSizeMultiplier`를 지원합니다. 특히 실제 렌더링된 줄을 움직일 때는 큰 글꼴 배율과 좁은 너비를 앱에서 확인하세요. 전체 prop 계약은 [컴포넌트 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md), 레이아웃 차이는 [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md)를 참고하세요.
## 앱에서 확인할 항목
- VoiceOver와 TalkBack으로 문장을 읽고, 장식용 단어와 문자가 개별적으로 읽히지 않는지 확인하세요.
- 모션 감소를 켜고 첫 프레임, 다시 재생, 초기화, 외부 진행률 상태를 확인하세요.
- 지원하는 글꼴 배율, 언어, 너비와 주변 UI의 대비를 확인하세요.
- 장식용 모션과 관계없이 핵심 정보가 읽혀야 합니다. Typewriter는 글자마다 별도의 안내를 보내지 않습니다.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/segmentation.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 문자 분할
모션을 정하기 전에 토큰 경계를 선택하세요. JavaScript의 코드 단위 하나가 화면의 문자 하나와 같지는 않습니다. 이모지, 결합 악센트, 분해된 한글은 여러 코드 포인트로 이루어질 수 있습니다.
## 기본 splitter
| Splitter | 단위 | 용도 |
| ------------- | ------------------- | ------------------------------- |
| `words()` | 단어, 문장부호, 공백 토큰 | 읽기 쉬운 단어 단위 제목과 제품 설명. |
| `graphemes()` | 문자소를 고려한 토큰 | 짧은 글자 단위 진입 효과와 Typewriter. |
| `lines()` | 명시적 줄바꿈으로 구분한 소스 단위 | 실험적인 줄바꿈 모션. 자동 줄바꿈은 감지하지 않습니다. |
| `custom(fn)` | 앱이 정의한 문자열 또는 토큰 객체 | 제품별 경계나 별도의 분할 구현. |
공백은 레이아웃 공간을 유지하면서 애니메이션 지연 슬롯을 소비하지 않습니다. 문장부호는 보이는 애니메이션 단위가 될 수 있습니다. 시그니처와 토큰 메타데이터는 [Splitters](https://react-native-text-motion.pages.dev/ko/api/splitters.md)를 참고하세요.
너비와 글꼴에 따른 자동 줄바꿈을 기준으로 움직이려면 `.split(...)` 없이 `overlayText()`를 사용하세요. [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md)를 참고하세요.
## `Intl.Segmenter`와 폴백
`words()`와 `graphemes()`는 런타임에 `Intl.Segmenter`가 있으면 사용합니다. React Native/Hermes 환경에 따라 제공 여부가 달라질 수 있어 작은 폴백 토크나이저도 포함합니다. `Intl.Segmenter`가 없을 때 앱 시작 오류를 피하기 위한 목적으로만 폴리필을 설치할 필요는 없습니다.
폴백은 `한` 같은 분해된 한글 음절과 관련된 완성형 한글·자모 경계를 처리하며 입력을 정규화하거나 다시 쓰지 않습니다. 일반적인 결합 문자와 이모지 시퀀스를 처리하지만, 모든 유니코드 문자소 규칙이나 언어별 단어 경계를 구현하지는 않습니다. `क्ष` 같은 일부 인도계 문자 결합은 여전히 나뉠 수 있고, 띄어쓰기가 없는 문자 체계는 더 정밀한 단어 분할이 필요할 수 있습니다.
정확한 경계가 중요하면 Text Motion을 렌더링하기 전에 앱 진입점에서 `Intl.Segmenter` 구현을 제공하거나, 앱이 선택한 토크나이저를 `custom()`에 연결하세요. 앱에서 `@formatjs/intl-segmenter` 같은 폴리필을 선택할 수 있지만 이 라이브러리가 설치해 주지는 않습니다.
## 원본 텍스트 보존
사용자 정의 splitter는 공백과 토큰 순서를 보존해야 합니다. 예를 들어 제품의 규칙에 따라 공백 기준으로 나누되 공백 묶음을 그대로 유지할 수 있습니다.
```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 원본의 공백을 유지합니다.;
}
```
이 예제는 문장부호를 인접한 공백 없는 텍스트에 포함합니다. 앱이 정한 규칙이며 완전한 언어학적 단어 분할은 아닙니다. 소스 범위와 메타데이터가 중요하다면 `custom()`에서 이를 명시한 토큰 객체를 반환할 수도 있습니다.
분할이 정확하다고 해서 토큰별 렌더링이 단일 네이티브 `Text`와 같아지지는 않습니다. 글자 조형, 합자, 양방향 텍스트, 줄바꿈, 복잡한 문자 체계는 선택한 렌더러에서 직접 확인해야 합니다. 예제 앱의 레이아웃 프로브는 [성능](https://react-native-text-motion.pages.dev/ko/guide/usage/performance.md)을 참고하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/performance.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 성능
Text Motion은 제목, 레이블, 온보딩 문구, 짧은 제품 설명처럼 중요한 UI 텍스트를 대상으로 합니다. 성능은 애니메이션 단위 수, 효과, 동시에 표시하는 컴포넌트 수, 기기와 재생 방식에 따라 달라집니다. 이 문서는 특정 FPS나 모든 환경에 통용되는 안전한 글자 수를 보장하지 않습니다.
## 애니메이션 단위 선택
`nativeText()`는 애니메이션 토큰마다 내부 `Text`와 애니메이션 `View` 컨테이너를 사용합니다. 정적 토큰은 일반 텍스트로 남습니다. 이 구조로 토큰 변형을 표시할 수 있지만, 글자 단위 분할은 단어 단위보다 훨씬 많은 애니메이션 단위를 만들 수 있습니다.
- 단어 단위 모션으로 의도가 전달된다면 `words()`를 우선 사용하세요.
- 짧은 글자 단위 표현에는 `graphemes()`나 `typewriter()`를 사용하고, 더 큰 작업량은 측정하세요.
- 레시피 컴포넌트는 렌더 함수 밖에 만드세요. 재시작만을 위해 반복해서 언마운트하기보다 controls로 기존 컴포넌트를 다시 재생하세요.
- 공유 controls는 실제 마운트할 행 수로 검사하세요. 명령 하나가 연결된 모든 컴포넌트에 전달됩니다.
- 실제 렌더링된 줄을 움직여야 한다면 `overlayText()`를 사용하세요. 네이티브 텍스트를 측정하고 줄마다 잘린 문단 복사본을 렌더링하므로, 모션 단위가 적다는 이유만으로 더 빠르다고 판단할 수는 없습니다.
레이아웃의 차이는 [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md), 명령과 진행률 제어는 [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 참고하세요.
## 예제 앱으로 프로파일링
측정할 플랫폼에서 저장소의 예제 앱을 실행하세요. 명령은 [예제](https://react-native-text-motion.pages.dev/ko/guide/usage/examples.md)에 있습니다.
**Playback → Renderer Performance**에서 단어·글자 작업량, Typewriter, 반복 재생, 공유 행, 외부 진행률 사례를 확인할 수 있습니다. **Playback → Controls Stress**는 명령을 여러 컴포넌트에 전달하는 추가 사례입니다. **Layout → Line Reveal**과 **Layout → Line Layout Probe**에서는 너비, 정렬, 글꼴 배율, 명시적 줄바꿈과 언어별 표시를 확인할 수 있습니다.
사례의 `normal`, `caution`, `stress` 표시는 프로브의 작업량 구분입니다. 측정된 성능 등급이나 지원하는 토큰 수 한도가 아닙니다. UI의 토큰·노드 수 추정치도 진단용이며 공개 구현 계약이 아닙니다.
React Native Perf Monitor, Xcode Instruments, Android Studio Profiler, Flashlight 같은 실제 FPS·프로파일링 도구를 사용하세요. 측정과 함께 기기·OS, 플랫폼, 빌드 모드, 텍스트·splitter, 효과, 컴포넌트·모션 단위 수, 재생 방식, 눈에 보이는 끊김을 기록하세요. 개발 모드와 시뮬레이터의 결과는 그 조건을 명시해야 합니다.
## 측정 근거 표기
| 상태 | 필요한 근거 |
| ------------- | ----------------------------------------- |
| `measured` | 같은 사례 유형에 대해 iOS와 Android 근거가 모두 있습니다. |
| `provisional` | 한 플랫폼만 확인했거나 시뮬레이터·에뮬레이터·개발 모드의 근거만 있습니다. |
| `unknown` | 해당 사례 유형을 측정하지 않았습니다. |
이 사이트는 플랫폼별 근거가 함께 제공되지 않는 작업량을 측정 완료로 주장하지 않습니다.
일반적인 제목과 레이블이 부드럽다면 기본 렌더러를 유지하고 무거운 텍스트의 경계를 안내하세요. 일반적인 작업량부터 끊긴다면 효과를 추가하기 전에 렌더러 비용을 조사하세요. 글자 단위 스트레스 사례가 실패했다는 사실만으로 일반적인 단어 단위 제목에도 다른 렌더러가 필요하다고 판단할 수는 없습니다.
## 프레임과 레이아웃을 함께 검증
`nativeText()`는 토큰별 변형을 위해 단일 `Text`의 정확한 글자 조형과 줄바꿈을 일부 포기합니다. `overlayText()`는 네이티브가 렌더링한 줄을 따르지만 앱의 글꼴, 배율, 너비, 정렬, 문자 체계에서도 확인해야 합니다. FPS만으로 줄바꿈, 접근성 읽기 순서, 모션 감소 동작까지 검증할 수는 없습니다. [문자 분할](https://react-native-text-motion.pages.dev/ko/guide/usage/segmentation.md)과 [접근성](https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md)을 참고하세요.
---
url: https://react-native-text-motion.pages.dev/ko/guide/usage/examples.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 예제
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
아래 예제는 현재 공개 API를 사용합니다. [설치](https://react-native-text-motion.pages.dev/ko/guide/getting-started/installation.md)를 마친 React Native 앱에서 실행하세요. 각 예제 옆의 미리보기에서 움직임을 확인하고 다시 재생할 수 있습니다.
## 프리셋으로 시작하기
`editorialRise()`React Native Web
예제 실행
코드 보기
프리셋은 `/presets` 경로에서 가져오는 레시피 팩토리입니다. 컴포넌트는 렌더 함수 밖에서 한 번 만드세요.
```tsx
import { editorialRise } from '@react-native-motion-kit/text-motion/presets';
const HeroTitle = editorialRise().component();
export function Hero() {
return (
자연스럽게 느껴지는 텍스트 모션
);
}
```
`softWave()`와 `gentleEmphasis()`는 [프리셋](https://react-native-text-motion.pages.dev/ko/guide/usage/presets.md)을 참고하세요.
## 단어 진입 효과와 다시 재생
`play() / replay() / reset() / stop()`React Native Web
예제 실행
코드 보기
```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 (
단어마다 작은 움직임을 더합니다.
);
}
```
`stagger(0.04)`는 시작 간격을 40ms로 설정하고, `duration: 360`은 토큰별 모션 시간을 밀리초로 설정합니다. controls를 전달해도 마운트 시 자동 재생은 유지됩니다. 외부 진행률과 전체 명령은 [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 참고하세요.
## 실제 렌더링된 줄 표시하기
`overlayText() + lineReveal()`iOS 녹화
코드 보기
사용 가능한 너비에 맞춰 제목이 줄바꿈돼야 한다면 네이티브가 렌더링한 줄을 사용하세요. 이 레시피에는 splitter를 추가하지 않습니다.
```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 (
레이아웃이 실제로 렌더링한 줄에 맞춰 제목을 움직입니다
);
}
```
`overlayText()`는 너비, 글꼴, 글꼴 배율, 글자 조형이 적용된 문단을 측정합니다. `lines()`는 명시적인 줄바꿈 문자만 나눕니다. [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md)를 참고하세요.
## 너비가 바뀌어도 진행률 유지하기
`overlayText() · width reflow`iOS 녹화
코드 보기
이 iOS 녹화는 명시적 줄바꿈이 없는 긴 영문 문단을 사용합니다. 네이티브 예제의 **Narrow**와 **Wide**는 React Native 레이아웃 너비를 `220`과 `320`으로 전환합니다. 진행률 컨트롤로 너비 변경 전후에 `progress`를 `0.5`로 유지한 뒤 각 너비에서 다시 재생하며, 새로 측정한 원문 문단에 맞춰 마스크가 배치되는지 확인할 수 있습니다.
## 레이아웃을 유지하는 Typewriter
`typewriter()`React Native Web
예제 실행
코드 보기
```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 (
안녕, 한글! 👩🏽💻
);
}
```
완성된 문장의 공간을 처음부터 확보합니다. 보이는 토큰은 타임라인의 시작 시점에 표시되고, 공백과 명시적 줄바꿈은 지연 슬롯 없이 공간을 유지합니다. `duration: 0`은 토큰별 표시를 즉시 처리합니다. Typewriter는 `nativeText()`가 필요하며 커서, 스트리밍, 단일 `Text`와 정확히 같은 줄바꿈을 제공하지 않습니다.
다른 문장을 처음부터 입력하려면 새 React `key`로 다시 마운트하세요. 문자열을 이어 붙이는 방식은 스트리밍 API가 아닙니다. 효과 조합은 [효과](https://react-native-text-motion.pages.dev/ko/api/effects.md), 문자소 폴백의 한계는 [문자 분할](https://react-native-text-motion.pages.dev/ko/guide/usage/segmentation.md)을 참고하세요.
## 저장소 예제 실행
저장소 루트에서 `.nvmrc`와 `package.json`에 고정된 Node·pnpm 버전을 사용하세요.
```sh
pnpm install
pnpm example start
# 또는 네이티브 앱을 빌드하고 실행합니다.
pnpm example ios
pnpm example android
# 브라우저 개발도 가능합니다.
pnpm example web
```
네이티브 빌드 명령에는 각 플랫폼의 일반적인 개발 도구가 필요합니다. 브라우저는 화면을 살펴보는 데 유용하지만 iOS·Android의 레이아웃과 성능을 검증한 근거는 아닙니다.
예제는 **Presets**, **Splitters**, **Effects**, **Timelines**, **Layout**, **Playback** 그룹으로 나뉩니다. **Line Reveal**, **Typewriter Controls**, **Controlled Progress**, **Renderer Performance**에서 관련 API를 확인하세요. 측정 기록 방법은 [성능](https://react-native-text-motion.pages.dev/ko/guide/usage/performance.md)을 참고하세요.
---
url: https://react-native-text-motion.pages.dev/ko/api/recipe.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 레시피 API
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
공개 팩터리는 `@react-native-motion-kit/text-motion`에서 가져옵니다. 프리셋은 별도 경로인 `@react-native-motion-kit/text-motion/presets`에서 가져옵니다.
## `defineTextMotion()`
`fade().and(rise()).and(scale())`React Native Web
예제 실행
코드 보기
레시피 빌더를 만듭니다. 각 설정 메서드는 새 빌더를 반환하므로, 기본 레시피를 재사용해도 앞서 만든 레시피는 바뀌지 않습니다.
```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 텍스트를 위한 모션;
}
```
일반적인 리렌더에서 React 컴포넌트의 정체성이 유지되도록, 레시피 컴포넌트는 렌더 함수 밖에서 만드세요.
## 빌더 메서드
| 메서드 | 입력 | 동작 |
| ------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `.split(splitter)` | [분할기](https://react-native-text-motion.pages.dev/ko/api/splitters.md) | 원문을 토큰으로 나눕니다. `overlayText()`에서는 생략합니다. |
| `.layout(renderer)` | [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md) | 텍스트 배치·렌더링 방식을 선택합니다. `.component()` 전에 필요합니다. |
| `.timeline(timeline)` | [타임라인](https://react-native-text-motion.pages.dev/ko/api/timelines.md) | 보이는 모션 단위별 시작 지연을 정합니다. |
| `.effect(effect)` | 호환되는 [효과](https://react-native-text-motion.pages.dev/ko/api/effects.md) | 효과를 추가합니다. 여러 번 호출하면 효과가 누적됩니다. |
| `.motion(config)` | `TextMotionMotionConfig` | 자동 재생과 controls 기반 재생을 설정합니다. |
| `.accessibility(policy)` | `TextMotionAccessibilityPolicy` | 부모 레이블과 모션 줄이기 동작을 설정합니다. |
| `.recipe()` | 없음 | 설정 스냅샷을 반환합니다. 렌더러 선택 전에도 호출할 수 있습니다. |
| `.component()` | 없음 | [텍스트 모션 props](https://react-native-text-motion.pages.dev/ko/api/component-props.md)를 받는 React 컴포넌트를 만듭니다. |
`.split()`, `.layout()`, `.timeline()`, `.motion()`, `.accessibility()`를 다시 호출하면 새 레시피에서 해당 설정이 교체됩니다. TypeScript가 렌더러 기능을 검사할 수 있도록 렌더러를 먼저 선택한 뒤 효과를 추가하세요. 렌더링된 줄을 사용하는 레시피에는 `.split(...)`을 지정할 수 없으며, 런타임에서도 이 조합을 거부합니다.
`nativeText()`에서 분할기를 생략하면 문자열 전체가 하나의 토큰이 됩니다. 타임라인이 없으면 모든 애니메이션 단위가 함께 시작합니다. 효과가 없으면 시각 스타일이 바뀌지 않습니다.
## `.motion(config)`
`.motion({ kind: 'spring' })`React Native Web
예제 실행
코드 보기
```tsx
.motion({ kind: 'timing', options: { duration: 420 } })
.motion({ kind: 'spring', options: { damping: 14, stiffness: 160 } })
```
`TextMotionMotionConfig`는 `kind`로 구분하는 유니온입니다.
```ts
type TextMotionMotionConfig =
| { kind: 'timing'; options?: TextMotionTimingOptions }
| { kind: 'spring'; options?: TextMotionSpringOptions };
```
`TextMotionTimingOptions`는 Reanimated의 `WithTimingConfig`, `TextMotionSpringOptions`는 `WithSpringConfig`를 따르며, 두 타입 모두 `reduceMotion`을 제외합니다. 모션 줄이기는 `.accessibility(...)`에서 설정합니다. 나머지 지원 옵션은 설치된 Reanimated 버전에 따릅니다. 숫자 모션 옵션은 유한한 값이어야 합니다.
내부 애니메이션의 기본값은 **300ms timing**입니다. 타임라인 입력은 **초**, `duration`은 **밀리초** 단위입니다. `easing`처럼 함수인 옵션은 참조로 비교하므로, 리렌더에서 재생을 유지하려면 같은 함수를 재사용하세요.
컴포넌트에 외부 `progress` 공유 값을 넘기면 내부 자동 재생을 사용하지 않고 해당 인스턴스의 `.motion()` 설정을 무시합니다. [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 참고하세요.
## `.accessibility(parentLabelPolicy(options))`
```tsx
import { parentLabelPolicy } from '@react-native-motion-kit/text-motion';
const policy = parentLabelPolicy({ reducedMotion: 'final-state' });
```
`ParentLabelPolicyOptions`의 옵션은 `reducedMotion?: 'system' | 'final-state'` 하나이며, 기본값은 `'system'`입니다. 반환되는 정책은 전체 문장을 부모 접근성 레이블로 노출하고 장식용 토큰 노드를 숨깁니다. 두 렌더러 모두 정책을 생략하면 `parentLabelPolicy()`를 사용합니다. 렌더러별 동작과 권장 사용법은 [접근성](https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md)을 참고하세요.
## 공개 핸들과 타입
`TextMotionSplitter`, `TextMotionRenderer`, `TextMotionTimeline`, `TextMotionEffect`는 공개 팩터리가 반환하는 불투명 핸들입니다. 빌더에 전달하고, 효과는 `.and(...)`로 합성하세요. 내부 `kind`, `name`, `options`, `delayFor`, `Component`, 기능 배열은 지원하는 조회·확장 API가 아닙니다.
루트에서는 `TextMotionRendererCapability`, `TextMotionRendererProps`, `TextMotionToken` 타입도 내보냅니다. 타입을 공개했다고 해서 내부 팩터리 함수까지 공개하는 것은 아닙니다. 사용자 정의 효과·렌더러 팩터리, descriptor 조회 함수, capability 팩터리는 현재 루트 API에 포함되지 않습니다.
---
url: https://react-native-text-motion.pages.dev/ko/api/splitters.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 분할기
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
분할기는 `nativeText()`가 사용할 원문 토큰을 정합니다. 반환되는 불투명 `TextMotionSplitter` 핸들을 `.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()`는 실제 렌더링된 줄을 직접 측정하므로 어떤 분할기와도 조합할 수 없습니다. [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md)를 참고하세요.
## `words()`
`words()`React Native Web
예제 실행
코드 보기
옵션을 받지 않습니다. `Intl.Segmenter`가 있으면 이를 사용하고, 없으면 내부 대체 구현으로 단어·공백·문장 부호 토큰을 만듭니다. 공백은 배치를 유지하지만 모션 인덱스를 사용하지 않으며, 보이는 문장 부호는 모션 인덱스를 사용할 수 있습니다.
단어 경계는 실행 환경의 분할 규칙을 따릅니다. 모든 언어에서 공백이 단어를 구분한다고 보장하지 않습니다. 생성된 토큰의 메타데이터에는 `isWordLike`가 포함됩니다.
## `graphemes()`
`graphemes()`React Native Web
예제 실행
코드 보기
옵션을 받지 않습니다. 문자 단위 모션을 위한 그래핌 기반 토큰을 만듭니다. 서로게이트 쌍과 결합 문자를 자를 수 있는 `text.split('')` 대신 사용하세요.
대체 구현은 일반적인 이모지 시퀀스와 `한` 같은 분해형 한글을 원문 정규화 없이 처리하지만, 모든 유니코드 그래핌 규칙을 구현하지는 않습니다. 일부 복잡한 문자 결합은 나뉠 수 있습니다. 정확한 언어별 경계가 필요하면 [텍스트 분할](https://react-native-text-motion.pages.dev/ko/guide/usage/segmentation.md)을 확인하세요.
## `lines()` — 실험적
`lines()`React Native Web
예제 실행
코드 보기
옵션을 받지 않습니다. 명시적인 `\n` 경계에서 나누며, 토큰의 원문 범위에 줄바꿈 문자를 보존합니다. 너비·글꼴·글자 크기 배율로 생긴 자동 줄바꿈은 **측정하지 않습니다**.
```tsx
const AuthoredLines = defineTextMotion()
.split(lines())
.layout(nativeText())
.effect(fade())
.component();
export function Heading() {
return {'첫 번째 줄\n두 번째 줄'};
}
```
토큰에는 `metadata: { experimental: true, mapping: 'newline-only' }`가 들어갑니다. React Native가 실제로 렌더링한 줄이 필요하면 `overlayText()`와 `lineReveal()`을 사용하세요.
## `custom(split)`
`custom()`React Native Web
예제 실행
코드 보기
```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;
};
```
문자열 또는 토큰 객체를 반환합니다. 문자열의 원문 범위는 이전 토큰의 끝부터 앞으로 검색해 추론합니다. 대응 관계가 모호하거나 메타데이터가 필요하면 범위를 직접 지정하세요. 범위는 JavaScript 문자열 인덱스(UTF-16 코드 단위)를 사용하며, `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 },
},
];
});
```
화면에 남겨야 할 문자와 공백을 모두 보존하세요. 사용자 정의 분할기는 제품별 분할 결정을 자동으로 보정하거나 검증하지 않습니다. 선택적인 context는 콜백 타입의 일부입니다. 현재 레시피 컴포넌트는 locale 없이 분할기를 호출하며, 컴포넌트에 `locale` prop은 없습니다.
## 토큰 타입
타입이 필요한 연동을 위해 `TextMotionToken`을 공개합니다.
```ts
type TextMotionToken = {
id: string;
text: string;
index: number;
unit: 'grapheme' | 'word' | 'line' | 'custom';
sourceRange: { start: number; end: number };
metadata?: Record;
};
```
분할기 핸들은 공개 `.split()` 메서드나 내부 descriptor를 노출하지 않습니다. 핸들을 레시피 빌더에 전달하세요.
---
url: https://react-native-text-motion.pages.dev/ko/api/renderers.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 렌더러
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
`.component()`를 호출하기 전에 `.layout(...)`으로 렌더러를 선택하세요. 두 팩터리는 React 컴포넌트가 아닌 불투명 핸들을 반환합니다.
| 렌더러 | 모션 단위 | 분할기 | 지원 효과 |
| --------------- | -------------------------- | ----- | ---------------------------------------------------------------- |
| `nativeText()` | 원문의 단어·그래핌·명시적 줄·사용자 정의 토큰 | 선택 | `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`, `typewriter` |
| `overlayText()` | React Native가 실제 렌더링한 줄 | 사용 불가 | `fade`, `rise`, `slide`, `scale`, `pulse`, `shake`, `lineReveal` |
## `nativeText(options?)`
`words()`React Native Web
예제 실행
코드 보기
```ts
type NativeTextRendererOptions = {
testIDPrefix?: string;
};
```
짧은 제목·레이블·온보딩 문구·제품 설명의 기본 선택입니다. 변형이 화면에 적용되도록 애니메이션 토큰을 animated `View` 컨테이너와 내부 `Text`로 렌더링합니다. 정적인 토큰은 일반 텍스트 노드로 남습니다. 명시적인 줄바꿈은 모션 지연 슬롯을 소비하지 않으면서 원문의 줄바꿈을 보존합니다.
```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 단어에 움직임을 더해요;
}
```
`testIDPrefix`의 기본값은 없습니다. 생성되는 토큰 test ID의 접두사이며, 애니메이션 토큰의 ID는 animated 컨테이너에 붙습니다. 컴포넌트의 `testID`는 부모를 식별합니다. `allowFontScaling` 같은 타이포그래피 props는 내부 텍스트로 전달됩니다.
이 렌더러는 토큰을 감싸는 줄 배치를 사용하므로 단일 `Text`의 정확한 글자 조형·커닝·합자·자동 줄바꿈은 보장하지 않습니다. `textAlign`은 토큰 행의 정렬로 대응하며, 완전한 네이티브 문단 구현으로 바뀌지는 않습니다. 실제 렌더링된 줄의 모션은 `overlayText()`, 중첩 인라인 콘텐츠나 정확한 텍스트 노드 동작은 일반 React Native `Text`를 사용하세요.
## `overlayText(options?)`
`overlayText() + lineReveal()`iOS 녹화
코드 보기
```ts
type OverlayTextRendererOptions = {
testIDPrefix?: string;
};
```
하나의 네이티브 문단을 측정하고 실제 렌더링된 줄마다 마스크를 애니메이션합니다. 너비·글꼴·글자 크기 배율·정렬·언어별 조형에 따라 줄바꿈이 달라지는 경우에 사용하세요. **`.split(...)`을 호출하지 마세요.** TypeScript와 런타임 검사 모두 이 조합을 거부합니다.
```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 (
화면에 배치된 줄을 따라 한 줄씩 나타나는 반응형 제목
);
}
```
문단에 실제로 사용할 수 있는 너비를 제공하세요. 측정은 추정한 글자 수가 아닌 네이티브 텍스트 레이아웃을 기준으로 합니다. 텍스트나 레이아웃 입력이 달라지면 측정값을 갱신합니다. 사용할 수 있는 줄 매핑이 없으면 줄의 위치를 추정해 애니메이션하는 대신 원문을 읽을 수 있게 유지합니다. 시스템 모션 줄이기가 켜져 있으면 완성된 원문 문단을 직접 렌더링합니다.
`testIDPrefix`의 기본값은 없으며, 생성되는 overlay·줄 마스크 ID의 접두사입니다. `lineReveal()`은 각 마스크 안의 문단 복사본을 움직이고, 불투명도는 줄 프레임에 적용합니다. 다른 변형 효과는 측정한 줄 프레임에 적용되므로, `scale()`이나 `pulse()`를 합성해도 렌더러 자체의 reveal 마스크에 잘리지 않고 줄 중심을 기준으로 커질 수 있습니다.
이는 렌더링된 줄의 모션이며, 줄 안의 단어·문자 매핑은 아닙니다. `onTextLayout`, `numberOfLines`, 텍스트 선택, 인라인 링크를 컴포넌트 props로 공개하지 않습니다.
### 너비가 달라질 때 줄 다시 배치하기
`overlayText() · width reflow`iOS 녹화
코드 보기
이 iOS 녹화는 명시적 줄바꿈이 없는 긴 영문 문단을 React Native 레이아웃 너비 `220`과 `320`에서 보여줍니다. 네이티브 예제의 **Narrow**와 **Wide** 버튼으로 사용 가능한 너비를 바꾸고, 진행률 컨트롤로 너비 변경 중 `progress`를 `0.5`로 유지한 뒤 각 너비에서 다시 재생합니다. 줄 마스크는 다시 배치된 원문 문단의 네이티브 측정값을 따릅니다.
## 공통 재생·접근성
두 렌더러 모두 자동 재생, 명시적 [controls](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md), 앱이 소유한 `progress`를 지원합니다. `controls`와 `progress`를 함께 넘기지 마세요. 기본 접근성 정책은 전체 문장을 한 번 노출하고 장식용 노드를 숨기며, 컴포넌트의 `accessibilityLabel`로 읽을 레이블을 바꿀 수 있습니다.
많은 토큰이나 행에 적용하기 전에 [컴포넌트 Props](https://react-native-text-motion.pages.dev/ko/api/component-props.md), [접근성](https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md), [성능](https://react-native-text-motion.pages.dev/ko/guide/usage/performance.md)을 확인하세요. 브라우저 렌더링만으로 iOS·Android의 배치나 성능을 검증할 수는 없습니다.
## 렌더러 타입
루트는 `NativeTextRendererOptions`, `OverlayTextRendererOptions`, `TextMotionRenderer`, `TextMotionRendererCapability`, `TextMotionRendererProps`를 내보냅니다. 렌더러 descriptor, 구현 `Component` 필드, capability 팩터리는 내부 API입니다. 공개 렌더러 확장 SDK는 현재 API 범위에 포함되지 않습니다.
---
url: https://react-native-text-motion.pages.dev/ko/api/timelines.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 타임라인
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
타임라인은 보이는 모션 단위별 시작 지연을 정합니다. `nativeText()`에서는 원문 토큰, `overlayText()`에서는 측정된 줄이 단위입니다. **타임라인의 모든 지연은 초 단위**입니다. 공백과 애니메이션하지 않는 배치 단위는 모션 인덱스를 사용하지 않습니다.
```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();
```
여기서 `0.04`는 40ms 지연 간격입니다. 모션의 `300`은 애니메이션 단위당 **밀리초** 지속 시간입니다. 타임라인을 생략하면 모든 단위의 지연이 0입니다.
## `stagger(step, options?)`
`stagger()`React Native Web
시작 방향startcenterendedges
예제 실행
코드 보기
위에서 **start**, **center**, **end**, **edges**를 선택해 나타나는 순서를 비교하세요. 선택할 때마다 실제 React Native Web 레시피를 바꾸고 다시 재생합니다. **Recipe** 소스와 복사 컨트롤도 선택한 방향을 따릅니다.
```ts
type TextMotionStaggerFrom = 'start' | 'center' | 'end' | 'edges' | number;
type TextMotionStaggerOptions = { from?: TextMotionStaggerFrom };
```
`step`은 필수이며, 유한한 0 이상의 값이어야 합니다. `from`의 기본값은 `'start'`입니다. 숫자로 지정한 시작점은 비율이 아닌 유한한 토큰 인덱스이며 소수도 가능합니다.
단위 인덱스가 `i`, 전체 개수가 `n`이면 지연은 `step × 거리`입니다.
| `from` | 거리 | 순서 |
| ---------- | ---------------------- | -------------- |
| `'start'` | `i` | 처음에서 끝으로 |
| `'end'` | `n - 1 - i` | 끝에서 처음으로 |
| `'center'` | `abs(i - (n - 1) / 2)` | 가운데에서 바깥으로 |
| `'edges'` | `min(i, n - 1 - i)` | 양 끝에서 안쪽으로 |
| 숫자 `k` | `abs(i - k)` | 인덱스 `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
예제 실행
코드 보기
```ts
type TextMotionWaveOptions = {
amplitude?: number;
wavelength?: number;
};
```
| 옵션 | 기본값 | 제약 | 의미 |
| ------------ | ------ | ------------- | ---------------------- |
| `amplitude` | `0.08` | 유한한 값, `>= 0` | 최대 지연 시간(초) |
| `wavelength` | `4` | 유한한 값, `> 0` | 사인파 한 주기에 포함되는 모션 단위 수 |
인덱스 `i`의 지연은 `((sin(i / wavelength × 2π) + 1) / 2) × amplitude`입니다. 따라서 첫 단위는 amplitude의 절반만큼 늦게 시작하며, wave가 왼쪽부터 오른쪽으로 나타나는 순서를 보장하지는 않습니다.
```tsx
wave();
wave({ amplitude: 0.06, wavelength: 5 });
```
## `sequence(...timelines)`
`sequence()`React Native Web
예제 실행
코드 보기
0개 이상의 타임라인 핸들을 받아 **각 단위의 지연을 더합니다**. 지연 패턴의 합성이며, 하나의 전체 애니메이션이 끝날 때까지 기다린 뒤 다음 애니메이션을 시작하는 API는 아닙니다.
```tsx
sequence(stagger(0.02), wave({ amplitude: 0.04, wavelength: 4 }));
```
인자 없는 `sequence()`는 지연 0을 만듭니다.
## `parallel(...timelines)`
`parallel()`React Native Web
예제 실행
코드 보기
0개 이상의 타임라인 핸들을 받아 **각 단위에서 가장 빠른 지연**을 선택합니다.
```tsx
parallel(stagger(0.08), wave({ amplitude: 0.05, wavelength: 3 }));
```
인자 없는 `parallel()`은 지연 0을 만듭니다. 독립적인 재생 트랙을 만드는 API는 아닙니다.
## 외부 progress
[외부 progress 모드](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)에서도 타임라인 지연은 각 단위의 로컬 progress를 정합니다. 공유 값의 시간 곡선은 앱이 제어하고 `.motion()`은 실행하지 않습니다. 타임라인은 지연 패턴이며 별도의 재생 컨트롤러가 아닙니다.
## 핸들과 검증
루트는 `TextMotionTimeline`, `TextMotionStaggerFrom`, `TextMotionStaggerOptions`, `TextMotionWaveOptions`를 내보냅니다. 숫자 팩터리 입력은 위의 제약대로 검사합니다. 반환되는 타임라인은 불투명 핸들이므로 `delayFor`, `name`, `options`는 공개 속성이 아닙니다. `.timeline(...)`, `sequence(...)`, `parallel(...)`에 전달하세요.
---
url: https://react-native-text-motion.pages.dev/ko/api/effects.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 효과
라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.
효과는 각 모션 단위의 시각적 변화를 설명합니다. `@react-native-motion-kit/text-motion`에서 가져오고, 렌더러를 선택한 뒤 호환되는 효과를 `.effect(...)`에 전달하세요.
## 팩터리와 기본값
모든 옵션은 선택 사항이며 `typewriter()`는 옵션이 없습니다. 숫자 효과 입력은 모두 유한한 값이어야 합니다. 방향을 나타내는 오프셋은 음수도 가능합니다. 오프셋은 React Native 레이아웃 단위, 불투명도는 스칼라, 크기는 배율입니다.
| 팩터리 | 옵션과 기본값 | 동작 | 렌더러 |
| ---------------------- | ------------------------- | ----------------------------- | --------------- |
| `fade(options?)` | `from: 0`, `to: 1` | 불투명도를 `from`에서 `to`로 변경 | 둘 다 |
| `rise(options?)` | `y: 12` | 아래쪽 `y` 오프셋에서 제자리로 이동 | 둘 다 |
| `slide(options?)` | `x: 0`, `y: 12` | x/y 오프셋에서 제자리로 이동 | 둘 다 |
| `scale(options?)` | `from: 0.96`, `to: 1` | 크기 배율 변경 | 둘 다 |
| `pulse(options?)` | `scale: 1.04` | 중간 부근에서 커진 뒤 합성된 최종 크기로 복귀 | 둘 다 |
| `shake(options?)` | `x: 4` | 가로 오프셋으로 흔들리는 듯한 진입 표현 | 둘 다 |
| `lineReveal(options?)` | `y: 16`, `fromOpacity: 0` | 마스크 안에서 렌더링된 줄을 드러냄 | `overlayText()` |
| `typewriter()` | 없음 | 로컬 progress가 양수가 될 때까지 토큰을 숨김 | `nativeText()` |
`shake()`는 진입 오프셋이며 반복적인 진동을 만들지 않습니다. `pulse()`는 중간 지점의 강조 효과입니다. 시작·종료 크기를 바꾸려면 `scale()`을 사용하세요.
루트에서 `FadeOptions`, `RiseOptions`, `SlideOptions`, `ScaleOptions`, `PulseOptions`, `ShakeOptions`, `LineRevealOptions`를 내보냅니다. 각 속성은 위 표의 옵션과 같습니다.
## 효과별 미리보기
각 데모에서 다시 재생해 시작 위치와 투명도, 크기 변화를 비교하세요.
### `fade()`
`fade()`React Native Web
예제 실행
코드 보기
### `rise()`
`rise()`React Native Web
예제 실행
코드 보기
### `slide()`
`slide()`React Native Web
예제 실행
코드 보기
### `scale()`
`scale()`React Native Web
예제 실행
코드 보기
### `pulse()`
`pulse()`React Native Web
예제 실행
코드 보기
### `shake()`
`shake()`React Native Web
예제 실행
코드 보기
## `.and(...)`로 합성
`fade().and(rise()).and(scale())`React Native Web
예제 실행
코드 보기
```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 작은 움직임으로 전하는 선명한 메시지;
}
```
`.and(...)`는 합성된 `TextMotionEffect`를 반환합니다. `.effect(...)`를 여러 번 호출해도 효과가 누적됩니다. 변형 오프셋은 더해지고 크기 배율은 곱해지며, 불투명도를 설정하는 효과는 합성 순서대로 적용됩니다. 레시피를 조합할 때는 불투명도 효과를 하나로 명확하게 정하는 편이 좋습니다.
효과는 렌더러가 제공하는 기능과 호환되어야 합니다. `lineReveal()`은 `nativeText()`에서, `typewriter()`는 `overlayText()`에서 사용할 수 없습니다. TypeScript가 조합을 검사하며 런타임에서도 호환되지 않는 효과를 거부합니다.
## `lineReveal()`
`overlayText() + lineReveal()`iOS 녹화
코드 보기
```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();
```
분할기를 추가하지 마세요. 렌더러가 실제로 줄바꿈된 줄을 측정합니다. reveal 오프셋은 각 마스크 안의 문단 복사본을 움직이고, 불투명도는 줄 프레임에 적용됩니다. 함께 사용하는 `scale()`과 `pulse()`는 측정된 줄 프레임을 변형합니다. 배치·측정 동작은 [렌더러](https://react-native-text-motion.pages.dev/ko/api/renderers.md)를 참고하세요.
## `typewriter()`
`typewriter()`React Native Web
예제 실행
코드 보기
완성된 배치를 유지하면서 문자를 드러낼 때 사용합니다. 분할기는 드러낼 단위, 타임라인은 시작 시점, `.motion()`은 시작 후의 움직임을 정합니다.
```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 안녕 세계! 👩🏽💻;
}
```
처음부터 완성된 문장의 공간과 줄바꿈을 유지합니다. 보이는 그래핌은 40ms 간격의 지연 슬롯을 받으며, 공백과 명시적 줄바꿈은 공간을 유지하되 슬롯을 사용하지 않습니다. 문장 부호는 다른 보이는 문자처럼 슬롯을 사용합니다. 첫 문자는 첫 재생 갱신에서 나타나며, 실제 표시 시점은 기기 프레임을 따릅니다.
`duration: 0`이면 자동 재생과 controls 모드에서 각 문자가 즉시 나타납니다. 나타난 뒤 움직이게 하려면 0보다 큰 지속 시간과 `typewriter().and(rise({ y: 6 }))` 같은 효과를 사용하세요. `fade()`를 합성하면 의도적으로 서서히 나타납니다. 표시 여부는 어느 합성 순서에서도 유지되며, `typewriter()`를 두 번 더해도 재생 시계가 추가되지 않습니다.
다시 재생·초기화·정지는 [controls](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 사용하세요. `stop()`은 현재 상태를 유지하며, 이후 `play()`가 남은 타이핑 일정을 정확히 이어간다고 보장하지 않습니다. 새 문구를 처음부터 전부 타이핑하려면 새 React `key`로 다시 마운트하세요. 텍스트를 덧붙이는 동작은 스트리밍 API가 아닙니다.
외부 `progress`에서 `0`은 애니메이션 문자를 숨기고 `1`은 최종 상태를 표시합니다. **progress는 표시된 문자 비율이 아니라 타임라인 진행률입니다.** 최대 지연을 `D`, 문자의 지연을 `d`라 하면 로컬 progress는 `clamp(progress × (D + 1) - d, 0, 1)`입니다. 이 값이 0보다 크면 문자가 보이며, 시작점을 지나 뒤로 되돌리면 다시 숨겨집니다. 외부 progress 모드에서는 `.motion()`을 무시합니다.
이 효과는 원문 문자열을 늘리거나 지우지 않으며, 커서·단일 `Text`의 정확한 조형·스트리밍을 제공하지 않습니다. 짧은 UI 문구에 사용하고 큰 작업량은 직접 측정하세요.
## 공개 범위
효과 핸들은 `.and(...)`를 공개합니다. 내부 `name`, `options`, `requiredCapabilities` 필드는 공개 API가 아닙니다. 사용자 정의 효과 팩터리, `wipe`, `scramble`, Skia 효과는 현재 API에 포함되지 않습니다.
---
url: https://react-native-text-motion.pages.dev/ko/api/component-props.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# 컴포넌트 Props
레시피의 `.component()`는 `TextMotionComponent`를 반환합니다. 두 기본 렌더러는 `TextMotionComponentProps`를 공통으로 사용합니다.
## 텍스트·스타일
| Prop | 타입 | 동작 |
| ----------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
| `children` | `string` | 필수 일반 문자열. 중첩 요소·배열·서식 있는 텍스트는 지원하지 않습니다. |
| `style` | `StyleProp` | 텍스트 스타일. `nativeText()`는 토큰 텍스트에, `overlayText()`는 측정할 문단에 적용합니다. |
| `testID` | `string` | 부모 컨테이너를 식별합니다. |
| `nativeID` | `string` | 부모 컨테이너에 전달합니다. |
| `allowFontScaling` | React Native `TextProps['allowFontScaling']` | 텍스트 렌더링에 전달합니다. |
| `maxFontSizeMultiplier` | React Native `TextProps['maxFontSizeMultiplier']` | 텍스트 렌더링에 전달합니다. |
TypeScript뿐 아니라 런타임에서도 문자열을 요구합니다. 명시적 줄바꿈은 `{'첫 번째 줄\n두 번째 줄'}` 같은 문자열 표현식으로 전달하세요. 모든 `Text`·`View` props가 전달된다고 가정하지 말고, 바깥 배치 제약은 감싸는 `View`에 지정하세요.
```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 (
읽기 좋은 모션을 위한 공간
);
}
```
## 재생
| Prop | 타입 | 동작 |
| ---------- | -------------------------------- | --------------------------------------------------------------------------------- |
| `controls` | `TextMotionControls` | 이벤트로 `play`, `replay`, `reset`, `stop`을 실행합니다. 내부 재생은 레시피의 `.motion()` 설정을 사용합니다. |
| `progress` | Reanimated `SharedValue` | 앱이 소유한 전체 텍스트 진행률입니다. 해당 인스턴스는 내부 자동 재생과 `.motion()`으로 움직이지 않습니다. |
**`controls`와 `progress`는 함께 사용할 수 없습니다.** TypeScript에서 조합을 거부하고 두 렌더러 모두 런타임에서도 오류를 던집니다. 둘 다 없으면 애니메이션 콘텐츠는 마운트 시 자동 재생합니다.
`progress`는 정규화된 값으로 `0`은 초기 상태, `1`은 최종 상태입니다. 범위를 벗어난 유한한 값은 보정하고, 유한하지 않은 값은 `0`으로 처리합니다. 타임라인 지연으로 단위별 진행률에 매핑하므로 표시된 문자 비율이 아닙니다. 전체 controls·progress 예제는 [재생 제어](https://react-native-text-motion.pages.dev/ko/guide/usage/playback.md)를 참고하세요.
## 접근성
지원하는 접근성 props는 다음과 같습니다.
- `accessibilityLabel`
- `accessibilityHint`
- `accessibilityRole`
- `accessibilityState`
- `accessibilityValue`
- `accessibilityActions`
- `accessibilityLanguage`
- `onAccessibilityAction`
기본 부모 레이블은 원문 전체이며, `accessibilityLabel`로 덮어쓸 수 있습니다. 부모의 접근 가능 여부와 장식용 노드 숨김은 정책에서 정합니다. `accessible` prop을 넘기는 대신 `.accessibility(parentLabelPolicy(...))`로 설정하세요. [접근성](https://react-native-text-motion.pages.dev/ko/guide/usage/accessibility.md)을 참고하세요.
## 생명주기
텍스트와 레시피가 같으면 일반적인 부모 리렌더에서 진행 중인 재생을 유지합니다. 텍스트 변경은 진입만 처리하며, 이전 텍스트를 종료 애니메이션·크로스페이드·토큰 비교를 위해 남겨 두지 않습니다. controls 모드에서 이후 명령은 현재 텍스트에 적용됩니다. 외부 progress 모드에서는 현재 공유 값이 새 텍스트의 상태를 결정합니다.
효과·타임라인·모션 설정이 달라지면 해당 애니메이션이 초기화될 수 있습니다. 부모 리렌더에서 재생을 유지하려면 레시피 컴포넌트와 함수 형태의 모션 옵션 참조를 안정적으로 유지하세요.
## 제한된 prop 범위
이 컴포넌트는 React Native `Text` 전체를 대체하지 않습니다. `numberOfLines`, `ellipsizeMode`, `lineBreakMode`, `onTextLayout`, `selectable`, 텍스트 `onPress`, 중첩된 서식 텍스트는 현재 계약에 포함되지 않습니다. 상호작용과 외부 배치는 적절한 바깥 컴포넌트에 지정하세요.
앱에서 타입을 사용할 수 있도록 루트에서 `TextMotionComponent`, `TextMotionComponentProps`, `TextMotionComponentTextProps`, `TextMotionComponentAccessibilityProps`를 내보냅니다. controls는 `useTextMotionControls()`와 공개 `TextMotionControls` 타입을 사용합니다. 공개 컴포넌트 ref나 context/provider 재생 API는 없습니다.
---
url: https://react-native-text-motion.pages.dev/ko/index.md
---
> For AI agents: the complete documentation index is available at https://react-native-text-motion.pages.dev/ko/llms.txt, the full documentation bundle is available at https://react-native-text-motion.pages.dev/ko/llms-full.txt.
# React Native Text Motion
글자에 리듬을 더하세요.
> 텍스트 분할, 렌더러, 타임라인, 효과를 조합해 재사용 가능한 애니메이션을 만드세요.
[빠르게 시작하기](/ko/guide/getting-started/quick-start.html) | [예제 살펴보기](/ko/guide/usage/examples.html)
## Features
- ✨ **프리셋으로 시작**: editorialRise, softWave, gentleEmphasis를 몇 줄의 코드로 재사용 가능한 컴포넌트로 만드세요.
- 🧩 **나만의 레시피**: 텍스트 분할 방식부터 토큰 렌더링, 시작 시점, 움직임까지 직접 조합하세요.
- 📐 **실제 렌더링된 줄의 움직임**: overlayText와 lineReveal로 React Native가 실제 배치한 줄을 애니메이션하세요.
- ⌨️ **레이아웃을 유지하는 타이핑**: 완성된 문장의 토큰 배치를 유지하면서 글자를 차례로 표시하세요.
- 🎛️ **명시적인 재생 제어**: 이벤트에서 controls로 다시 재생하거나 Reanimated 공유 값으로 진행률을 제어하세요.
- ♿ **읽을 수 있는 텍스트**: 스크린 리더에는 전체 문장을 한 번 전달하고 모션 줄이기 정책을 선택하세요.