Pager

Swipeable, scroll-snap pager with typed page ids and a segmented tab bar (APG tabs).

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { Pager, PagerTabList, PagerTab, PagerViewport, PagerPage } from "@vizejs/ui/pager";

Or copy the source into your project with vize lib pull pager (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Controlled swipeable pager whose segmented tabs and scroll-snap pages stay in sync. -->
<script setup lang="ts">
import { ref } from "vue";

import { Pager, PagerPage, PagerTab, PagerTabList, PagerViewport } from "@vizejs/ui/pager";

type Library = "photos" | "albums" | "shared";

const pages: readonly Library[] = ["photos", "albums", "shared"];
const labels: Record<Library, string> = { photos: "Photos", albums: "Albums", shared: "Shared" };
const active = ref<Library>("photos");
// Swiping needs a horizontal scroll-snap viewport with one full-width page per snap point.
const viewportLayout = { display: "flex", overflowX: "auto", scrollSnapType: "x mandatory" };
const pageLayout = { flex: "0 0 100%", scrollSnapAlign: "start" };
</script>

<template>
  <Pager v-model="active" :pages>
    <PagerTabList aria-label="Library">
      <PagerTab v-for="page in pages" :key="page" :page>{{ labels[page] }}</PagerTab>
    </PagerTabList>
    <PagerViewport :style="viewportLayout">
      <PagerPage v-for="page in pages" :key="page" :page :style="pageLayout">
        <p>{{ labels[page] }} in your library.</p>
      </PagerPage>
    </PagerViewport>
  </Pager>
</template>

API

Pager<PageId extends string>

Source: src/families/navigation/pager/pager.vue

Props

Events

Slots

Exposed

PagerTabList

Source: src/families/navigation/pager/pager-tab-list.vue

Props

Slots

PagerTab

Source: src/families/navigation/pager/pager-tab.vue

Props

Slots

PagerViewport

Source: src/families/navigation/pager/pager-viewport.vue

Props

Slots

PagerPage

Source: src/families/navigation/pager/pager-page.vue

Props

Slots

Behavior

Normative state x input -> outcome table for pager.vue, pager-tab-list.vue, pager-tab.vue, pager-viewport.vue, and pager-page.vue (@vizejs/ui/pager): a swipeable, scroll-snap page view whose segmented tab bar follows the WAI-ARIA APG tabs pattern with automatic activation. pages infers the page-id union. Minimal consumer CSS: the viewport is display: flex; overflow-x: auto; scroll-snap-type: x mandatory and pages are flex: 0 0 100%; scroll-snap-align: start. Every row is proven by the named test in pager.test.ts or pager-ssr.test.ts.

The subpath ships no CSS.