# Pagination

Moves between pages of a long list.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Pagination.tsx)

## Overview

Pagination is a navigation landmark that links to pages of a list, with previous and next steps.

Use it when a list is split across pages rather than loaded as you scroll.

## Examples

### Basic

```tsx
import { Pagination } from '@tempoxyz/ds'

function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
  return (
    <Pagination size={props.size}>
      <Pagination.Previous disabled={props.current === 1} href="#" />
      <Pagination.Page current={props.current === 1} href="#">
        1
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 4} href="#">
        4
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 9} href="#">
        9
      </Pagination.Page>
      <Pagination.Next disabled={props.current === 9} href="#" />
    </Pagination>
  )
}

export function Demo() {
  return <Pages current={4} />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Basic.tsx)

### Size

Set `size` to `small`, `medium`, or `large`. It defaults to `medium`.

```tsx
import { Pagination, Stack } from '@tempoxyz/ds'

function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
  return (
    <Pagination size={props.size}>
      <Pagination.Previous disabled={props.current === 1} href="#" />
      <Pagination.Page current={props.current === 1} href="#">
        1
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 4} href="#">
        4
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 9} href="#">
        9
      </Pagination.Page>
      <Pagination.Next disabled={props.current === 9} href="#" />
    </Pagination>
  )
}

export function Demo() {
  return (
    <Stack gap="4">
      <Pages current={4} size="small" />
      <Pages current={4} size="medium" />
      <Pages current={4} size="large" />
    </Stack>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Size.tsx)

### Current

Set `current` on exactly one `Pagination.Page`. `Pagination.Previous` and `Pagination.Next` take `disabled` at either end.

```tsx
import { Pagination, Stack } from '@tempoxyz/ds'

function Pages(props: { current: number; size?: Pagination.Props['size'] }) {
  return (
    <Pagination size={props.size}>
      <Pagination.Previous disabled={props.current === 1} href="#" />
      <Pagination.Page current={props.current === 1} href="#">
        1
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 4} href="#">
        4
      </Pagination.Page>
      <Pagination.Ellipsis />
      <Pagination.Page current={props.current === 9} href="#">
        9
      </Pagination.Page>
      <Pagination.Next disabled={props.current === 9} href="#" />
    </Pagination>
  )
}

export function Demo() {
  return (
    <Stack gap="4">
      <Pages current={1} />
      <Pages current={4} />
      <Pages current={9} />
    </Stack>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Pagination/Current.tsx)

## Guidelines

TODO: Write guidelines for Pagination.