# Page Indicator

Show which page of a carousel or a short sequence is current, as dots or line segments, and go to another page.

Dots for three slides

[Complete TSX file](/examples/page-indicator/default.tsx)

```tsx
"use client";

import { useState } from "react";

import { PageIndicator } from "@/siteplane/components/page-indicator";

const slides = ["Invite your team", "Connect your data", "Share a report"];

export default function Example() {
  const [page, setPage] = useState(1);
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-4">
      <p className="text-sm font-medium">{slides[page - 1]}</p>
      <PageIndicator count={slides.length} onPageChange={setPage} page={page} />
    </div>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/page-indicator
```

With npm: `npx shadcn@4.18.0 add @siteplane/page-indicator`. [Registry JSON](/registry/page-indicator.json) lists source files and dependencies.

## Usage

```tsx
import { useState } from "react";

import { PageIndicator } from "@/siteplane/components/page-indicator";

export function Slides() {
  const [page, setPage] = useState(1);
  return <PageIndicator count={3} onPageChange={setPage} page={page} />;
}
```

## Pages

`count` sets the number of pages, one mark each, and `page` the current one, counted from 1. A click on another mark calls `onPageChange` with its page. Keep the page in state and change the slide or the content there; PageIndicator moves no content by itself.

## Dots and lines

`variant="dot"`, the default, draws a row of dots that is as wide as its dots. `variant="line"` draws a line of segments that takes the width of its container and shares it between the pages, so put the line in a container of the width you want, such as the width of the slides.

A line of three segments

[Complete TSX file](/examples/page-indicator/line.tsx)

```tsx
"use client";

import { useState } from "react";

import { PageIndicator } from "@/siteplane/components/page-indicator";

export default function Example() {
  const [page, setPage] = useState(1);
  return (
    <div className="w-40">
      <PageIndicator
        count={3}
        onPageChange={setPage}
        page={page}
        variant="line"
      />
    </div>
  );
}
```

## Sizes

`size="md"`, the default, draws 8 px dots 12 px apart, or 6 px segments 8 px apart. `size="lg"` draws 10 px dots 16 px apart, or 8 px segments 12 px apart. A mark responds to clicks a little beyond its edge: up to 8 px above and below it at md and 12 px at lg, and halfway to its neighbor on each side. On a touch screen it responds up to 44 px high.

Dots and lines at md and lg

[Complete TSX file](/examples/page-indicator/sizes.tsx)

```tsx
"use client";

import { useState } from "react";

import { PageIndicator } from "@/siteplane/components/page-indicator";

export default function Example() {
  const [page, setPage] = useState(1);
  return (
    <div className="grid grid-cols-2 items-center gap-x-12 gap-y-8">
      <PageIndicator count={3} onPageChange={setPage} page={page} size="md" />
      <PageIndicator count={3} onPageChange={setPage} page={page} size="lg" />
      <div className="w-40">
        <PageIndicator
          count={3}
          onPageChange={setPage}
          page={page}
          size="md"
          variant="line"
        />
      </div>
      <div className="w-40">
        <PageIndicator
          count={3}
          onPageChange={setPage}
          page={page}
          size="lg"
          variant="line"
        />
      </div>
    </div>
  );
}
```

## Framed

`framed` sets the marks on a translucent pill with a blur behind it, so they stay readable on an image.

A framed indicator on a slide

[Complete TSX file](/examples/page-indicator/framed.tsx)

```tsx
"use client";

import { useState } from "react";

import { PageIndicator } from "@/siteplane/components/page-indicator";

export default function Example() {
  const [page, setPage] = useState(1);
  return (
    <div className="flex aspect-video w-full max-w-md items-end justify-center rounded-xl bg-muted p-4">
      <PageIndicator count={4} framed onPageChange={setPage} page={page} />
    </div>
  );
}
```

## Accessibility

PageIndicator is a group named “Pages”, and each mark is a button named “Page 1”, “Page 2” and so on. The current page carries `aria-current="page"`. Tab moves through the pages, and Enter or Space goes to one; keyboard focus draws an outline around the mark. Name the group after its content with `aria-label`, such as “Customer stories”, and pass the names in another language with `labels`.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| PageIndicator.count | number | required | The number of pages, one mark each. |
| PageIndicator.page | number | required | The current page, counted from 1. A page outside 1 to count marks none. |
| PageIndicator.onPageChange | (page: number) => void | unset | Called with the page a person picks. A click on the current page calls nothing. |
| PageIndicator.variant | "dot" \| "line" | "dot" | dot draws a row of dots, line a line of segments that shares the width of its container. |
| PageIndicator.size | "md" \| "lg" | "md" | md draws 8 px dots 12 px apart or 6 px segments 8 px apart, lg 10 px dots 16 px apart or 8 px segments 12 px apart. |
| PageIndicator.framed | boolean | false | Sets the marks on a translucent pill, for an indicator on an image. |
| PageIndicator.labels | Partial<PageIndicatorLabels> | English | Replaces the names, each one on its own: group ("Pages") and page, a function of the page number ("Page 1"). Pass their translation when the application is in another language. |
| PageIndicator.aria-label | string | labels.group | The name of the group, in place of labels.group. |
`PageIndicatorProps` extends the props of a `div`, except `children`, and
accepts a ref. The root carries `data-variant`, `data-size` and `data-framed`,
and the button of the current page `data-current`. The types
`PageIndicatorVariant`, `PageIndicatorSize` and `PageIndicatorLabels` are
exported.

[Read the installed source](/source/page-indicator).

## Usage notes

PageIndicator shows one mark per page and suits a handful of pages. Use [Pagination](/docs/components/pagination/) for a long list or a table with numbered pages, and [Stepper](/docs/components/stepper/) for the steps of a task that people complete in order.

The md dots sit 20 px apart, closer than the 24 px target spacing that WCAG 2.2 asks for. Use `size="lg"` where people tap the dots, such as on a phone.
