# ch-paginator-render

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Use when](#use-when)
- [Do not use when](#do-not-use-when)
- [Accessibility](#accessibility)
- [Properties](#properties)
- [Events](#events)
- [Dependencies](#dependencies)
  - [Depends on](#depends-on)
  - [Graph](#graph)
- [Styling](./styling.md)

<!-- Auto Generated Below -->

## Overview

The `ch-paginator-render` component provides a fully customizable pagination control for navigating through paged data sets

## Features
 - Numeric and hyperlink-based pagination models
 - Configurable items-per-page selection via combo-box
 - First, previous, next, and last navigation buttons
 - "Go to page" numeric input for direct page access
 - Informational displays for current page range and item counts
 - Fully configurable layout and ordering of sub-controls via the `order` property
 - Full translation support for all visible text via the `translations` property

## Use when
 - Displaying large data sets that need to be split across multiple pages
 - Building SEO-friendly paginated navigation with hyperlink models
 - Displaying large datasets where loading all records at once would harm performance or UX (generally >25 items)
 - Data tables, search results, or content lists where users browse sequentially

## Do not use when
 - The data set is small enough to display on a single page
 - Infinite scrolling is preferred — use `ch-smart-grid` with `ch-infinite-scroll` instead
 - The full dataset is small enough to display at once — pagination adds unnecessary interaction cost
 - A social-feed-style infinite scroll is more appropriate for the browsing context
 - A linear multi-step form flow is needed — use a stepper instead

## Accessibility
 - Navigation buttons carry `aria-label` attributes for clear screen-reader announcements
 - The current page element is marked with `aria-current="page"`
 - All translatable labels are configurable via the `translations` property for internationalization
 - The "go to page" input supports keyboard confirmation with the Enter key

## Properties

| Property                     | Attribute                       | Description                                                                                    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |   |
| `hasNextPage`                | `has-next-page`                 | Indicates that the end has been reached. Use when total pages are not known (totalPages = -1). | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `itemsPerPage`               | `items-per-page`                | Number for Total Items Per Page.                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `10`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `itemsPerPageOptions`        | --                              | Specifies the options in Items Per Page combo-box.                                             | `ComboBoxItemModel[]`                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `maxPagesToShowLeft`         | `max-pages-to-show-left`        | Number of pages to show starting from the selected page to the left.                           | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `3`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `maxPagesToShowRight`        | `max-pages-to-show-right`       | Number of pages to show starting from the selected page to the right.                          | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `3`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `model`                      | --                              | Specifies the UI Model for the Paginator.                                                      | `string[] \| ({ totalPages?: number; urlMapping?: (index: number) => string; })`                                                                                                                                                                                                                                                                                                                                                                                  | `[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `order`                      | --                              | Specifies the order for the controls.                                                          | `{ itemsPerPage?: number; itemsPerPageInfo?: number; firstControl?: number; lastControl?: number; prevControl?: number; nextControl?: number; navigationControls?: number; navigationGoTo?: number; navigationControlsInfo?: number; }`                                                                                                                                                                                                                           | `{     itemsPerPage: 1,     itemsPerPageInfo: 2,     firstControl: 3,     prevControl: 4,     navigationControls: 5,     nextControl: 6,     lastControl: 7,     navigationGoTo: 8,     navigationControlsInfo: 9   }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `selectedPage`               | `selected-page`                 | Specifies the Selected Page, can be a number or hyperlink.                                     | `number \| string`                                                                                                                                                                                                                                                                                                                                                                                                                                                | `1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `showFirstControl`           | `show-first-control`            | `true` to render the navigation First control.                                                 | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showItemsPerPage`           | `show-items-per-page`           | `true` to render the Items Per Page control.                                                   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showItemsPerPageInfo`       | `show-items-per-page-info`      | `true` to render the Items Per Page Info.                                                      | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showLastControl`            | `show-last-control`             | `true` to render the navigation Last control.                                                  | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showNavigationControls`     | `show-navigation-controls`      | `true` to render the navigation controls.                                                      | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `true`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showNavigationControlsInfo` | `show-navigation-controls-info` | `true` to render the navigation Info.                                                          | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showNavigationGoTo`         | `show-navigation-go-to`         | `true` to render the navigation Go To control.                                                 | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showNextControl`            | `show-next-control`             | `true` to render the navigation Next control.                                                  | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `showPrevControl`            | `show-prev-control`             | `true` to render the navigation Prev control.                                                  | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `totalItems`                 | `total-items`                   | Number for Total Items, default = undefined.                                                   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `translations`               | --                              | Specifies the literals required in the control.                                                | `{ accessibleName: { currentPage: string; goToPage: string; goToInput: string; itemsPerPageOptions: string; firstButton: string; lastButton: string; nextButton: string; previousButton: string; }; text: { first: string; goToButton: string; of: string; itemsPerPage: string; ellipsis: string; last: string; next: string; goToInputLabel: string; prev: string; showingItems: string; showingPage: string; unknownPages: string; unknownItems: string; }; }` | `{     accessibleName: {       currentPage: "current page, page ",       goToPage: "go to page ",       goToInput: "Go to page",       itemsPerPageOptions: "Select amount of items to show",       firstButton: "Go to first page",       nextButton: "Go to next page",       lastButton: "Go to last page",       previousButton: "Go to previous page"     },     text: {       goToButton: "Go",       itemsPerPage: "Items per page:",       of: "of ",       ellipsis: "...",       first: "First",       prev: "Prev",       next: "Next",       last: "Last",       unknownPages: "many",       unknownItems: "many",       showingItems: `Showing ${FIRST_ITEM_IN_PAGE} - ${LAST_ITEM_IN_PAGE} of ${TOTAL_ITEMS} items`,       goToInputLabel: "Page:",       showingPage: `Showing ${ACTUAL_PAGE} of ${TOTAL_PAGES} pages`     }   }` |

## Events

| Event                | Description                                            | Type                  |
| -------------------- | ------------------------------------------------------ | --------------------- |
| `itemsPerPageChange` | Event fired when the amount of items per page changes. | `CustomEvent<number>` |
| `pageChange`         | Event fired when there is a new page selection.        | `CustomEvent<number>` |

## Dependencies

### Depends on

 - [ch-combo-box-render](../ch-combo-box-render/README.md)

### Graph
```mermaid
graph TD;
  ch-paginator-render --> ch-combo-box-render
  ch-combo-box-render --> ch-popover
  style ch-paginator-render fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------


