예제

라이브 미리보기는 React Native Web에서 실제 라이브러리를 실행합니다. 네이티브 줄 측정이 필요한 예제는 iOS 녹화로 표시합니다.

아래 예제는 현재 공개 API를 사용합니다. 설치를 마친 React Native 앱에서 실행하세요. 각 예제 옆의 미리보기에서 움직임을 확인하고 다시 재생할 수 있습니다.

프리셋으로 시작하기

editorialRise()React Native Web

프리셋은 /presets 경로에서 가져오는 레시피 팩토리입니다. 컴포넌트는 렌더 함수 밖에서 한 번 만드세요.

import { editorialRise } from '@react-native-motion-kit/text-motion/presets';

const HeroTitle = editorialRise().component();

export function Hero() {
  return (
    <HeroTitle style={{ fontSize: 32, fontWeight: '700' }}>
      자연스럽게 느껴지는 텍스트 모션
    </HeroTitle>
  );
}

softWave()와 gentleEmphasis()는 프리셋을 참고하세요.

단어 진입 효과와 다시 재생

play() / replay() / reset() / stop()React Native Web

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 (
    <View>
      <WordReveal controls={controls}>단어마다 작은 움직임을 더합니다.</WordReveal>
      <Button title="다시 재생" onPress={controls.replay} />
    </View>
  );
}

stagger(0.04)는 시작 간격을 40ms로 설정하고, duration: 360은 토큰별 모션 시간을 밀리초로 설정합니다. controls를 전달해도 마운트 시 자동 재생은 유지됩니다. 외부 진행률과 전체 명령은 재생 제어를 참고하세요.

실제 렌더링된 줄 표시하기

overlayText() + lineReveal()iOS 녹화

사용 가능한 너비에 맞춰 제목이 줄바꿈돼야 한다면 네이티브가 렌더링한 줄을 사용하세요. 이 레시피에는 splitter를 추가하지 않습니다.

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 (
    <View style={{ width: 280 }}>
      <LineTitle style={{ fontSize: 32, lineHeight: 40, fontWeight: '700' }}>
        레이아웃이 실제로 렌더링한 줄에 맞춰 제목을 움직입니다
      </LineTitle>
    </View>
  );
}

overlayText()는 너비, 글꼴, 글꼴 배율, 글자 조형이 적용된 문단을 측정합니다. lines()는 명시적인 줄바꿈 문자만 나눕니다. 렌더러를 참고하세요.

너비가 바뀌어도 진행률 유지하기

overlayText() · width reflowiOS 녹화

이 iOS 녹화는 명시적 줄바꿈이 없는 긴 영문 문단을 사용합니다. 네이티브 예제의 Narrow와 Wide는 React Native 레이아웃 너비를 220과 320으로 전환합니다. 진행률 컨트롤로 너비 변경 전후에 progress를 0.5로 유지한 뒤 각 너비에서 다시 재생하며, 새로 측정한 원문 문단에 맞춰 마스크가 배치되는지 확인할 수 있습니다.

레이아웃을 유지하는 Typewriter

typewriter()React Native Web

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 (
    <View>
      <TypewriterText controls={controls}>안녕, 한글! 👩🏽‍💻</TypewriterText>
      <Button title="다시 재생" onPress={controls.replay} />
      <Button title="초기화" onPress={controls.reset} />
      <Button title="정지" onPress={controls.stop} />
    </View>
  );
}

완성된 문장의 공간을 처음부터 확보합니다. 보이는 토큰은 타임라인의 시작 시점에 표시되고, 공백과 명시적 줄바꿈은 지연 슬롯 없이 공간을 유지합니다. duration: 0은 토큰별 표시를 즉시 처리합니다. Typewriter는 nativeText()가 필요하며 커서, 스트리밍, 단일 Text와 정확히 같은 줄바꿈을 제공하지 않습니다.

다른 문장을 처음부터 입력하려면 새 React key로 다시 마운트하세요. 문자열을 이어 붙이는 방식은 스트리밍 API가 아닙니다. 효과 조합은 효과, 문자소 폴백의 한계는 문자 분할을 참고하세요.

저장소 예제 실행

저장소 루트에서 .nvmrc와 package.json에 고정된 Node·pnpm 버전을 사용하세요.

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를 확인하세요. 측정 기록 방법은 성능을 참고하세요.

#예제

#프리셋으로 시작하기

#단어 진입 효과와 다시 재생

#실제 렌더링된 줄 표시하기

#너비가 바뀌어도 진행률 유지하기

#레이아웃을 유지하는 Typewriter