MotionPager

Des pages à balayer à partir de données : onboarding, carrousels et panneaux d’onglets.

WebReact NativeSélection et pagination

Essayer

Préparation de l’exemple…

JavaScript est désactivé. Le code ci-dessous est l’exemple complet.

App.jsx

import { useState } from 'react';
import { MotionHighlight, MotionPager, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const slides = [
  { id: 'welcome', title: 'Welcome', text: 'Swipe, drag or use the arrow keys.', tone: 'deep' },
  { id: 'data', title: 'Your data', text: 'Pages come from an array.', tone: 'forest' },
  { id: 'flick', title: 'Flick', text: 'A quick flick always turns one page.', tone: 'mint' },
  { id: 'done', title: 'Done', text: 'The index is yours to control.', tone: 'light' },
];

export default function App({ gap = 16, spring = 'default' }) {
  const [page, setPage] = useState(0);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];

  return (
    <div className="stage">
      <MotionPager
        className="pager"
        items={slides}
        index={page}
        onIndexChange={setPage}
        gap={gap}
        transition={transition}
        renderItem={(slide) => (
          <article className={`slide ${slide.tone}`}>
            <h2>{slide.title}</h2>
            <p>{slide.text}</p>
          </article>
        )}
      />
      <div className="controls">
        <button onClick={() => setPage(Math.max(0, page - 1))} disabled={page === 0}>
          Back
        </button>
        <MotionHighlight
          className="dots"
          itemClassName="dot"
          highlightClassName="dot-active"
          items={slides}
          value={slides[page].id}
          transition={transition}
          onValueChange={(key) => setPage(slides.findIndex((slide) => slide.id === key))}
          renderItem={(slide, { index }) => <span className="dot-number">{index + 1}</span>}
        />
        <button
          onClick={() => setPage(Math.min(slides.length - 1, page + 1))}
          disabled={page === slides.length - 1}
        >
          Next
        </button>
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  gap: 16px;
  max-width: 560px;
  margin: 0 auto;
  padding: 24px 20px;
}

.pager {
  border-radius: 20px;
}

.slide {
  display: grid;
  align-content: end;
  gap: 6px;
  height: 240px;
  padding: 24px;
  border-radius: 20px;
  user-select: none;
}

.slide h2 {
  margin: 0;
  font:
    800 30px/1.1 system-ui,
    sans-serif;
}

.slide p {
  margin: 0;
}

.deep {
  background: #0e2e24;
  color: #fff;
}

.forest {
  background: #176b52;
  color: #fff;
}

.mint {
  background: #43c58f;
  color: #0e2e24;
}

.light {
  background: #eaf6f0;
  color: #0e2e24;
}

.controls {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
}

.controls > button {
  flex: none;
  min-height: 44px;
  padding: 0 18px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 15px system-ui,
    sans-serif;
  cursor: pointer;
}

.controls > button:disabled {
  opacity: 0.4;
}

.dots {
  display: flex;
  min-width: 0;
  gap: 4px;
}

/* On a narrow phone the page dots shrink (never below 28px); Back and Next keep their size. */
.dot {
  flex: 0 1 36px;
  min-width: 28px;
  aspect-ratio: 1;
  border: 0;
  border-radius: 50%;
  background: none;
  cursor: pointer;
}

.dot-number {
  font:
    600 13px system-ui,
    sans-serif;
  color: #5b616b;
}

.dot-active {
  border-radius: 50%;
  background: #eaf6f0;
  box-shadow: inset 0 0 0 2px #176b52;
}

@media (max-width: 340px) {
  .controls {
    gap: 8px;
  }

  .controls > button {
    padding: 0 14px;
  }
}

Usage minimal

Onboarding.jsx

<MotionPager
  items={slides}
  index={page}
  onIndexChange={setPage}
  gap={16}
  renderItem={(slide) => <Slide slide={slide} />}
/>;

Ce qu’il gère pour vous

Les pages suivent les balayages et les glisser à la souris, résistent aux extrémités et se posent selon la vitesse de relâchement.
Un geste vif tourne toujours une page, et un geste ne tourne jamais plus d’une page.
Le défilement horizontal du trackpad tourne aussi les pages, et sa traîne d’inertie est ignorée.
Les flèches, Début et Fin fonctionnent quand le pagineur a le focus, et le défilement vertical continue de fonctionner.
Les pages autres que la page active sont inertes.

À utiliser pour

Un parcours d’onboarding.
Un carrousel de photos.
Des panneaux d’onglets à balayer associés à MotionHighlight.

Props

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.

Les autres props vont à l’élément rendu : className, style et les gestionnaires d’événements fonctionnent comme d’habitude.

Web et React Native

index peut être contrôlé (onIndexChange(index, item) signale chaque arrêt) ou laissé au pagineur avec defaultIndex.

Le même composant et les mêmes props fonctionnent sur React Native.

Utilisé dans ces exemples

Fil de photosFaites défiler les photos, sautez de l’une à l’autre avec les vignettes, ouvrez n’importe quelle photo en plein écran et remontez ses détails.MotionPagerMotionHighlightMotionZoomMotionSheet