Referência da API

Todos os exports de @kkwaenggwari/animated-chorus, com props, tipos e valores padrão. Os mesmos nomes funcionam na web e no React Native.

Filtrar17 APIs

Números e texto

MotionNumber

Um número cujas casas rolam como rodas.

Prop	Tipo	Padrão	Descrição
`value`	`number \| bigint \| string`	`—`obrigatória	O número, ou um texto numérico já formatado por quem chama.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` move cada casa alterada um passo; `roll` passa pelos dígitos intermediários.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` segue a mudança de grandeza, para o vai-um rolar em um sentido; `digit` compara cada casa por conta própria.
`stagger`	`number`	`45`	Milissegundos entre as casas alteradas, das unidades para fora. A onda inteira tem limite.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Uma função que retorna o texto a mostrar, ou opções de `Intl.NumberFormat` (com `intl`).
`intl`	`boolean`	`false`	Usa o `Intl.NumberFormat` embutido. Desligado por padrão para que nenhum ambiente precise de `Intl`.
`locale`	`string \| string[]`		Locale para `intl`.
`prefix`	`string`		Texto antes do número.
`suffix`	`string`		Texto depois do número.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.
`onMotionComplete`	`(value) => void`		Roda com o valor quando as casas se acomodam.

Página do componente e bancada

MotionText

Texto que anima quando muda: texto numérico rola por casa, os demais trocam.

Prop	Tipo	Padrão	Descrição
`children`	`ReactNode`		O texto a mostrar.
`as`	`element`	`'span'`	O elemento a renderizar.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.
`onMotionComplete`	`(text) => void`		Roda quando o movimento se acomoda.

Página do componente e bancada

MotionStream

Texto em streaming exibido em ritmo constante, que alcança as rajadas.

