Navs
Pagination
Bit.BlazorUI
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.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Count is all it needs. DefaultSelectedPage picks the page it starts on (the first by default);
Disabled disables every control.
Binding
SelectedPage bound one way is only rendered, never changed: apply the clicks OnChange reports yourself.
Bound two ways it follows the clicks on its own. OnChange runs in both cases.
One-way:
Two-way:
OnChange:
Changed page: 3
Variant & Rounded
Variant: Fill (default), Outline or Text. Rounded turns the buttons and the ellipses
into circles, or pills where a button is wider than it is tall.
BoundaryCount & MiddleCount
BoundaryCount (2 by default) is how many pages stay at each end of the range; MiddleCount (3 by default) how
many surround the selected one. An ellipsis that would hide a single page shows that page instead.
Ellipsis
EllipsisText replaces the glyph and EllipsisAriaLabel the name it is announced with.
ClickableEllipsis makes each gap a control that jumps into the middle of the pages it hides, named (and
tooltipped) by the page it lands on.
Navigation buttons
ShowFirstButton and ShowLastButton add the jumps to the ends; ShowPreviousButton and
ShowNextButton (on by default) turn those two off. Loop wraps previous and next around the ends.
Button text & icons
FirstButtonText, PreviousButtonText, NextButtonText and LastButtonText put a text beside the icon;
the *ButtonIconName parameters replace the chevrons (only the default chevrons mirror in RTL).
Compact & Summary
ShowPageButtons="false" leaves the navigation buttons alone. ShowSummary adds "Page 4 of 12", a status
region a screen reader announces as the page changes; GetSummary rewrites it from the page and the page count.
Total items & Page size
TotalItems replaces Count: the range follows PageSize, the summary counts items ("1 - 10 of 240",
reworded by GetItemsSummary from the first item, the last one and the total), and a new size keeps the first item of the
page in view. ShowPageSizeSelector picks the size out of PageSizeOptions.
Page 1, 10 items a page
With Count instead, recompute it from the size OnPageSizeChange / @bind-PageSize reports.
An empty PageSizeText drops the visible label and PageSizeAriaLabel names the select.
Page 1 of 24, 10 items a page
Go to page
ShowGoToPage adds an input that jumps to the page typed into it on Enter or blur; a number past either end lands on
that end. GoToPageText="" drops the label and GoToPageAriaLabel names the input.
Hide on single page
HideOnSinglePage renders nothing at all (summary, selector and jump included) while there is a single page.
(nothing is rendered above for a single page)
Alignment
Alignment stretches the pagination across its container and lines the controls up inside it.
Baseline and Stretch do not apply to a single row.
Links
GetPageHref turns every control into a link, so pages can be crawled, bookmarked or opened in another tab (previous and
next carry
rel="prev" / rel="next"). A link with nowhere to go drops its href and reports
aria-disabled. A plain click still selects the page; a Ctrl/Cmd/Shift/Alt click leaves it to the browser.
Selected page: 1
Accessibility
A
nav landmark (named by AriaLabel; give each one its own name) holding a list, with the current page marked
aria-current="page". The *ButtonAriaLabel parameters name the icon buttons (and double as tooltips),
GetPageAriaLabel names the pages - keep the visible number in it for speech input. A button that disables itself hands the focus to the selected page, and
FocusAsync puts it back after a reload.
Cascading parameters
BitParams with a BitPaginationParams sets defaults for every pagination inside it - the one place to localize
them all. A pagination's own parameters win; only unset ones are filled in. AriaLabel stays on each one, since
every landmark needs a name of its own.
Outside the cascade:
Color
Color paints the buttons, the hover, the selected page and the focus ring from one role.
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
Disabled
External Icons
FirstButtonIcon, PreviousButtonIcon, NextButtonIcon and LastButtonIcon take a
BitIconInfo from any icon set (FontAwesome, Bootstrap Icons, ...).
FontAwesome:
Bootstrap:
Size
Size scales the buttons, the text, the selector and the jump together.
Style & Class
Reach for the --bit-Pagination-* CSS variables first (listed in the API section): they inherit, so set them on
:root, an ancestor or an instance's Style. They restyle the default, not a choice: an explicit
Color, Size or Rounded wins over the variables for what it sets.
Style/Class and Styles/Classes (per part) cover the rest.
CSS variables:
Style & Class:
Styles & Classes:
RTL
Use BitPagination in right-to-left (RTL); the chevrons mirror along with the layout.
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.
BitPagination CSS variables
| 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. |
| --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. |
| --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. |
| --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. |
| --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. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitPagination 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. |
BitPagination 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. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| 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. |
| 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. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| 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. |
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. |
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. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.