Siteplane UI

Page Indicator

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

Markdown

Invite your team

"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

Usage

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.

"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.

"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.

"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

Component properties
PropTypeDefaultDescription
PageIndicator.countnumberrequiredThe number of pages, one mark each.
PageIndicator.pagenumberrequiredThe current page, counted from 1. A page outside 1 to count marks none.
PageIndicator.onPageChange(page: number) => voidunsetCalled 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.framedbooleanfalseSets the marks on a translucent pill, for an indicator on an image.
PageIndicator.labelsPartial<PageIndicatorLabels>EnglishReplaces 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-labelstringlabels.groupThe 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.

Usage notes

PageIndicator shows one mark per page and suits a handful of pages. Use Pagination for a long list or a table with numbered pages, and 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.