API 레퍼런스

@kkwaenggwari/animated-chorus의 모든 내보내기와 props, 타입, 기본값입니다. 같은 이름이 웹과 React Native에서 동작합니다.

필터API 17개

숫자와 글

MotionNumber

자리마다 바퀴처럼 구르는 숫자.

Prop	타입	기본값	설명
`value`	`number \| bigint \| string`	`—`필수	숫자, 또는 호출자가 서식을 입힌 숫자 글자.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace`는 바뀐 자리를 한 칸 옮기고, `roll`은 사이의 숫자를 거쳐 갑니다.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto`는 크기 변화를 따라 올림이 한 방향으로 구르고, `digit`은 자리마다 따로 비교합니다.
`stagger`	`number`	`45`	일의 자리부터 바깥으로, 바뀐 자리 사이의 밀리초. 전체 물결 시간은 제한됩니다.
`format`	`(value) => string \| Intl.NumberFormatOptions`		보여 줄 글자를 돌려주는 함수, 또는 `Intl.NumberFormat` 옵션(`intl`과 함께).
`intl`	`boolean`	`false`	내장 `Intl.NumberFormat`을 씁니다. 기본으로 꺼져 있어 어떤 런타임도 `Intl`이 필요 없습니다.
`locale`	`string \| string[]`		`intl`에 쓸 로캘.
`prefix`	`string`		숫자 앞 글자.
`suffix`	`string`		숫자 뒤 글자.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(value) => void`		자리가 모두 멈추면 값과 함께 실행됩니다.

컴포넌트 페이지와 작업대

MotionText

바뀔 때 움직이는 글자. 숫자 글자는 자리마다 구르고 다른 글자는 교체됩니다.

Prop	타입	기본값	설명
`children`	`ReactNode`		보여 줄 글자.
`as`	`element`	`'span'`	그릴 요소.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(text) => void`		움직임이 멈추면 실행됩니다.

컴포넌트 페이지와 작업대

MotionStream

몰려오는 스트리밍 글을 일정한 속도로 보여 주고 밀리면 따라잡습니다.

Prop	타입	기본값	설명
`text`	`string`	`—`필수	지금까지의 글. 늘어나는 글은 일정한 속도로 드러나고, 다시 쓰이면 같은 앞부분에서 이어갑니다.
`speed`	`number`	`90`	초당 글자 수로 정한 기본 공개 속도.
`catchUp`	`number`	`900`	쌓인 글을 속도를 올려 약 이 밀리초 안에 보여 줍니다.
`initial`	`boolean`	`false`	마운트할 때 이미 있던 글도 드러냅니다(아니면 바로 보임).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade`는 새 글자를 페이드인하고 `none`은 바로 보여 줍니다.
`children`	`(visible: string) => ReactNode`		속도가 맞춰진 글을 받는 함수. 예를 들어 Markdown을 그릴 때.
`as`	`element`	`'span'`	그릴 요소.
`onMotionComplete`	`(text) => void`		공개가 `text`를 따라잡을 때마다 실행됩니다.

컴포넌트 페이지와 작업대

내용과 크기

MotionSwap

요소 크기가 바뀌는 동안 서로 교차해 바뀌는 내용.

Prop	타입	기본값	설명
`value`	`unknown`		내용의 정체. 새 값이면 교체합니다. 일반 글자 자식은 그 자체가 정체입니다.
`children`	`ReactNode`		내용.
`as`	`element`	`'span'`	그릴 요소.
`inline`	`boolean`	`as === 'span'`	`true`는 내용에 크기를 맞추고(라벨, 아이콘) `false`는 부모 너비를 채우고 높이를 움직입니다.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	크기가 바뀌는 동안 내용이 놓이는 위치.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	들어오고 나가는 방식. `up`은 올라오고, `down`은 내려오고, `scale`은 커집니다.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(value) => void`		움직임이 멈추면 실행됩니다.

컴포넌트 페이지와 작업대

