API reference

Every export of @kkwaenggwari/animated-chorus with its props, types and defaults. The same names work on the web and React Native.

Filter17 APIs

Numbers and text

MotionNumber

A number whose places roll like wheels.

Prop	Type	Default	Description
`value`	`number \| bigint \| string`	`—`required	The number, or caller-formatted numeric text.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` moves each changed place one step; `roll` passes through the digits in between.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` follows the change in size so carries roll one way; `digit` compares each place on its own.
`stagger`	`number`	`45`	Milliseconds between changed places, from the units outward. The whole ripple is bounded.
`format`	`(value) => string \| Intl.NumberFormatOptions`		A function that returns the text to show, or `Intl.NumberFormat` options (with `intl`).
`intl`	`boolean`	`false`	Use the built-in `Intl.NumberFormat`. Off by default so no runtime needs `Intl`.
`locale`	`string \| string[]`		Locale for `intl`.
`prefix`	`string`		Text before the number.
`suffix`	`string`		Text after the number.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(value) => void`		Runs with the value once the places have settled.

Component page and workbench

MotionText

Text that animates when it changes: numeric text rolls per place, other text swaps.

Prop	Type	Default	Description
`children`	`ReactNode`		The text to show.
`as`	`element`	`'span'`	The element to render.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(text) => void`		Runs when the motion settles.

Component page and workbench

MotionStream

Streamed text revealed at a steady pace that catches up with bursts.

Prop	Type	Default	Description
`text`	`string`	`—`required	The text so far. Growing text is revealed at a steady pace; a rewrite continues from the shared start.
`speed`	`number`	`90`	Base reveal rate in characters per second.
`catchUp`	`number`	`900`	A backlog is revealed within about this many milliseconds by speeding up.
`initial`	`boolean`	`false`	Also reveal the text present on mount (otherwise it shows at once).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` fades new characters in; `none` shows them directly.
`children`	`(visible: string) => ReactNode`		A function that receives the paced text, for example to render Markdown.
`as`	`element`	`'span'`	The element to render.
`onMotionComplete`	`(text) => void`		Runs whenever the reveal catches up with `text`.

Component page and workbench

Content and size

MotionSwap

Content that cross-fades while the element resizes.

Prop	Type	Default	Description
`value`	`unknown`		Identity of the content; a new value swaps. Plain text children are their own identity.
`children`	`ReactNode`		The content.
`as`	`element`	`'span'`	The element to render.
`inline`	`boolean`	`as === 'span'`	`true` sizes to the content (labels, icons); `false` fills the parent width and animates height.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Where the content sits while the size changes.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	How content enters and leaves: `up` rises, `down` falls, `scale` grows.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(value) => void`		Runs when the motion settles.

Component page and workbench

MotionHeight

Animates height to its content: collapse, expand and content changes.

