MotionPager

Wischbare Seiten aus Daten: Onboarding, Karussells und Tab-Panels.

WebReact NativeAuswahl und Blättern

Ausprobieren

Beispiel wird vorbereitet…

JavaScript ist aus. Der Code unten ist das vollständige Beispiel.

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

Kürzeste Nutzung

Onboarding.jsx

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

Was sie dir abnimmt

Seiten folgen Wischgesten und Mausziehen, bieten an den Enden Widerstand und kommen mit deinem Loslass-Tempo zur Ruhe.
Ein Flick blättert immer eine Seite um, und eine Geste blättert nie mehr als eine.
Horizontales Scrollen mit dem Trackpad blättert ebenfalls, und sein Schwung-Nachlauf wird ignoriert.
Pfeiltasten, Pos1 und Ende funktionieren, wenn der Pager fokussiert ist, und vertikales Scrollen funktioniert weiter.
Seiten außer der aktiven sind inaktiv.

Gut für

Ein Onboarding-Ablauf.
Ein Foto-Karussell.
Wischbare Tab-Panels zusammen mit MotionHighlight.

props

Prop	Typ	Standard	Beschreibung
`items`	`readonly T[]`	`—`erforderlich	Dein Daten-Array.
`index`	`number`		Die angezeigte Seite. Weglassen, damit der Pager seine eigene verwaltet.
`defaultIndex`	`number`	`0`	Startseite, wenn `index` nicht kontrolliert wird.
`onIndexChange`	`(index, item) => void`		Läuft mit Index und Element, sobald eine Wisch-, Tasten- oder Mausradgeste einrastet.
`getKey`	`(item) => string \| number`	`item.id`	Gibt einen eindeutigen, stabilen Key für ein Element zurück. Standard ist `item.id` oder bei Strings und Zahlen das Element selbst.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Zeichnet eine Seite; erhält ihren Index und ob sie aktiv ist.
`gap`	`number`	`0`	Abstand zwischen Seiten in Pixeln.
`itemClassName`	`string`		Klasse für jedes Eintragselement; `itemStyle` setzt seinen Inline-Style.
`transition`	`Transition`	`spring`	Eine Timing-Kurve `{ duration, easing }` oder eine Feder `{ tempo: 'spring', spring }`. Federn behalten bei Unterbrechung ihren Schwung.

Weitere props gehen an das gerenderte Element, also funktionieren className, style und Event-Handler wie gewohnt.

Web und React Native

index kann kontrolliert werden (onIndexChange(index, item) meldet jedes Einrasten) oder mit defaultIndex dem Pager überlassen werden.

Dieselbe Komponente und dieselben props funktionieren unter React Native.

Verwendet in diesen Beispielen

Foto-FeedDurch Fotos wischen, mit Vorschaubildern springen, jedes Foto im Vollbild öffnen und seine Details hochziehen.MotionPagerMotionHighlightMotionZoomMotionSheet