MotionHeight

높이를 내용에 맞춰 움직입니다. 접기, 펼치기, 내용 변화까지.

Prop	타입	기본값	설명
`open`	`boolean`	`true`	`false`면 높이 0으로 접힙니다. 내용은 마운트된 채 숨겨지고 비활성이 됩니다.
`children`	`ReactNode`		내용.
`as`	`element`	`'div'`	그릴 요소.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onMotionComplete`	`(open) => void`		높이가 멈추면 `open`과 함께 실행됩니다.

컴포넌트 페이지와 작업대

MotionPresence

나타나고 사라지는 동안 내용을 마운트한 채 유지합니다.

Prop	타입	기본값	설명
`present`	`boolean`	`—`필수	내용을 보이거나 숨깁니다. 마운트를 해제하는 대신 이것을 바꾸세요.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	머무는 자세.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	사라질 때의 자세이자 다시 들어올 때의 출발 자세.
`as`	`element`	`'div'`	그릴 요소.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.
`onExitComplete`	`() => void`		내용이 사라져 제거된 뒤 실행됩니다.

컴포넌트 페이지와 작업대

선택과 넘기기

MotionHighlight

데이터로 만든 항목과 선택 항목으로 이동하는 하이라이트 하나.

Prop	타입	기본값	설명
`items`	`readonly T[]`	`—`필수	내 데이터 배열.
`value`	`key \| null`	`—`필수	하이라이트할 항목의 키. `null`이면 하이라이트를 숨깁니다.
`onValueChange`	`(key, item) => void`		항목을 누르면 키와 항목으로 실행됩니다.
`getKey`	`(item) => string \| number`	`item.id`	항목의 고유하고 안정적인 키를 돌려줍니다. 기본값은 `item.id`, 문자열과 숫자는 그 값 자체입니다.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	항목을 그립니다. 선택 여부를 받습니다.
`hover`	`boolean`	`false`	항목 위의 포인터를 따라가다 벗어나면 `value`로 돌아옵니다(웹).
`itemAs`	`element`	`'button'`	각 항목의 요소.
`itemClassName`	`string`		각 항목 요소의 클래스. 인라인 스타일은 `itemStyle`.
`highlightClassName`	`string`		하이라이트의 클래스. 인라인 스타일은 `highlightStyle`.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

MotionPager

데이터로 만드는 넘기는 페이지.

Prop	타입	기본값	설명
`items`	`readonly T[]`	`—`필수	내 데이터 배열.
`index`	`number`		보여 줄 페이지. 생략하면 페이저가 직접 관리합니다.
`defaultIndex`	`number`	`0`	`index`를 제어하지 않을 때의 시작 페이지.
`onIndexChange`	`(index, item) => void`		스와이프, 키, 휠 동작이 멈추는 즉시 인덱스와 항목으로 실행됩니다.
`getKey`	`(item) => string \| number`	`item.id`	항목의 고유하고 안정적인 키를 돌려줍니다. 기본값은 `item.id`, 문자열과 숫자는 그 값 자체입니다.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	페이지를 그립니다. 인덱스와 현재 페이지 여부를 받습니다.
`gap`	`number`	`0`	페이지 사이 간격(픽셀).
`itemClassName`	`string`		각 항목 요소의 클래스. 인라인 스타일은 `itemStyle`.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

MotionList

바뀐 항목만 움직이는, 키가 있는 데이터 목록.

Prop	타입	기본값	설명
`items`	`readonly T[]`	`—`필수	내 데이터 배열.
`getKey`	`(item) => string \| number`	`item.id`	항목의 고유하고 안정적인 키를 돌려줍니다. 기본값은 `item.id`, 문자열과 숫자는 그 값 자체입니다.
`renderItem`	`(item, index) => ReactNode`	`item.label`	항목을 그립니다.
`as`	`element`	`'div'`	그릴 요소.
`itemAs`	`element`	`'li' \| 'div'`	각 항목의 요소.
`itemClassName`	`string`		각 항목 요소의 클래스. 인라인 스타일은 `itemStyle`.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	항목이 들어오고 나가는 방식.
`distance`	`number`	`16`	`rise`와 `slide`의 이동 거리(픽셀).
`stagger`	`number`	`40`	들어오는 항목 사이의 밀리초.
`order`	`'forward' \| 'reverse'`	`'forward'`	시간차의 방향.
`present`	`boolean`	`true`	`false`면 레이아웃을 유지한 채 모든 항목을 내보내고, `true`면 되돌립니다.
`initial`	`boolean`	`true`	목록이 마운트될 때 입장을 재생합니다.
`playKey`	`string \| number`		바꾸면 입장을 다시 재생합니다.
`transition`	`Transition`	`spring`	들어오고 나가는 항목의 전환.
`layoutTransition`	`Transition`	`spring`	새 위치로 미끄러지는 항목의 전환.

컴포넌트 페이지와 작업대

MotionReorder

끌어서 순서를 바꾸는 목록과 격자. 키보드로도 옮깁니다.

Prop	타입	기본값	설명
`items`	`readonly T[]`		순서를 직접 제어할 때의 항목.
`defaultItems`	`readonly T[]`	`[]`	컴포넌트가 순서를 관리할 때의 시작 항목.
`onItemsChange`	`(items, { reason, key }) => void`		새 순서와, 변경이 드래그·놓기·키보드 중 어디서 왔는지로 실행됩니다.
`getKey`	`(item) => string \| number`	`item`	항목의 고유한 키를 돌려줍니다. 기본값은 항목 자체입니다.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	항목을 그립니다. 인덱스와 끌리는 중인지를 받습니다.
`reorder`	`'live' \| 'drop'`	`'live'`	`live`는 끄는 동안 다른 항목을 옮기고, `drop`은 놓을 때까지 기다립니다.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` 또는 `grid`.
`columns`	`number`	`3`	격자의 열 수.
`gap`	`number`	`12`	항목 사이 간격(픽셀).
`disabled`	`boolean`	`false`	끌기를 끕니다.
`duration`	`number`	`260`	비켜 주는 항목의 이동 시간(밀리초).
`itemClassName`	`string`		각 항목 요소의 클래스. 인라인 스타일은 `itemStyle`.