Prop	Type	Default	Description
`open`	`boolean`	`true`	`false` collapses to zero height; the content stays mounted but hidden and inert.
`children`	`ReactNode`		The content.
`as`	`element`	`'div'`	The element to render.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onMotionComplete`	`(open) => void`		Runs with `open` once the height has settled.

Component page and workbench

MotionPresence

Keeps content mounted while it animates in and out.

Prop	Type	Default	Description
`present`	`boolean`	`—`required	Show or hide the content. Change this instead of unmounting.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	The pose at rest.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	The pose the content leaves with and enters from.
`as`	`element`	`'div'`	The element to render.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.
`onExitComplete`	`() => void`		Runs after the content has left and been removed.

Component page and workbench

Selection and paging

MotionHighlight

Items from data with one highlight that travels to the selected item.

Prop	Type	Default	Description
`items`	`readonly T[]`	`—`required	Your data array.
`value`	`key \| null`	`—`required	Key of the highlighted item; `null` hides the highlight.
`onValueChange`	`(key, item) => void`		Runs with the key and the item when an item is pressed.
`getKey`	`(item) => string \| number`	`item.id`	Returns a unique, stable key for an item. Defaults to `item.id`, or the item itself for strings and numbers.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Draws an item; receives whether it is selected.
`hover`	`boolean`	`false`	Follow the pointer over items and return to `value` on leave (web).
`itemAs`	`element`	`'button'`	The element for each item.
`itemClassName`	`string`		Class for each item element; `itemStyle` sets its inline style.
`highlightClassName`	`string`		Class for the highlight; `highlightStyle` sets its inline style.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

MotionPager

Swipeable pages from data.

Prop	Type	Default	Description
`items`	`readonly T[]`	`—`required	Your data array.
`index`	`number`		The page shown. Leave it out to let the pager keep its own.
`defaultIndex`	`number`	`0`	Starting page when `index` is not controlled.
`onIndexChange`	`(index, item) => void`		Runs with the index and item as soon as a swipe, key or wheel gesture settles.
`getKey`	`(item) => string \| number`	`item.id`	Returns a unique, stable key for an item. Defaults to `item.id`, or the item itself for strings and numbers.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Draws a page; receives its index and whether it is active.
`gap`	`number`	`0`	Space between pages in pixels.
`itemClassName`	`string`		Class for each item element; `itemStyle` sets its inline style.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

Lists

MotionList

A keyed list from data that animates only what changed.

Prop	Type	Default	Description
`items`	`readonly T[]`	`—`required	Your data array.
`getKey`	`(item) => string \| number`	`item.id`	Returns a unique, stable key for an item. Defaults to `item.id`, or the item itself for strings and numbers.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Draws an item.
`as`	`element`	`'div'`	The element to render.
`itemAs`	`element`	`'li' \| 'div'`	The element for each item.
`itemClassName`	`string`		Class for each item element; `itemStyle` sets its inline style.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	How items enter and leave.
`distance`	`number`	`16`	Travel of `rise` and `slide` in pixels.
`stagger`	`number`	`40`	Milliseconds between entering items.
`order`	`'forward' \| 'reverse'`	`'forward'`	Direction of the stagger.
`present`	`boolean`	`true`	`false` animates every item out while keeping the layout; `true` brings them back.
`initial`	`boolean`	`true`	Play the entrance when the list mounts.
`playKey`	`string \| number`		Changing it replays the entrance.
`transition`	`Transition`	`spring`	Transition for entering and leaving items.
`layoutTransition`	`Transition`	`spring`	Transition for items gliding to new positions.

Component page and workbench

MotionReorder

Drag to reorder a list or a grid, with keyboard moves.

Prop	Type	Default	Description
`items`	`readonly T[]`		The items, when you control the order.
`defaultItems`	`readonly T[]`	`[]`	Starting items, when the component keeps the order.
`onItemsChange`	`(items, { reason, key }) => void`		Runs with the new order and whether it came from a drag, a drop or the keyboard.
`getKey`	`(item) => string \| number`	`item`	Returns a unique key for an item. Defaults to the item itself.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Draws an item; receives its index and whether it is being dragged.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` moves other items while dragging; `drop` waits for the drop.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` or `grid`.
`columns`	`number`	`3`	Columns in a grid.
`gap`	`number`	`12`	Space between items in pixels.
`disabled`	`boolean`	`false`	Turns dragging off.
`duration`	`number`	`260`	Milliseconds for items moving out of the way.
`itemClassName`	`string`		Class for each item element; `itemStyle` sets its inline style.

Component page and workbench

Gestures

MotionSwipe

A row that reveals actions with a horizontal swipe and can be swiped away.

Prop	Type	Default	Description
`children`	`ReactNode`		The row content.
`startActions`	`ReactNode`		Revealed at the inline start when the row is dragged toward the end.
`endActions`	`ReactNode`		Revealed at the inline end when the row is dragged toward the start.
`dismiss`	`'start' \| 'end' \| 'both'`		Sides where a long swipe or a throw removes the row.
`onDismiss`	`(side) => void`		Runs after the row slid out and collapsed; remove the item from your data here.
`onOpenChange`	`(side \| null) => void`		Runs with the open side, or `null` when the row closes.
`disabled`	`boolean`	`false`	Turns swiping off.
`contentClassName`	`string`		Class for the row content; `contentStyle` sets its inline style.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

MotionHold

Press and hold to confirm; releasing early rewinds.

Prop	Type	Default	Description
`children`	`ReactNode`		The button label.
`onConfirm`	`() => void`		Runs once the hold completes.
`duration`	`number`	`1200`	Milliseconds the press must be held.
`disabled`	`boolean`	`false`	Turns the button off.
`fillClassName`	`string`		Class for the growing fill; `fillStyle` sets its inline style.

Component page and workbench

Overlays

MotionSheet

A bottom sheet, top sheet or side drawer with detents.

Prop	Type	Default	Description
`open`	`boolean`	`false`	Whether the sheet is shown.
`onOpenChange`	`(open) => void`		Runs with `false` when the sheet is dragged, tapped or escaped closed.
`detents`	`(number \| 'content')[]`	`['content']`	Resting sizes: a fraction of the screen, pixels, or `'content'`.
`detent`	`number`		Controlled detent index.
`defaultDetent`	`number`	`0`	Detent index used when opening without `detent`.
`onDetentChange`	`(index) => void`		Runs with the index of the detent the sheet settles on.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	The edge the sheet comes from.
`modal`	`boolean`	`true`	Adds a backdrop, keeps focus inside and makes the page inert.
`dismissible`	`boolean`	`true`	Dragging past the smallest detent, the backdrop and Escape close it.
`backdropClassName`	`string`		Class for the backdrop; `backdropStyle` sets its inline style.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

MotionZoom

An image that zooms from where it is to fill the screen.

Prop	Type	Default	Description
`src`	`string`		The image shown in place.
`zoomSrc`	`string`		A larger image shown once it has loaded; keep the same aspect ratio.
`margin`	`number`	`24`	Space kept around the zoomed image in pixels.
`disabled`	`boolean`	`false`	Turns zooming off.
`onZoomChange`	`(zoomed) => void`		Runs with `true` when zoomed and `false` when closed.
`backdropStyle`	`CSSProperties`		Inline style for the backdrop.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

Progress

ProgressBar

A controlled progress line with an indeterminate state.

Prop	Type	Default	Description
`value`	`number \| null`		Progress from `0` to `max`; `null` is indeterminate.
`max`	`number`	`100`	The value that means complete.
`color`	`string`	`'currentColor'`	Fill color.
`trackColor`	`string`	`'#e7ece9'`	Track color.
`thickness`	`number`	`8`	Line thickness in pixels.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Fill from the left (`ltr`) or from the right (`rtl`).
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

ProgressRing

A controlled progress ring with an indeterminate state.

Prop	Type	Default	Description
`value`	`number \| null`		Progress from `0` to `max`; `null` is indeterminate.
`max`	`number`	`100`	The value that means complete.
`size`	`number`	`96`	Diameter in pixels.
`thickness`	`number`	`8`	Ring thickness in pixels.
`color`	`string`	`'currentColor'`	Arc color.
`trackColor`	`string`	`'#e7ece9'`	Track color.
`children`	`ReactNode`		A label shown in the middle.
`transition`	`Transition`	`spring`	A timing curve `{ duration, easing }` or a spring `{ tempo: 'spring', spring }`. Springs keep their momentum when interrupted.

Component page and workbench

Transitions

motionTokens

Ready-made values for any transition prop.

Prop	Type	Default	Description
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Durations in milliseconds.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Timing transitions with a duration and a named curve.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Spring transitions, from quick and firm to gentle and bouncy.

Transitions

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} />
    </>
  );
}