# Pagination
## Description
Pagination renders the navigation across a paged range: page buttons with ellipses, first/previous/next/last buttons, a position summary, a page size selector and a go to page input. Every control is a button, or a link once given an address, inside a named navigation landmark.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Alignment | `BitAlignment?` | null | Stretches the pagination across its container and lines the controls up inside it. Baseline and Stretch do not apply. |
| BoundaryCount | `int` | 2 | The number of items at the start and end of the pagination. A value that is not positive falls back to the default. |
| Classes | `BitPaginationClassStyles?` | null | Custom CSS classes for different parts of the pagination. |
| ClickableEllipsis | `bool` | false | Turns every ellipsis into a button (or link) that jumps into the middle of the pages it hides, named by EllipsisAriaLabel plus the page it lands on ("More pages (Page 38)"). |
| Color | `BitColor?` | null | The general color of the pagination. An explicit value wins over the --bit-Pagination-* button, selected and focus color variables; left unset, the pagination is primary unless they say otherwise. |
| Count | `int` | 1 | The total number of pages. Ignored while TotalItems is set. |
| DefaultSelectedPage | `int` | 0 | The default selected page number. |
| EllipsisAriaLabel | `string` | "More pages" | The accessible name of an ellipsis, announced in place of its glyph. A clickable one appends the label of the page it jumps to. |
| EllipsisText | `string` | "•••" | The text of the ellipsis standing in for the pages that are collapsed out of the range. |
| FirstButtonAriaLabel | `string` | "First page" | The accessible label of the first button, which is used as its tooltip as well until FirstButtonText puts a visible text beside its icon. |
| FirstButtonIcon | `BitIconInfo?` | null | The icon for the first button using custom CSS classes for external icon libraries. Takes precedence over FirstButtonIconName when both are set. |
| FirstButtonIconName | `string?` | null | The built-in icon name for the first button. |
| FirstButtonText | `string?` | null | The text rendered beside the icon of the first button, which widens to fit it. The accessible name still comes from FirstButtonAriaLabel. |
| GetItemsSummary | `Func<int, int, int, string>?` | null | Provides the text of the summary while TotalItems is set, from the first item of the page, its last one and the total, replacing "{first} - {last} of {total}". Wins over GetSummary there. |
| GetPageAriaLabel | `Func<int, bool, string>?` | null | Provides the accessible label of a page button, from its one-based number and whether it is the selected one, replacing the default "Page {number}" label. |
| GetPageHref | `Func<int, string?>?` | null | Provides the address of a page, which turns every control into a link. A link with nowhere to go drops its href and reports aria-disabled. |
| GetSummary | `Func<int, int, string>?` | null | Provides the text of the summary from the selected page and the page count, replacing "Page {number} of {count}" (and "1 - 10 of 240" while TotalItems is set, unless GetItemsSummary is). |
| GoToPageAriaLabel | `string` | "Go to page" | The accessible name of the go to page input while GoToPageText is empty. |
| GoToPageText | `string?` | "Go to" | The visible label of the go to page input. Empty drops it, and GoToPageAriaLabel names the input. |
| HideOnSinglePage | `bool` | false | Renders nothing at all while there is a single page to navigate, the summary, the page size selector and the jump included. |
| LastButtonAriaLabel | `string` | "Last page" | The accessible label of the last button, which is used as its tooltip as well until LastButtonText puts a visible text beside its icon. |
| LastButtonIcon | `BitIconInfo?` | null | The icon for the last button using custom CSS classes for external icon libraries. Takes precedence over LastButtonIconName when both are set. |
| LastButtonIconName | `string?` | null | The built-in icon name for the last button. |
| LastButtonText | `string?` | null | The text rendered beside the icon of the last button, which widens to fit it. The accessible name still comes from LastButtonAriaLabel. |
| Loop | `bool` | false | Wraps the next and previous buttons around the ends of the range, and keeps them enabled there. |
| MiddleCount | `int` | 3 | The number of items to render in the middle of the pagination. A value that is not positive falls back to the default. |
| NextButtonAriaLabel | `string` | "Next page" | The accessible label of the next button, which is used as its tooltip as well until NextButtonText puts a visible text beside its icon. |
| NextButtonIcon | `BitIconInfo?` | null | The icon for the next button using custom CSS classes for external icon libraries. Takes precedence over NextButtonIconName when both are set. |
| NextButtonIconName | `string?` | null | The built-in icon name for the next button. |
| NextButtonText | `string?` | null | The text rendered beside the icon of the next button, which widens to fit it. The accessible name still comes from NextButtonAriaLabel. |
| OnChange | `EventCallback<int>` | null | The event callback for when selected page changes. It also runs when SelectedPage is bound one way. |
| OnPageSizeChange | `EventCallback<int>` | null | The event callback for when a page size is picked. It also runs when PageSize is bound one way. |
| PageSize | `int` | 0 | The number of items a page holds, which the page size selector picks. Not positive falls back to the first of the PageSizeOptions; one not among them is offered along with them. |
| PageSizeAriaLabel | `string` | "Items per page" | The accessible name of the page size selector while PageSizeText is empty. |
| PageSizeOptions | `IEnumerable<int>?` | null | The page sizes the selector offers (10, 25, 50 and 100 by default). Sizes that are not positive are dropped. |
| PageSizeText | `string?` | "Items per page" | The visible label of the page size selector. Empty drops it, and PageSizeAriaLabel names the select. |
| PreviousButtonAriaLabel | `string` | "Previous page" | The accessible label of the previous button, which is used as its tooltip as well until PreviousButtonText puts a visible text beside its icon. |
| PreviousButtonIcon | `BitIconInfo?` | null | The icon for the previous button using custom CSS classes for external icon libraries. Takes precedence over PreviousButtonIconName when both are set. |
| PreviousButtonIconName | `string?` | null | The built-in icon name for the previous button. |
| PreviousButtonText | `string?` | null | The text rendered beside the icon of the previous button, which widens to fit it. The accessible name still comes from PreviousButtonAriaLabel. |
| Rounded | `bool` | false | Renders the buttons and the ellipses of the pagination with fully rounded corners: circles, or pills where a button is wider than it is tall. |
| SelectedPage | `int` | 0 | The selected page number. It is one-based and is clamped into the available range while rendering. |
| ShowFirstButton | `bool` | false | Determines whether to show the first button. |
| ShowGoToPage | `bool` | false | Shows an input that jumps to the page typed into it on Enter or blur; a number past either end lands on that end. |
| ShowLastButton | `bool` | false | Determines whether to show the last button. |
| ShowNextButton | `bool` | true | Determines whether to show the next button. |
| ShowPageButtons | `bool` | true | Determines whether to show the numeric page buttons. Turning them off leaves a compact pagination made of the navigation buttons only. |
| ShowPageSizeSelector | `bool` | false | Shows a selector that picks how many items a page holds, reported through PageSize and OnPageSizeChange. |
| ShowPreviousButton | `bool` | true | Determines whether to show the previous button. |
| ShowSummary | `bool` | false | Shows "Page {number} of {count}" ("1 - 10 of 240" while TotalItems is set) in a status region a screen reader announces as the page changes. |
| Size | `BitSize?` | null | The size of the buttons. An explicit value wins over --bit-Pagination-font-size and --bit-Pagination-button-size; left unset, the pagination is medium unless they say otherwise. |
| Styles | `BitPaginationClassStyles?` | null | Custom CSS styles for different parts of the BitPagination. |
| TotalItems | `int` | 0 | The number of items paged through, which with PageSize replaces Count. A new page size then keeps the first item of the page in view. |
| Variant | `BitVariant?` | null | The visual variant of the pagination. |
| AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `() => ValueTask` | | Gives the keyboard focus to the button of the selected page, falling back to the first navigation button that is rendered while the page buttons are turned off. Call it after reloading the list behind the pagination to put the focus back where the reload was asked from. |
| UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. |
## Enums
### BitAlignment Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Start | 0 | Lines the controls up at the start of the room. |
| End | 1 | Lines the controls up at the end of the room. |
| Center | 2 | Centers the controls inside the room. |
| SpaceBetween | 3 | Shares the room out between the controls, leaving none of it at the two ends. |
| SpaceAround | 4 | Shares the room out around the controls, leaving half of it at the two ends. |
| SpaceEvenly | 5 | Shares the room out evenly between the controls and at the two ends. |
| Baseline | 6 | Lines the controls up on their baseline. |
| Stretch | 7 | Stretches the controls across the room. |
### BitColor Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Primary | 0 | Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
### BitVariant Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Fill | 0 | Fill styled variant. |
| Outline | 1 | Outline styled variant. |
| Text | 2 | Text styled variant. |
### BitVisibility Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
### BitDir Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
## Sub Classes
### BitIconInfo Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Name | `string?` | null | Gets or sets the name of the icon. |
| BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. |
| Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. |
### BitPaginationClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitPagination. |
| PageSizeSelector | `string?` | null | Custom CSS classes/styles for the page size selector container of the BitPagination. |
| PageSizeLabel | `string?` | null | Custom CSS classes/styles for the page size label of the BitPagination. |
| PageSizeSelect | `string?` | null | Custom CSS classes/styles for the page size select of the BitPagination. |
| Summary | `string?` | null | Custom CSS classes/styles for the summary of the BitPagination. |
| GoToPage | `string?` | null | Custom CSS classes/styles for the go to page container of the BitPagination. |
| GoToPageLabel | `string?` | null | Custom CSS classes/styles for the go to page label of the BitPagination. |
| GoToPageInput | `string?` | null | Custom CSS classes/styles for the go to page input of the BitPagination. |
| Button | `string?` | null | Custom CSS classes/styles for the button of the BitPagination. |
| ButtonText | `string?` | null | Custom CSS classes/styles for the text rendered beside the icon of a navigation button of the BitPagination. |
| Ellipsis | `string?` | null | Custom CSS classes/styles for the ellipsis of the BitPagination. |
| SelectedButton | `string?` | null | Custom CSS classes/styles for the selected button of the BitPagination. |
| FirstButton | `string?` | null | Custom CSS classes/styles for the first button of the BitPagination. |
| FirstButtonIcon | `string?` | null | Custom CSS classes/styles for the icon of the first button of the BitPagination. |
| PreviousButton | `string?` | null | Custom CSS classes/styles for the previous button of the BitPagination. |
| PreviousButtonIcon | `string?` | null | Custom CSS classes/styles for the icon of the previous button of the BitPagination. |
| NextButton | `string?` | null | Custom CSS classes/styles for the next button of the BitPagination. |
| NextButtonIcon | `string?` | null | Custom CSS classes/styles for the icon of the next button of the BitPagination. |
| LastButton | `string?` | null | Custom CSS classes/styles for the last button of the BitPagination. |
| LastButtonIcon | `string?` | null | Custom CSS classes/styles for the icon of the last button of the BitPagination. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-Pagination-gap` | spacing(0.5) | Room between the controls. |
| `--bit-Pagination-color` | inherit | Text color of the summary, the labels and the ellipsis. |
| `--bit-Pagination-font-size` | --bit-tpg-fs-sm | Text size of every control. The Size parameter wins over it. |
| `--bit-Pagination-button-size` | --bit-siz-ctrl-md | Height and minimum width of a button, which the ellipsis, the summary, the selector and the jump stand at too. The Size parameter wins over it. |
| `--bit-Pagination-button-radius` | --bit-shp-radius-control | Corner radius of the buttons and the ellipses. Rounded wins over it. |
| `--bit-Pagination-button-border-width` | --bit-shp-brd-width | Border thickness of the buttons. |
| `--bit-Pagination-button-color` | Per Variant, from the primary role | Label color of a button at rest. The Color parameter wins over it. Shared by the three variants: --bit-Pagination-fill-button-color, --bit-Pagination-outline-button-color and --bit-Pagination-text-button-color are read ahead of it. |
| `--bit-Pagination-button-background` | Per Variant, from the primary role | Fill of a button at rest. The Color parameter wins over it in Fill; the transparent fill of Outline and Text is its alone. Shared by the three variants: --bit-Pagination-fill-button-background, --bit-Pagination-outline-button-background and --bit-Pagination-text-button-background are read ahead of it. |
| `--bit-Pagination-button-border-color` | Per Variant, from the primary role | Border color of a button at rest. The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Pagination-fill-button-border-color, --bit-Pagination-outline-button-border-color and --bit-Pagination-text-button-border-color are read ahead of it. |
| `--bit-Pagination-fill-button-color` | --bit-Pagination-button-color | Label color of a button at rest of a Fill pagination alone, read ahead of --bit-Pagination-button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-fill-button-background` | --bit-Pagination-button-background | Fill of a button at rest of a Fill pagination alone, read ahead of --bit-Pagination-button-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-fill-button-border-color` | --bit-Pagination-button-border-color | Border color of a button at rest of a Fill pagination alone, read ahead of --bit-Pagination-button-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-outline-button-color` | --bit-Pagination-button-color | Label color of a button at rest of an Outline pagination alone, read ahead of --bit-Pagination-button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-outline-button-background` | --bit-Pagination-button-background | Fill of a button at rest of an Outline pagination alone, read ahead of --bit-Pagination-button-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Pagination-outline-button-border-color` | --bit-Pagination-button-border-color | Border color of a button at rest of an Outline pagination alone, read ahead of --bit-Pagination-button-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-text-button-color` | --bit-Pagination-button-color | Label color of a button at rest of a Text pagination alone, read ahead of --bit-Pagination-button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Pagination-text-button-background` | --bit-Pagination-button-background | Fill of a button at rest of a Text pagination alone, read ahead of --bit-Pagination-button-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Pagination-text-button-border-color` | --bit-Pagination-button-border-color | Border color of a button at rest of a Text pagination alone, read ahead of --bit-Pagination-button-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Pagination-button-hover-color` | --bit-clr-pri-text | Label color of a hovered button. The Color parameter wins over it. |
| `--bit-Pagination-button-hover-background` | --bit-clr-pri-hover | Fill and border color of a hovered button. The Color parameter wins over it. |
| `--bit-Pagination-button-active-color` | --bit-Pagination-button-hover-color, then --bit-clr-pri-text | Label color of a pressed button. The Color parameter wins over it. |
| `--bit-Pagination-button-active-background` | --bit-Pagination-button-hover-background, then --bit-clr-pri-active | Fill and border color of a pressed button. The Color parameter wins over it. |
| `--bit-Pagination-selected-color` | --bit-clr-pri-text | Label color of the current page, held under the pointer too. The Color parameter wins over it. |
| `--bit-Pagination-selected-background` | --bit-clr-pri-dark | Fill and border color of the current page, held under the pointer too. The Color parameter wins over it. |
| `--bit-Pagination-selected-font-weight` | --bit-tpg-fw-semibold | Weight of the number of the current page, heavier than the rest so it is not told apart by color alone. |
| `--bit-Pagination-focus-color` | --bit-clr-pri-focus | Color of the keyboard focus ring of every control. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. |
| `--bit-Pagination-input-color` | --bit-clr-fg-pri | Text color of the page size select and the go to page input. |
| `--bit-Pagination-input-background` | --bit-clr-bg-sec | Fill of the page size select and the go to page input. |
| `--bit-Pagination-input-border-color` | --bit-clr-brd-sec | Border color of the page size select and the go to page input, under the pointer as well. |
## Examples
\n**Basic**:
```razor
Reload & focus the pagination
```
```csharp
private BitPagination accessiblePagination = default!;
private string GetResultsRangeLabel(int page, bool isSelected)
{
return $"Page {page}, results {(page - 1) * 10 + 1} to {page * 10}";
}
```
\n**Cascading parameters**:
```razor
One-way:
Two-way:
OnChange:
Changed page: @onChangeSelectedPage
Page @totalItemsSelectedPage, @totalItemsPageSize items a page
Page @pageSizeSelectedPage of @pageSizeCount, @selectedPageSize items a page
```
```csharp
private int totalItemsPageSize = 10;
private int totalItemsSelectedPage = 1;
private const int totalItems = 240;
private int selectedPageSize = 10;
private int pageSizeSelectedPage = 1;
private int pageSizeCount => (int)Math.Ceiling(totalItems / (double)selectedPageSize);
```
\n**Go to page**:
```razor
Selected page: @linkSelectedPage
```
```csharp
[SupplyParameterFromQuery(Name = "page")] public string? LinkPage { get; set; }
private const int linkPageCount = 8;
private int linkSelectedPage = 1;
protected override void OnParametersSet()
{
if (int.TryParse(LinkPage, out var page))
{
linkSelectedPage = Math.Clamp(page, 1, linkPageCount);
}
base.OnParametersSet();
}
private string GetDemoPageHref(int page)
{
return $"?page={page}";
}
```
\n**Accessibility**:
```razor