컴포넌트 페이지와 작업대

제스처

MotionSwipe

가로로 밀어 동작을 드러내고 밀어서 치울 수 있는 행.

Prop	타입	기본값	설명
`children`	`ReactNode`		행의 내용.
`startActions`	`ReactNode`		행을 끝 방향으로 끌 때 시작 쪽에 드러납니다.
`endActions`	`ReactNode`		행을 시작 방향으로 끌 때 끝 쪽에 드러납니다.
`dismiss`	`'start' \| 'end' \| 'both'`		길게 밀거나 던지면 행을 치우는 쪽.
`onDismiss`	`(side) => void`		행이 밀려 나가고 접힌 뒤 실행됩니다. 여기서 데이터의 항목을 지우세요.
`onOpenChange`	`(side \| null) => void`		열린 쪽으로, 닫히면 `null`로 실행됩니다.
`disabled`	`boolean`	`false`	밀기를 끕니다.
`contentClassName`	`string`		행 내용의 클래스. 인라인 스타일은 `contentStyle`.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

MotionHold

길게 눌러 확정합니다. 일찍 떼면 되감깁니다.

Prop	타입	기본값	설명
`children`	`ReactNode`		버튼 라벨.
`onConfirm`	`() => void`		누르기가 끝까지 채워지면 한 번 실행됩니다.
`duration`	`number`	`1200`	눌러야 하는 밀리초.
`disabled`	`boolean`	`false`	버튼을 끕니다.
`fillClassName`	`string`		자라는 채움의 클래스. 인라인 스타일은 `fillStyle`.

컴포넌트 페이지와 작업대

겹침 화면

MotionSheet

