MotionPager

Páginas deslizáveis a partir de dados: onboarding, carrosséis e painéis de abas.

WebReact NativeSeleção e paginação

Experimente

Preparando o exemplo…

O JavaScript está desativado. O código abaixo é o exemplo 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 mais curto

Onboarding.jsx

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

O que ele resolve para você

As páginas seguem os deslizes e o arraste com o mouse, oferecem resistência nas pontas e se acomodam com a velocidade com que você solta.
Um gesto rápido sempre vira uma página, e um gesto nunca vira mais de uma.
A rolagem horizontal do trackpad também vira páginas, e a inércia final é ignorada.
Setas, Home e End funcionam quando o paginador tem foco, e a rolagem vertical continua funcionando.
As páginas que não estão ativas ficam inertes.

Use para

Um fluxo de onboarding.
Um carrossel de fotos.
Painéis de abas deslizáveis junto com MotionHighlight.

Props

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.

As outras props vão para o elemento renderizado, então className, style e handlers de eventos funcionam normalmente.

Web e React Native

index pode ser controlado (onIndexChange(index, item) informa cada parada) ou ficar com o paginador via defaultIndex.

O mesmo componente e as mesmas props funcionam no React Native.

Usado nestes exemplos

Feed de fotosDeslize pelas fotos, pule com as miniaturas, abra qualquer foto em tela cheia e puxe os detalhes para cima.MotionPagerMotionHighlightMotionZoomMotionSheet