# Pagination (w-pagination)

## Description

Pagination allows users to navigate through multiple pages of content by providing navigation controls with page numbers and directional arrows.

[Warp component reference](https://warp-ds.github.io/docs/components/pagination/frameworks/elements)

## Usage


The pagination component automatically shows/hides navigation buttons based on the current page:

- **First page button** (double chevron): Shown when current page is greater than 2
- **Previous page button** (single chevron): Shown when current page is greater than 1
- **Next page button** (single chevron): Shown when current page is less than total pages

On mobile devices, the page numbers are hidden and replaced with a "Page X" label for a cleaner interface.


<elements-example>

```html
<w-pagination base-url="#/search?page=" pages="5" current-page="1"></w-pagination>
```

</elements-example>

## Accessibility

## Examples

### Single-page app behavior

By default the pagination component uses link which trigger a full page navigation.

If you want to override this in your app and handle things like scroll and focus management on your own you can add an event listener to the pagination component and prevent the default navigation.

```html
<w-pagination base-url="/search?page=" pages="10" current-page="5"></w-pagination>

<script type="module">
  const pagination = document.querySelector('w-pagination');

  pagination.addEventListener('page-click', (event) => {
    event.preventDefault();
    // event.detail = { clickedPage: string }
    console.log('Do something with the clicked page after preventing default navigation:', event.detail.clickedPage);
  });
</script>
```

## Styling API

## `<w-pagination>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| base-url | `string \| undefined` | `-` | The base URL used to construct page links, for example `/search?page=`. |
| current-page | `number` | `1` | The currently active page number. |
| pages | `number` | `0` | The total number of pages. |
| visible-pages | `number` | `7` | The maximum number of page numbers visible. |

### Property Details

#### base-url

The base URL used to construct page links, for example `/search?page=`.

The page number is appended to this URL.

- Type: `string | undefined`
- Default: `-`

#### current-page

The currently active page number.

- Type: `number`
- Default: `1`

#### pages

The total number of pages.

- Type: `number`
- Default: `0`

#### visible-pages

The maximum number of page numbers visible.

- Type: `number`
- Default: `7`

### Events

#### page-click

Triggered when a link in the pagination is clicked. Contains the page number in `string` form.

- Type: `CustomEvent`