멈춤 위치가 있는 아래·위 시트와 옆 서랍.

Prop	타입	기본값	설명
`open`	`boolean`	`false`	시트를 보일지 여부.
`onOpenChange`	`(open) => void`		시트를 끌어서, 눌러서, Escape로 닫으면 `false`로 실행됩니다.
`detents`	`(number \| 'content')[]`	`['content']`	멈추는 크기. 화면 비율, 픽셀, 또는 `'content'`.
`detent`	`number`		제어하는 멈춤 위치 인덱스.
`defaultDetent`	`number`	`0`	`detent` 없이 열 때 쓰는 멈춤 위치 인덱스.
`onDetentChange`	`(index) => void`		시트가 멈춘 위치의 인덱스로 실행됩니다.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	시트가 나오는 가장자리.
`modal`	`boolean`	`true`	배경을 깔고 포커스를 안에 가두며 페이지를 비활성으로 만듭니다.
`dismissible`	`boolean`	`true`	가장 작은 멈춤 위치 너머로 끌기, 배경, Escape로 닫힙니다.
`backdropClassName`	`string`		배경의 클래스. 인라인 스타일은 `backdropStyle`.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

MotionZoom

제자리에서 화면 전체로 커지는 이미지.

Prop	타입	기본값	설명
`src`	`string`		제자리에 보이는 이미지.
`zoomSrc`	`string`		다 불러오면 보여 줄 더 큰 이미지. 가로세로 비율을 같게 두세요.
`margin`	`number`	`24`	확대한 이미지 둘레에 남길 간격(픽셀).
`disabled`	`boolean`	`false`	확대를 끕니다.
`onZoomChange`	`(zoomed) => void`		확대하면 `true`, 닫으면 `false`로 실행됩니다.
`backdropStyle`	`CSSProperties`		배경의 인라인 스타일.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

진행

ProgressBar

알 수 없는 상태도 있는 제어형 진행 막대.

Prop	타입	기본값	설명
`value`	`number \| null`		`0`부터 `max`까지의 진행. `null`은 알 수 없는 진행입니다.
`max`	`number`	`100`	완료를 뜻하는 값.
`color`	`string`	`'currentColor'`	채움 색.
`trackColor`	`string`	`'#e7ece9'`	바탕 색.
`thickness`	`number`	`8`	선 두께(픽셀).
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	왼쪽부터(`ltr`) 또는 오른쪽부터(`rtl`) 채웁니다.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

ProgressRing

알 수 없는 상태도 있는 제어형 진행 링.

Prop	타입	기본값	설명
`value`	`number \| null`		`0`부터 `max`까지의 진행. `null`은 알 수 없는 진행입니다.
`max`	`number`	`100`	완료를 뜻하는 값.
`size`	`number`	`96`	지름(픽셀).
`thickness`	`number`	`8`	링 두께(픽셀).
`color`	`string`	`'currentColor'`	호 색.
`trackColor`	`string`	`'#e7ece9'`	바탕 색.
`children`	`ReactNode`		가운데 보여 줄 라벨.
`transition`	`Transition`	`spring`	시간 곡선 `{ duration, easing }` 또는 스프링 `{ tempo: 'spring', spring }`. 스프링은 끊겨도 속도를 이어갑니다.

컴포넌트 페이지와 작업대

전환

motionTokens

어떤 transition prop에도 넣을 수 있는 준비된 값.

Prop	타입	기본값	설명
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	밀리초 단위 시간.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	시간과 이름 붙은 곡선으로 된 시간 전환.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	빠르고 단단한 것부터 부드럽고 통통 튀는 것까지의 스프링 전환.

전환

App.jsx

// Web and React Native: the same import.
import { MotionNumber, MotionList } from '@kkwaenggwari/animated-chorus';

export function Score({ points, players }) {
  return (
    <>
      <MotionNumber value={points} />
      <MotionList items={players} renderItem={(player) => player.name} />
    </>
  );
}