Riferimento API

Ogni export di @kkwaenggwari/animated-chorus con le sue props, i tipi e i valori predefiniti. Gli stessi nomi funzionano sul web e su React Native.

Filtra17 API

Numeri e testo

MotionNumber

Un numero le cui cifre scorrono come rotelle.

Prop	Tipo	Predefinito	Descrizione
`value`	`number \| bigint \| string`	`—`obbligatoria	Il numero, oppure un testo numerico formattato da te.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` sposta ogni cifra cambiata di un passo; `roll` passa per i numeri intermedi.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` segue la variazione di grandezza, così i riporti scorrono in un solo verso; `digit` confronta ogni cifra per conto suo.
`stagger`	`number`	`45`	Millisecondi tra le cifre cambiate, dalle unità verso l’esterno. L’intera onda ha una durata limitata.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Una funzione che restituisce il testo da mostrare, oppure le opzioni di `Intl.NumberFormat` (con `intl`).
`intl`	`boolean`	`false`	Usa l’`Intl.NumberFormat` integrato. Disattivato di default, così nessun runtime ha bisogno di `Intl`.
`locale`	`string \| string[]`		Locale per `intl`.
`prefix`	`string`		Testo prima del numero.
`suffix`	`string`		Testo dopo il numero.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.
`onMotionComplete`	`(value) => void`		Viene eseguito con il valore quando le cifre si sono assestate.

Pagina del componente e banco di prova

MotionText

Testo che si anima quando cambia: il testo numerico scorre cifra per cifra, il resto viene scambiato.

Prop	Tipo	Predefinito	Descrizione
`children`	`ReactNode`		Il testo da mostrare.
`as`	`element`	`'span'`	L’elemento da renderizzare.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.
`onMotionComplete`	`(text) => void`		Viene eseguito quando il movimento si assesta.

Pagina del componente e banco di prova

MotionStream

Testo in streaming rivelato a ritmo costante, che recupera le raffiche.

