Référence de l’API

Chaque export de @kkwaenggwari/animated-chorus avec ses props, ses types et ses valeurs par défaut. Les mêmes noms fonctionnent sur le web et React Native.

Filtrer17 API

Nombres et texte

MotionNumber

Un nombre dont les chiffres tournent comme des roues.

Prop	Type	Défaut	Description
`value`	`number \| bigint \| string`	`—`obligatoire	Le nombre, ou un texte numérique déjà formaté par l’appelant.
`mode`	`'replace' \| 'roll'`	`'replace'`	`replace` avance chaque chiffre modifié d’un cran ; `roll` passe par les chiffres intermédiaires.
`direction`	`'auto' \| 'digit' \| 'up' \| 'down'`	`'auto'`	`auto` suit la variation d’ordre de grandeur pour que les retenues tournent dans un sens ; `digit` compare chaque chiffre isolément.
`stagger`	`number`	`45`	Millisecondes entre les chiffres modifiés, des unités vers l’extérieur. L’ondulation totale est bornée.
`format`	`(value) => string \| Intl.NumberFormatOptions`		Une fonction qui renvoie le texte à afficher, ou des options `Intl.NumberFormat` (avec `intl`).
`intl`	`boolean`	`false`	Utilise l’`Intl.NumberFormat` intégré. Désactivé par défaut pour qu’aucun environnement n’ait besoin d’`Intl`.
`locale`	`string \| string[]`		Paramètre régional pour `intl`.
`prefix`	`string`		Texte avant le nombre.
`suffix`	`string`		Texte après le nombre.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.
`onMotionComplete`	`(value) => void`		S’exécute avec la valeur une fois les chiffres posés.

Page du composant et banc d’essai

MotionText

Un texte qui s’anime quand il change : le texte numérique défile chiffre par chiffre, le reste s’échange.

Prop	Type	Défaut	Description
`children`	`ReactNode`		Le texte à afficher.
`as`	`element`	`'span'`	L’élément à rendre.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.
`onMotionComplete`	`(text) => void`		S’exécute quand le mouvement se pose.

Page du composant et banc d’essai

MotionStream

Du texte en streaming révélé à un rythme régulier, qui rattrape son retard en cas de rafale.

