MotionPager

Páginas deslizables a partir de datos: onboarding, carruseles y paneles de pestañas.

WebReact NativeSelección y paginación

Pruébalo

Preparando el ejemplo…

JavaScript está desactivado. El código de abajo es el ejemplo completo.

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

Uso mínimo

Onboarding.jsx

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

Lo que resuelve por ti

Las páginas siguen los deslizamientos y los arrastres con el ratón, ofrecen resistencia en los extremos y se asientan con la velocidad con la que sueltas.
Un gesto rápido siempre pasa una página, y un solo gesto nunca pasa más de una.
El scroll horizontal del trackpad también pasa páginas, y se ignora su inercia final.
Las flechas, Inicio y Fin funcionan cuando el paginador tiene el foco, y el scroll vertical sigue funcionando.
Las páginas que no están activas son inertes.

Úsalo para

Un flujo de onboarding.
Un carrusel de fotos.
Paneles de pestañas deslizables junto con MotionHighlight.

Props

Prop	Tipo	Por defecto	Descripción
`items`	`readonly T[]`	`—`obligatoria	Tu array de datos.
`index`	`number`		La página que se muestra. Omítela para que el paginador la gestione.
`defaultIndex`	`number`	`0`	Página inicial cuando `index` no está controlado.
`onIndexChange`	`(index, item) => void`		Se ejecuta con el índice y el elemento en cuanto un deslizamiento, una tecla o la rueda se asientan.
`getKey`	`(item) => string \| number`	`item.id`	Devuelve una key única y estable para un elemento. Por defecto `item.id`, o el propio elemento si es una cadena o un número.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Dibuja una página; recibe su índice y si está activa.
`gap`	`number`	`0`	Espacio entre páginas en píxeles.
`itemClassName`	`string`		Clase para el elemento de cada ítem; `itemStyle` fija su estilo en línea.
`transition`	`Transition`	`spring`	Una curva de tiempo `{ duration, easing }` o un resorte `{ tempo: 'spring', spring }`. Los resortes conservan su impulso cuando se interrumpen.

Las demás props van al elemento renderizado, así que className, style y los manejadores de eventos funcionan como siempre.

Web y React Native

index puede controlarse (onIndexChange(index, item) informa de cada asentamiento) o dejarse al paginador con defaultIndex.

El mismo componente y las mismas props funcionan en React Native.

Se usa en estos ejemplos

Feed de fotosPasa fotos deslizando, salta con las miniaturas, abre cualquier foto a pantalla completa y sube sus detalles.MotionPagerMotionHighlightMotionZoomMotionSheet