Prop	Tipo	Predefinito	Descrizione
`text`	`string`	`—`obbligatoria	Il testo ricevuto finora. Il testo che cresce viene rivelato a ritmo costante; una riscrittura prosegue dall’inizio comune.
`speed`	`number`	`90`	Velocità base di rivelazione, in caratteri al secondo.
`catchUp`	`number`	`900`	Un arretrato viene rivelato entro circa questi millisecondi accelerando.
`initial`	`boolean`	`false`	Rivela anche il testo presente al montaggio (altrimenti compare subito).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` fa comparire in dissolvenza i nuovi caratteri; `none` li mostra direttamente.
`children`	`(visible: string) => ReactNode`		Una funzione che riceve il testo cadenzato, per esempio per renderizzare Markdown.
`as`	`element`	`'span'`	L’elemento da renderizzare.
`onMotionComplete`	`(text) => void`		Viene eseguito ogni volta che la rivelazione raggiunge `text`.

Pagina del componente e banco di prova

Contenuto e dimensione

MotionSwap

Contenuto che passa in dissolvenza incrociata mentre l’elemento si ridimensiona.

Prop	Tipo	Predefinito	Descrizione
`value`	`unknown`		Identità del contenuto; un nuovo valore lo scambia. I figli di solo testo sono la loro stessa identità.
`children`	`ReactNode`		Il contenuto.
`as`	`element`	`'span'`	L’elemento da renderizzare.
`inline`	`boolean`	`as === 'span'`	`true` si adatta al contenuto (etichette, icone); `false` riempie la larghezza del genitore e anima l’altezza.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Dove si trova il contenuto mentre la dimensione cambia.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	Come entra ed esce il contenuto: `up` sale, `down` scende, `scale` cresce.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.
`onMotionComplete`	`(value) => void`		Viene eseguito quando il movimento si assesta.

Pagina del componente e banco di prova

MotionHeight

Anima l’altezza secondo il contenuto: chiusura, apertura e cambi di contenuto.

Prop	Tipo	Predefinito	Descrizione
`open`	`boolean`	`true`	`false` riduce l’altezza a zero; il contenuto resta montato ma nascosto e inerte.
`children`	`ReactNode`		Il contenuto.
`as`	`element`	`'div'`	L’elemento da renderizzare.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.
`onMotionComplete`	`(open) => void`		Viene eseguito con `open` quando l’altezza si è assestata.

Pagina del componente e banco di prova

MotionPresence

Mantiene montato il contenuto mentre entra ed esce con un’animazione.

Prop	Tipo	Predefinito	Descrizione
`present`	`boolean`	`—`obbligatoria	Mostra o nasconde il contenuto. Cambia questa invece di smontare.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	La pose a riposo.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	La pose con cui il contenuto esce e da cui entra.
`as`	`element`	`'div'`	L’elemento da renderizzare.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.
`onExitComplete`	`() => void`		Viene eseguito dopo che il contenuto è uscito ed è stato rimosso.

Pagina del componente e banco di prova

Selezione e pagine

MotionHighlight

Elementi a partire dai dati con un’unica evidenziazione che si sposta sull’elemento selezionato.

Prop	Tipo	Predefinito	Descrizione
`items`	`readonly T[]`	`—`obbligatoria	Il tuo array di dati.
`value`	`key \| null`	`—`obbligatoria	Key dell’elemento evidenziato; `null` nasconde l’evidenziazione.
`onValueChange`	`(key, item) => void`		Viene eseguito con la key e l’elemento quando un elemento viene premuto.
`getKey`	`(item) => string \| number`	`item.id`	Restituisce una key unica e stabile per un elemento. Di default è `item.id`, oppure l’elemento stesso per stringhe e numeri.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Disegna un elemento; riceve se è selezionato.
`hover`	`boolean`	`false`	Segue il puntatore sugli elementi e torna a `value` quando esce (web).
`itemAs`	`element`	`'button'`	L’elemento per ogni voce.
`itemClassName`	`string`		Classe per l’elemento di ogni voce; `itemStyle` imposta il suo stile inline.
`highlightClassName`	`string`		Classe per l’evidenziazione; `highlightStyle` imposta il suo stile inline.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

MotionPager

Pagine da scorrere con lo swipe a partire dai dati.

Prop	Tipo	Predefinito	Descrizione
`items`	`readonly T[]`	`—`obbligatoria	Il tuo array di dati.
`index`	`number`		La pagina mostrata. Se la ometti, il pager gestisce la propria.
`defaultIndex`	`number`	`0`	Pagina iniziale quando `index` non è controllato.
`onIndexChange`	`(index, item) => void`		Viene eseguito con l’indice e l’elemento appena uno swipe, un tasto o un gesto della rotellina si assesta.
`getKey`	`(item) => string \| number`	`item.id`	Restituisce una key unica e stabile per un elemento. Di default è `item.id`, oppure l’elemento stesso per stringhe e numeri.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Disegna una pagina; riceve il suo indice e se è attiva.
`gap`	`number`	`0`	Spazio tra le pagine, in pixel.
`itemClassName`	`string`		Classe per l’elemento di ogni voce; `itemStyle` imposta il suo stile inline.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

Liste

MotionList

Una lista con key a partire dai dati che anima solo ciò che è cambiato.

Prop	Tipo	Predefinito	Descrizione
`items`	`readonly T[]`	`—`obbligatoria	Il tuo array di dati.
`getKey`	`(item) => string \| number`	`item.id`	Restituisce una key unica e stabile per un elemento. Di default è `item.id`, oppure l’elemento stesso per stringhe e numeri.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Disegna un elemento.
`as`	`element`	`'div'`	L’elemento da renderizzare.
`itemAs`	`element`	`'li' \| 'div'`	L’elemento per ogni voce.
`itemClassName`	`string`		Classe per l’elemento di ogni voce; `itemStyle` imposta il suo stile inline.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	Come entrano ed escono gli elementi.
`distance`	`number`	`16`	Percorso di `rise` e `slide`, in pixel.
`stagger`	`number`	`40`	Millisecondi tra gli elementi che entrano.
`order`	`'forward' \| 'reverse'`	`'forward'`	Direzione dello sfalsamento.
`present`	`boolean`	`true`	`false` anima l’uscita di tutti gli elementi mantenendo il layout; `true` li fa tornare.
`initial`	`boolean`	`true`	Riproduce l’entrata quando la lista viene montata.
`playKey`	`string \| number`		Cambiarla riproduce di nuovo l’entrata.
`transition`	`Transition`	`spring`	Transizione per gli elementi che entrano ed escono.
`layoutTransition`	`Transition`	`spring`	Transizione per gli elementi che scivolano nelle nuove posizioni.

Pagina del componente e banco di prova

MotionReorder

Trascina per riordinare una lista o una griglia, con spostamenti da tastiera.

Prop	Tipo	Predefinito	Descrizione
`items`	`readonly T[]`		Gli elementi, quando controlli tu l’ordine.
`defaultItems`	`readonly T[]`	`[]`	Elementi iniziali, quando è il componente a gestire l’ordine.
`onItemsChange`	`(items, { reason, key }) => void`		Viene eseguito con il nuovo ordine e con l’origine della modifica: trascinamento, rilascio o tastiera.
`getKey`	`(item) => string \| number`	`item`	Restituisce una key unica per un elemento. Di default è l’elemento stesso.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Disegna un elemento; riceve il suo indice e se lo si sta trascinando.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` sposta gli altri elementi durante il trascinamento; `drop` aspetta il rilascio.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` o `grid`.
`columns`	`number`	`3`	Colonne di una griglia.
`gap`	`number`	`12`	Spazio tra gli elementi, in pixel.
`disabled`	`boolean`	`false`	Disattiva il trascinamento.
`duration`	`number`	`260`	Millisecondi per gli elementi che si spostano.
`itemClassName`	`string`		Classe per l’elemento di ogni voce; `itemStyle` imposta il suo stile inline.

Pagina del componente e banco di prova

Gesti

MotionSwipe

Una riga che rivela azioni con uno swipe orizzontale e si può scartare con lo swipe.

Prop	Tipo	Predefinito	Descrizione
`children`	`ReactNode`		Il contenuto della riga.
`startActions`	`ReactNode`		Rivelate all’inizio della riga quando la si trascina verso la fine.
`endActions`	`ReactNode`		Rivelate alla fine della riga quando la si trascina verso l’inizio.
`dismiss`	`'start' \| 'end' \| 'both'`		Lati in cui uno swipe lungo o un lancio rimuove la riga.
`onDismiss`	`(side) => void`		Viene eseguito dopo che la riga è scivolata via e si è chiusa; qui rimuovi l’elemento dai tuoi dati.
`onOpenChange`	`(side \| null) => void`		Viene eseguito con il lato aperto, oppure `null` quando la riga si chiude.
`disabled`	`boolean`	`false`	Disattiva lo swipe.
`contentClassName`	`string`		Classe per il contenuto della riga; `contentStyle` imposta il suo stile inline.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

MotionHold

Tieni premuto per confermare; un rilascio anticipato torna indietro.

Prop	Tipo	Predefinito	Descrizione
`children`	`ReactNode`		L’etichetta del pulsante.
`onConfirm`	`() => void`		Viene eseguito quando la pressione prolungata è completa.
`duration`	`number`	`1200`	Millisecondi per cui bisogna tenere premuto.
`disabled`	`boolean`	`false`	Disattiva il pulsante.
`fillClassName`	`string`		Classe per il riempimento che cresce; `fillStyle` imposta il suo stile inline.

Pagina del componente e banco di prova

Overlay

MotionSheet

Un bottom sheet, un top sheet o un cassetto laterale con detent.

Prop	Tipo	Predefinito	Descrizione
`open`	`boolean`	`false`	Se lo sheet è visibile.
`onOpenChange`	`(open) => void`		Viene eseguito con `false` quando lo sheet viene chiuso trascinandolo, toccando fuori o con Esc.
`detents`	`(number \| 'content')[]`	`['content']`	Dimensioni di riposo: una frazione dello schermo, pixel, oppure `'content'`.
`detent`	`number`		Indice del detent controllato.
`defaultDetent`	`number`	`0`	Indice del detent usato all’apertura senza `detent`.
`onDetentChange`	`(index) => void`		Viene eseguito con l’indice del detent su cui lo sheet si assesta.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	Il bordo da cui arriva lo sheet.
`modal`	`boolean`	`true`	Aggiunge uno sfondo, tiene il focus all’interno e rende inerte la pagina.
`dismissible`	`boolean`	`true`	Trascinare oltre il detent più piccolo, lo sfondo ed Esc lo chiudono.
`backdropClassName`	`string`		Classe per lo sfondo; `backdropStyle` imposta il suo stile inline.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

MotionZoom

Un’immagine che si ingrandisce da dove si trova fino a riempire lo schermo.

Prop	Tipo	Predefinito	Descrizione
`src`	`string`		L’immagine mostrata al suo posto.
`zoomSrc`	`string`		Un’immagine più grande mostrata appena è caricata; mantieni le stesse proporzioni.
`margin`	`number`	`24`	Spazio lasciato attorno all’immagine ingrandita, in pixel.
`disabled`	`boolean`	`false`	Disattiva lo zoom.
`onZoomChange`	`(zoomed) => void`		Viene eseguito con `true` quando è ingrandita e con `false` quando si chiude.
`backdropStyle`	`CSSProperties`		Stile inline per lo sfondo.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

Avanzamento

ProgressBar

Una linea di avanzamento controllata, con uno stato indeterminato.

Prop	Tipo	Predefinito	Descrizione
`value`	`number \| null`		Avanzamento da `0` a `max`; `null` è indeterminato.
`max`	`number`	`100`	Il valore che significa completato.
`color`	`string`	`'currentColor'`	Colore del riempimento.
`trackColor`	`string`	`'#e7ece9'`	Colore della traccia.
`thickness`	`number`	`8`	Spessore della linea, in pixel.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Riempimento da sinistra (`ltr`) o da destra (`rtl`).
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

ProgressRing

Un anello di avanzamento controllato, con uno stato indeterminato.

Prop	Tipo	Predefinito	Descrizione
`value`	`number \| null`		Avanzamento da `0` a `max`; `null` è indeterminato.
`max`	`number`	`100`	Il valore che significa completato.
`size`	`number`	`96`	Diametro in pixel.
`thickness`	`number`	`8`	Spessore dell’anello, in pixel.
`color`	`string`	`'currentColor'`	Colore dell’arco.
`trackColor`	`string`	`'#e7ece9'`	Colore della traccia.
`children`	`ReactNode`		Un’etichetta mostrata al centro.
`transition`	`Transition`	`spring`	Una curva di timing `{ duration, easing }` o una molla `{ tempo: 'spring', spring }`. Le molle conservano lo slancio quando vengono interrotte.

Pagina del componente e banco di prova

Transizioni

motionTokens

Valori pronti per qualsiasi prop transition.

Prop	Tipo	Predefinito	Descrizione
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Durate in millisecondi.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Transizioni di timing con una durata e una curva con nome.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Transizioni a molla, da rapide e decise a morbide ed elastiche.

Transizioni

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