Prop	Type	Défaut	Description
`text`	`string`	`—`obligatoire	Le texte reçu jusqu’ici. Un texte qui s’allonge est révélé à un rythme régulier ; une réécriture repart du début commun.
`speed`	`number`	`90`	Rythme de base de la révélation, en caractères par seconde.
`catchUp`	`number`	`900`	Un retard accumulé est révélé en environ autant de millisecondes, en accélérant.
`initial`	`boolean`	`false`	Révéler aussi le texte présent au montage (sinon il s’affiche aussitôt).
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` fait apparaître les nouveaux caractères en fondu ; `none` les affiche directement.
`children`	`(visible: string) => ReactNode`		Une fonction qui reçoit le texte rythmé, par exemple pour rendre du Markdown.
`as`	`element`	`'span'`	L’élément à rendre.
`onMotionComplete`	`(text) => void`		S’exécute chaque fois que la révélation rattrape `text`.

Page du composant et banc d’essai

Contenu et taille

MotionSwap

Un contenu en fondu enchaîné pendant que l’élément se redimensionne.

Prop	Type	Défaut	Description
`value`	`unknown`		Identité du contenu ; une nouvelle valeur déclenche le changement. Les enfants en texte brut sont leur propre identité.
`children`	`ReactNode`		Le contenu.
`as`	`element`	`'span'`	L’élément à rendre.
`inline`	`boolean`	`as === 'span'`	`true` dimensionne selon le contenu (libellés, icônes) ; `false` prend la largeur du parent et anime la hauteur.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Où se place le contenu pendant le changement de taille.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	Comment le contenu entre et sort : `up` monte, `down` descend, `scale` grandit.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.
`onMotionComplete`	`(value) => void`		S’exécute quand le mouvement se pose.

Page du composant et banc d’essai

MotionHeight

Anime la hauteur selon son contenu : repli, dépli et changements de contenu.

Prop	Type	Défaut	Description
`open`	`boolean`	`true`	`false` replie à une hauteur nulle ; le contenu reste monté mais masqué et inerte.
`children`	`ReactNode`		Le contenu.
`as`	`element`	`'div'`	L’élément à rendre.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.
`onMotionComplete`	`(open) => void`		S’exécute avec `open` une fois la hauteur posée.

Page du composant et banc d’essai

MotionPresence

Garde le contenu monté pendant ses animations d’entrée et de sortie.

Prop	Type	Défaut	Description
`present`	`boolean`	`—`obligatoire	Afficher ou masquer le contenu. Modifiez ceci au lieu de démonter.
`enter`	`Pose`	`{ opacity: 1, translateY: 0 }`	La pose au repos.
`exit`	`Pose`	`{ opacity: 0, translateY: -12 }`	La pose avec laquelle le contenu sort et depuis laquelle il entre.
`as`	`element`	`'div'`	L’élément à rendre.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.
`onExitComplete`	`() => void`		S’exécute une fois le contenu sorti et retiré.

Page du composant et banc d’essai

Sélection et pagination

MotionHighlight

Des éléments à partir de données, avec un surlignage unique qui se déplace vers l’élément sélectionné.

Prop	Type	Défaut	Description
`items`	`readonly T[]`	`—`obligatoire	Votre tableau de données.
`value`	`key \| null`	`—`obligatoire	Key de l’élément surligné ; `null` masque le surlignage.
`onValueChange`	`(key, item) => void`		S’exécute avec la key et l’élément quand un élément est pressé.
`getKey`	`(item) => string \| number`	`item.id`	Renvoie une key unique et stable pour un élément. Par défaut `item.id`, ou l’élément lui-même pour les chaînes et les nombres.
`renderItem`	`(item, { selected, index }) => ReactNode`	`item.label`	Dessine un élément ; reçoit s’il est sélectionné.
`hover`	`boolean`	`false`	Suit le pointeur sur les éléments et revient à `value` à la sortie (web).
`itemAs`	`element`	`'button'`	L’élément de chaque item.
`itemClassName`	`string`		Classe de l’élément de chaque item ; `itemStyle` définit son style en ligne.
`highlightClassName`	`string`		Classe du surlignage ; `highlightStyle` définit son style en ligne.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

MotionPager

Des pages à balayer à partir de données.

Prop	Type	Défaut	Description
`items`	`readonly T[]`	`—`obligatoire	Votre tableau de données.
`index`	`number`		La page affichée. Omettez-la pour laisser le pagineur gérer la sienne.
`defaultIndex`	`number`	`0`	Page de départ quand `index` n’est pas contrôlé.
`onIndexChange`	`(index, item) => void`		S’exécute avec l’index et l’élément dès qu’un balayage, une touche ou la molette se pose.
`getKey`	`(item) => string \| number`	`item.id`	Renvoie une key unique et stable pour un élément. Par défaut `item.id`, ou l’élément lui-même pour les chaînes et les nombres.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Dessine une page ; reçoit son index et si elle est active.
`gap`	`number`	`0`	Espace entre les pages, en pixels.
`itemClassName`	`string`		Classe de l’élément de chaque item ; `itemStyle` définit son style en ligne.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

Listes

MotionList

Une liste à keys, à partir de données, qui n’anime que ce qui a changé.

Prop	Type	Défaut	Description
`items`	`readonly T[]`	`—`obligatoire	Votre tableau de données.
`getKey`	`(item) => string \| number`	`item.id`	Renvoie une key unique et stable pour un élément. Par défaut `item.id`, ou l’élément lui-même pour les chaînes et les nombres.
`renderItem`	`(item, index) => ReactNode`	`item.label`	Dessine un élément.
`as`	`element`	`'div'`	L’élément à rendre.
`itemAs`	`element`	`'li' \| 'div'`	L’élément de chaque item.
`itemClassName`	`string`		Classe de l’élément de chaque item ; `itemStyle` définit son style en ligne.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	Comment les éléments entrent et sortent.
`distance`	`number`	`16`	Déplacement de `rise` et `slide`, en pixels.
`stagger`	`number`	`40`	Millisecondes entre les éléments entrants.
`order`	`'forward' \| 'reverse'`	`'forward'`	Sens du décalage.
`present`	`boolean`	`true`	`false` fait sortir tous les éléments en gardant la mise en page ; `true` les fait revenir.
`initial`	`boolean`	`true`	Jouer l’entrée au montage de la liste.
`playKey`	`string \| number`		Le modifier rejoue l’entrée.
`transition`	`Transition`	`spring`	Transition des éléments entrants et sortants.
`layoutTransition`	`Transition`	`spring`	Transition des éléments qui glissent vers une nouvelle position.

Page du composant et banc d’essai

MotionReorder

Faites glisser pour réordonner une liste ou une grille, avec déplacements au clavier.

Prop	Type	Défaut	Description
`items`	`readonly T[]`		Les éléments, quand vous contrôlez l’ordre.
`defaultItems`	`readonly T[]`	`[]`	Éléments de départ, quand le composant conserve l’ordre.
`onItemsChange`	`(items, { reason, key }) => void`		S’exécute avec le nouvel ordre et indique s’il vient d’un glisser, d’un dépôt ou du clavier.
`getKey`	`(item) => string \| number`	`item`	Renvoie une key unique pour un élément. Par défaut, l’élément lui-même.
`renderItem`	`(item, { index, dragging }) => ReactNode`	`item.label`	Dessine un élément ; reçoit son index et s’il est en cours de glisser.
`reorder`	`'live' \| 'drop'`	`'live'`	`live` déplace les autres éléments pendant le glisser ; `drop` attend le dépôt.
`layout`	`'list' \| 'grid'`	`'grid'`	`list` ou `grid`.
`columns`	`number`	`3`	Colonnes d’une grille.
`gap`	`number`	`12`	Espace entre les éléments, en pixels.
`disabled`	`boolean`	`false`	Désactive le glisser.
`duration`	`number`	`260`	Millisecondes pour les éléments qui s’écartent.
`itemClassName`	`string`		Classe de l’élément de chaque item ; `itemStyle` définit son style en ligne.

Page du composant et banc d’essai

Gestes

MotionSwipe

Une ligne qui révèle des actions par balayage horizontal et peut être écartée d’un balayage.

Prop	Type	Défaut	Description
`children`	`ReactNode`		Le contenu de la ligne.
`startActions`	`ReactNode`		Révélées au début de la ligne quand on la fait glisser vers la fin.
`endActions`	`ReactNode`		Révélées à la fin de la ligne quand on la fait glisser vers le début.
`dismiss`	`'start' \| 'end' \| 'both'`		Côtés où un long balayage ou un lancer supprime la ligne.
`onDismiss`	`(side) => void`		S’exécute une fois la ligne sortie et repliée ; retirez ici l’élément de vos données.
`onOpenChange`	`(side \| null) => void`		S’exécute avec le côté ouvert, ou `null` quand la ligne se ferme.
`disabled`	`boolean`	`false`	Désactive le balayage.
`contentClassName`	`string`		Classe du contenu de la ligne ; `contentStyle` définit son style en ligne.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

MotionHold

Maintenez appuyé pour confirmer ; relâcher trop tôt fait revenir en arrière.

Prop	Type	Défaut	Description
`children`	`ReactNode`		Le libellé du bouton.
`onConfirm`	`() => void`		S’exécute une fois l’appui maintenu terminé.
`duration`	`number`	`1200`	Millisecondes pendant lesquelles l’appui doit être maintenu.
`disabled`	`boolean`	`false`	Désactive le bouton.
`fillClassName`	`string`		Classe du remplissage qui progresse ; `fillStyle` définit son style en ligne.

Page du composant et banc d’essai

Superpositions

MotionSheet

Un panneau inférieur, un panneau supérieur ou un tiroir latéral à crans.

Prop	Type	Défaut	Description
`open`	`boolean`	`false`	Indique si le panneau est affiché.
`onOpenChange`	`(open) => void`		S’exécute avec `false` quand le panneau est fermé par un glisser, un appui ou Échap.
`detents`	`(number \| 'content')[]`	`['content']`	Tailles de repos : une fraction de l’écran, des pixels ou `'content'`.
`detent`	`number`		Index de cran contrôlé.
`defaultDetent`	`number`	`0`	Index de cran utilisé à l’ouverture sans `detent`.
`onDetentChange`	`(index) => void`		S’exécute avec l’index du cran où le panneau se pose.
`side`	`'bottom' \| 'top' \| 'start' \| 'end'`	`'bottom'`	Le bord d’où vient le panneau.
`modal`	`boolean`	`true`	Ajoute un fond, garde le focus à l’intérieur et rend la page inerte.
`dismissible`	`boolean`	`true`	Un glisser au-delà du plus petit cran, le fond et Échap le ferment.
`backdropClassName`	`string`		Classe du fond ; `backdropStyle` définit son style en ligne.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

MotionZoom

Une image qui s’agrandit depuis sa place jusqu’à remplir l’écran.

Prop	Type	Défaut	Description
`src`	`string`		L’image affichée en place.
`zoomSrc`	`string`		Une image plus grande affichée une fois chargée ; gardez le même rapport d’aspect.
`margin`	`number`	`24`	Espace conservé autour de l’image agrandie, en pixels.
`disabled`	`boolean`	`false`	Désactive le zoom.
`onZoomChange`	`(zoomed) => void`		S’exécute avec `true` à l’agrandissement et `false` à la fermeture.
`backdropStyle`	`CSSProperties`		Style en ligne du fond.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

Progression

ProgressBar

Une ligne de progression contrôlée, avec un état indéterminé.

Prop	Type	Défaut	Description
`value`	`number \| null`		Progression de `0` à `max` ; `null` est indéterminé.
`max`	`number`	`100`	La valeur qui signifie terminé.
`color`	`string`	`'currentColor'`	Couleur du remplissage.
`trackColor`	`string`	`'#e7ece9'`	Couleur de la piste.
`thickness`	`number`	`8`	Épaisseur de la ligne, en pixels.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Remplir depuis la gauche (`ltr`) ou depuis la droite (`rtl`).
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

ProgressRing

Un anneau de progression contrôlé, avec un état indéterminé.

Prop	Type	Défaut	Description
`value`	`number \| null`		Progression de `0` à `max` ; `null` est indéterminé.
`max`	`number`	`100`	La valeur qui signifie terminé.
`size`	`number`	`96`	Diamètre, en pixels.
`thickness`	`number`	`8`	Épaisseur de l’anneau, en pixels.
`color`	`string`	`'currentColor'`	Couleur de l’arc.
`trackColor`	`string`	`'#e7ece9'`	Couleur de la piste.
`children`	`ReactNode`		Une étiquette affichée au centre.
`transition`	`Transition`	`spring`	Une courbe de temps `{ duration, easing }` ou un ressort `{ tempo: 'spring', spring }`. Les ressorts gardent leur élan quand ils sont interrompus.

Page du composant et banc d’essai

Transitions

motionTokens

Des valeurs prêtes à l’emploi pour toute prop transition.

Prop	Type	Défaut	Description
`duration`	`{ instant, fast, normal, slow }`	`0 · 140 · 280 · 520`	Durées en millisecondes.
`easing`	`{ ease, easeOut, expoOut, backOut }`	`Transition`	Transitions temporelles avec une durée et une courbe nommée.
`spring`	`{ quick, basic, gentle, bouncy }`	`Transition`	Transitions à ressort, des plus vives et fermes aux plus douces et rebondissantes.

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