Prop	Tipo	Padrão	Descrição
`text`	`string`	`—`obrigatória	O texto até agora. Texto que cresce aparece em ritmo constante; uma reescrita continua do começo em comum.
`speed`	`number`	`90`	Velocidade base de exibição, em caracteres por segundo.
`catchUp`	`number`	`900`	Um acúmulo é exibido em cerca desse número de milissegundos, acelerando.
`initial`	`boolean`	`false`	Exibe aos poucos também o texto presente na montagem (senão ele aparece na hora).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` faz os caracteres novos aparecerem com fade; `none` os mostra direto.
`children`	`(visible: string) => ReactNode`		Uma função que recebe o texto no ritmo, por exemplo para renderizar Markdown.
`as`	`element`	`'span'`	O elemento a renderizar.
`onMotionComplete`	`(text) => void`		Roda sempre que a exibição alcança `text`.

Página do componente e bancada

Conteúdo e tamanho

MotionSwap

Conteúdo que faz crossfade enquanto o elemento muda de tamanho.

Prop	Tipo	Padrão	Descrição
`value`	`unknown`		Identidade do conteúdo; um valor novo dispara a troca. Filhos de texto simples são a própria identidade.
`children`	`ReactNode`		O conteúdo.
`as`	`element`	`'span'`	O elemento a renderizar.
`inline`	`boolean`	`as === 'span'`	`true` ajusta o tamanho ao conteúdo (rótulos, ícones); `false` ocupa a largura do pai e anima a altura.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Onde o conteúdo fica enquanto o tamanho muda.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	Como o conteúdo entra e sai: `up` sobe, `down` desce, `scale` cresce.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.
`onMotionComplete`	`(value) => void`		Roda quando o movimento se acomoda.

Página do componente e bancada

MotionHeight

Anima a altura conforme o conteúdo: recolher, expandir e mudanças de conteúdo.

Prop	Tipo	Padrão	Descrição
`open`	`boolean`	`true`	`false` recolhe até altura zero; o conteúdo continua montado, mas oculto e inerte.
`children`	`ReactNode`		O conteúdo.
`as`	`element`	`'div'`	O elemento a renderizar.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.
`onMotionComplete`	`(open) => void`		Roda com `open` quando a altura se acomoda.

Página do componente e bancada

MotionPresence

Mantém o conteúdo montado enquanto ele entra e sai animado.

Prop	Tipo	Padrão	Descrição
`present`	`boolean`	`—`obrigatória	Mostra ou oculta o conteúdo. Mude isto em vez de desmontar.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	A pose em repouso.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	A pose com que o conteúdo sai e a partir da qual entra.
`as`	`element`	`'div'`	O elemento a renderizar.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.
`onExitComplete`	`() => void`		Roda depois que o conteúdo saiu e foi removido.

Página do componente e bancada

Seleção e paginação

MotionHighlight

Itens a partir de dados com um destaque que viaja até o item selecionado.

Prop	Tipo	Padrão	Descrição
`items`	`readonly T[]`	`—`obrigatória	Seu array de dados.
`value`	`key \| null`	`—`obrigatória	Key do item destacado; `null` esconde o destaque.
`onValueChange`	`(key, item) => void`		Roda com a key e o item quando um item é pressionado.
`getKey`	`(item) => string \| number`	`item.id`	Retorna uma key única e estável para um item. Por padrão `item.id`, ou o próprio item para strings e números.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Desenha um item; recebe se ele está selecionado.
`hover`	`boolean`	`false`	Segue o ponteiro sobre os itens e volta para `value` ao sair (web).
`itemAs`	`element`	`'button'`	O elemento de cada item.
`itemClassName`	`string`		Classe do elemento de cada item; `itemStyle` define o estilo inline.
`highlightClassName`	`string`		Classe do destaque; `highlightStyle` define o estilo inline.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

MotionPager

Páginas deslizáveis a partir de dados.

Prop	Tipo	Padrão	Descrição
`items`	`readonly T[]`	`—`obrigatória	Seu array de dados.
`index`	`number`		A página exibida. Omita para o paginador cuidar da própria.
`defaultIndex`	`number`	`0`	Página inicial quando `index` não é controlado.
`onIndexChange`	`(index, item) => void`		Roda com o índice e o item assim que um deslize, uma tecla ou a roda do mouse se acomoda.
`getKey`	`(item) => string \| number`	`item.id`	Retorna uma key única e estável para um item. Por padrão `item.id`, ou o próprio item para strings e números.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Desenha uma página; recebe o índice e se ela está ativa.
`gap`	`number`	`0`	Espaço entre as páginas, em pixels.
`itemClassName`	`string`		Classe do elemento de cada item; `itemStyle` define o estilo inline.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

Listas

MotionList

Uma lista com keys, a partir de dados, que anima só o que mudou.

Prop	Tipo	Padrão	Descrição
`items`	`readonly T[]`	`—`obrigatória	Seu array de dados.
`getKey`	`(item) => string \| number`	`item.id`	Retorna uma key única e estável para um item. Por padrão `item.id`, ou o próprio item para strings e números.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Desenha um item.
`as`	`element`	`'div'`	O elemento a renderizar.
`itemAs`	`element`	`'li' \| 'div'`	O elemento de cada item.
`itemClassName`	`string`		Classe do elemento de cada item; `itemStyle` define o estilo inline.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	Como os itens entram e saem.
`distance`	`number`	`16`	Percurso de `rise` e `slide`, em pixels.
`stagger`	`number`	`40`	Milissegundos entre os itens que entram.
`order`	`'forward' \| 'reverse'`	`'forward'`	Direção do escalonamento.
`present`	`boolean`	`true`	`false` anima a saída de todos os itens mantendo o layout; `true` os traz de volta.
`initial`	`boolean`	`true`	Reproduz a entrada quando a lista é montada.
`playKey`	`string \| number`		Mudá-lo repete a entrada.
`transition`	`Transition`	`spring`	Transição dos itens que entram e saem.
`layoutTransition`	`Transition`	`spring`	Transição dos itens que deslizam até novas posições.

Página do componente e bancada

MotionReorder

Arraste para reordenar uma lista ou grade, com movimento por teclado.

Prop	Tipo	Padrão	Descrição
`items`	`readonly T[]`		Os itens, quando você controla a ordem.
`defaultItems`	`readonly T[]`	`[]`	Itens iniciais, quando o componente guarda a ordem.
`onItemsChange`	`(items, { reason, key }) => void`		Roda com a nova ordem e se ela veio de um arraste, de soltar ou do teclado.
`getKey`	`(item) => string \| number`	`item`	Retorna uma key única para um item. Por padrão, o próprio item.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Desenha um item; recebe o índice e se ele está sendo arrastado.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` move os outros itens durante o arraste; `drop` espera você soltar.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` ou `grid`.
`columns`	`number`	`3`	Colunas de uma grade.
`gap`	`number`	`12`	Espaço entre os itens, em pixels.
`disabled`	`boolean`	`false`	Desliga o arraste.
`duration`	`number`	`260`	Milissegundos para os itens que abrem espaço.
`itemClassName`	`string`		Classe do elemento de cada item; `itemStyle` define o estilo inline.

Página do componente e bancada

Gestos

MotionSwipe

Uma linha que revela ações com um deslize horizontal e pode ser descartada deslizando.

Prop	Tipo	Padrão	Descrição
`children`	`ReactNode`		O conteúdo da linha.
`startActions`	`ReactNode`		Aparecem no começo da linha quando ela é arrastada para o fim.
`endActions`	`ReactNode`		Aparecem no fim da linha quando ela é arrastada para o começo.
`dismiss`	`'start' \| 'end' \| 'both'`		Lados em que um deslize longo ou um arremesso remove a linha.
`onDismiss`	`(side) => void`		Roda depois que a linha saiu e foi recolhida; remova o item dos seus dados aqui.
`onOpenChange`	`(side \| null) => void`		Roda com o lado aberto, ou `null` quando a linha fecha.
`disabled`	`boolean`	`false`	Desliga o deslize.
`contentClassName`	`string`		Classe do conteúdo da linha; `contentStyle` define o estilo inline.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

MotionHold

Pressione e segure para confirmar; soltar antes volta atrás.

Prop	Tipo	Padrão	Descrição
`children`	`ReactNode`		O rótulo do botão.
`onConfirm`	`() => void`		Roda uma vez quando o tempo de segurar se completa.
`duration`	`number`	`1200`	Milissegundos que é preciso segurar.
`disabled`	`boolean`	`false`	Desativa o botão.
`fillClassName`	`string`		Classe do preenchimento que cresce; `fillStyle` define o estilo inline.

Página do componente e bancada

Sobreposições

MotionSheet

Um bottom sheet, top sheet ou gaveta lateral com pontos de parada.

Prop	Tipo	Padrão	Descrição
`open`	`boolean`	`false`	Se o sheet está visível.
`onOpenChange`	`(open) => void`		Roda com `false` quando o sheet é fechado por arraste, toque ou Escape.
`detents`	`(number \| 'content')[]`	`['content']`	Tamanhos de repouso: uma fração da tela, pixels ou `'content'`.
`detent`	`number`		Índice controlado do ponto de parada.
`defaultDetent`	`number`	`0`	Índice do ponto de parada usado ao abrir sem `detent`.
`onDetentChange`	`(index) => void`		Roda com o índice do ponto em que o sheet se acomoda.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	A borda de onde o sheet vem.
`modal`	`boolean`	`true`	Adiciona um fundo, mantém o foco dentro e deixa a página inerte.
`dismissible`	`boolean`	`true`	Arrastar além do menor ponto de parada, o fundo e Escape o fecham.
`backdropClassName`	`string`		Classe do fundo; `backdropStyle` define o estilo inline.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

MotionZoom

Uma imagem que amplia de onde está até preencher a tela.

Prop	Tipo	Padrão	Descrição
`src`	`string`		A imagem exibida no lugar.
`zoomSrc`	`string`		Uma imagem maior exibida depois de carregar; mantenha a mesma proporção.
`margin`	`number`	`24`	Espaço mantido em volta da imagem ampliada, em pixels.
`disabled`	`boolean`	`false`	Desliga o zoom.
`onZoomChange`	`(zoomed) => void`		Roda com `true` ao ampliar e `false` ao fechar.
`backdropStyle`	`CSSProperties`		Estilo inline do fundo.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

Progresso

ProgressBar

Uma linha de progresso controlada, com estado indeterminado.

Prop	Tipo	Padrão	Descrição
`value`	`number \| null`		Progresso de `0` a `max`; `null` é indeterminado.
`max`	`number`	`100`	O valor que significa concluído.
`color`	`string`	`'currentColor'`	Cor do preenchimento.
`trackColor`	`string`	`'#e7ece9'`	Cor da trilha.
`thickness`	`number`	`8`	Espessura da linha, em pixels.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Preencher pela esquerda (`ltr`) ou pela direita (`rtl`).
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

ProgressRing

Um anel de progresso controlado, com estado indeterminado.

Prop	Tipo	Padrão	Descrição
`value`	`number \| null`		Progresso de `0` a `max`; `null` é indeterminado.
`max`	`number`	`100`	O valor que significa concluído.
`size`	`number`	`96`	Diâmetro, em pixels.
`thickness`	`number`	`8`	Espessura do anel, em pixels.
`color`	`string`	`'currentColor'`	Cor do arco.
`trackColor`	`string`	`'#e7ece9'`	Cor da trilha.
`children`	`ReactNode`		Um rótulo exibido no centro.
`transition`	`Transition`	`spring`	Uma curva de tempo `{ duration, easing }` ou uma mola `{ tempo: 'spring', spring }`. As molas mantêm o embalo quando interrompidas.

Página do componente e bancada

Transições

motionTokens

Valores prontos para qualquer prop transition.

Prop	Tipo	Padrão	Descrição
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Durações em milissegundos.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Transições de tempo com duração e uma curva nomeada.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Transições de mola, das rápidas e firmes às suaves e saltitantes.

Transições

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