Navs
Pagination
Bit.BlazorUI
Pagination splits long content into pages and renders the navigation to move between them. The range of pages is either given as a page count or worked out from the number of items and the page size, and it collapses into ellipses (clickable ones, if you want) when the pages do not fit. Around it sit optional first, previous, next and last buttons, a position summary, a page size selector and a jump straight to a page number. Every control renders as a button or, given an address, as a link; the selected page binds one way or two ways; and the whole thing is a navigation landmark that names each of its controls for assistive technologies.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
The Count parameter is the total number of pages, and it is all the pagination needs to render. The first page is selected by default and the previous and next buttons are shown,
while the buttons that cannot go anywhere are disabled. When the number of items is what you know rather than the number of pages, hand it TotalItems instead.
Variants
The pagination offers three variants: Fill (default) paints the buttons, Outline leaves them on the surface behind a border, and Text drops both and keeps the label alone.
Fill
Outline
Text
Default selected
DefaultSelectedPage is the page the pagination starts on while it keeps the selection itself. Use it for an uncontrolled pagination; to drive the selection from your own state, bind SelectedPage instead.
BoundaryCount
BoundaryCount is how many pages stay visible at each end of the range, no matter which page is selected, so the first and the last pages are always one click away.
The default is 2, and a value that is not positive falls back to it, since a range with no fixed ends would lose that shortcut altogether.
MiddleCount
MiddleCount is how many pages are rendered around the selected one, between the two ellipses. The default is 3, and a value that is not positive falls back to it. An ellipsis that would hide a single page is replaced by that page, since it takes the same room.
Ellipsis
EllipsisText replaces the glyph standing in for the pages that are collapsed out of the range, and EllipsisAriaLabel the name it is announced with.
A plain gap keeps its glyph hidden from assistive technologies and lets the item around it carry that name, so it is reported as one named item instead of being read out as a run of punctuation.
ClickableEllipsis turns each gap into a control that jumps into the middle of the pages it hides, which is what makes the middle of a few hundred pages reachable in a couple of clicks
instead of one window at a time. It becomes a button (or a link, along with the rest of the pagination) named by EllipsisAriaLabel, so it is announced and reached like any other control.
The jump can spell the pages it landed among out in place of the gap that was clicked, so the focus is handed over to the page the pagination settled on rather than being dropped on the document.
Navigation buttons
Beside the previous and next buttons, which are shown by default, ShowFirstButton and ShowLastButton add the jumps to the two ends of the range.
Each of the four can be turned off on its own through ShowPreviousButton and ShowNextButton. A button that has nowhere left to go disables itself at the end of the range it points at.
Without the previous and next buttons:
Button labels
FirstButtonText, PreviousButtonText, NextButtonText and LastButtonText put a text beside the icon of a navigation button, which widens to fit it.
The spoken name still comes from the matching AriaLabel parameter, so a short visible text can sit next to a fuller one for a screen reader.
Compact
ShowPageButtons turns the numeric page buttons off and leaves only the navigation buttons, which is the compact pagination a narrow layout calls for,
or an unbounded result set where the number of pages is not worth spelling out.
Summary
ShowSummary puts the position in the range ahead of the buttons, reading "Page {number} of {count}", and GetSummary replaces that text from the selected page and the total number of pages,
which is the hook to localize it or to count the items rather than the pages.
The summary is a status region, so a screen reader reports the new position as the page changes. That makes it the piece to pair with ShowPageButtons turned off,
where nothing else says which page of how many is the current one.
Total items
TotalItems is the size of the result set, and the number of pages is worked out from it and the page size, replacing Count.
It is the form to reach for whenever the size of the result set is known: the range follows the page size on its own, so the
page size selector needs nothing wired up behind it, and the summary reports the items ("1 - 10 of 240") instead of the pages.
Picking a new size keeps the first item of the current page in view rather than the page number, so a jump from 10 to 100 items a page lands on the page those items ended up on
instead of at the end of a range that just got shorter.
Page 1 of 24, 10 items a page
Page size
ShowPageSizeSelector opens the pagination with a selector of how many items a page holds, picked out of PageSizeOptions (10, 25, 50 and 100 by default).
Picking a size reports it through the two-way bound PageSize and through OnPageSizeChange. A size that is not one of the options is offered along with them, in its place among them,
so the selector never shows one size while the pagination runs on another — and a pick that is not taken (PageSize bound one way and left where it was) puts the selector back on the size in force.
The example below is the form without TotalItems: the number of pages the new size adds up to is yours to recompute into Count,
and a selected page that falls out of the shrunk range is pulled back on its own. Hand it the number of items instead and both of those are taken care of for you.
PageSizeText is the visible text ahead of the selector, and it is what names the selector while it is there. Drop it for the compact form a narrow layout calls for
and PageSizeAriaLabel steps in, so the selector is never left unnamed and never announced as something other than what is written beside it.
Page size: 10, page: 1 of 24
Go to page
ShowGoToPage closes the pagination with an input that jumps straight to the page number typed into it, which is the shortcut a long range needs.
The jump runs when the input is committed (on Enter, or when it loses the focus), a number past the ends of the range lands on the nearest one rather than being dropped,
and the field clears itself afterwards so the next jump starts from an empty one.
GoToPageText is the visible text ahead of the input, and it is what names the input while it is there. Drop it for the compact form and GoToPageAriaLabel steps in,
so the input is never left unnamed and never announced as something other than what is written beside it.
Loop
Loop wraps the previous and next buttons around the ends of the range: the next button moves from the last page back to the first one and the previous button from the first page to the last one.
Both buttons also stay enabled at the ends while it is on, unless the range holds a single page and there is nowhere to wrap to. The first and last buttons are unaffected, since they always target a fixed page.
Hide on single page
HideOnSinglePage renders nothing at all while there is a single page to navigate, so a short result set is not left with navigation that cannot go anywhere.
Nothing at all means nothing at all: the summary, the page size selector and the jump go with the page controls, so leave it off wherever a size big enough
to leave a single page would take the selector that picked it off the screen with it.
(nothing is rendered above for a single page)
Icon
Each navigation button takes its own built-in icon through FirstButtonIconName, PreviousButtonIconName, NextButtonIconName and LastButtonIconName, replacing the default chevrons.
The default chevrons are mirrored along with the layout in RTL; an icon you pick yourself is rendered as it is, so pick one that reads the same in both directions.
Rounded
Rounded renders the buttons, and the ellipses standing between them, as circles instead of the default rounded rectangles. A button that is wider than it is tall, like a navigation button carrying a text or a page number of several digits, becomes a pill, since a circle would stretch into an ellipse.
Alignment
The pagination is only as wide as its own controls, so it sits wherever the layout around it puts it. Alignment stretches it across the room it is given and lines the controls up
inside that room, which is what saves wrapping it in a flex container of its own. The controls are laid out along one row, so the BitAlignment values that place a box
along it apply - the three space distributions included - while
Baseline and Stretch, which place it across the other axis, leave the pagination where it starts.
Binding
With SelectedPage bound one way the pagination only renders the page you hand it and never changes it on its own, so the clicks reach you through OnChange and it is up to you to apply them.
Binding it two way lets the pagination keep the value in sync by itself. OnChange runs in both cases, and only for a page the user actually asked for.
One-way:
Two-way:
OnChange:
Changed page: 3
Links
GetPageHref gives every control the address of the page it points at, which turns the whole pagination into links instead of buttons, so the range can be crawled, opened in another tab, or bookmarked.
The four navigation controls ask for the address of the page they move to, so they turn into links along with the numeric ones.
A control with no page to reach — one at the end of the range it navigates, one the pagination is disabled for, or one GetPageHref returns nothing for — keeps its place while reporting
aria-disabled and staying out of the tab order.
The click still reaches OnChange and SelectedPage, so a pagination of links reports the page that was asked for exactly like a pagination of buttons — except for a click carrying a modifier
(Ctrl, Cmd, Shift or Alt), which opens the address somewhere else and leaves this pagination on the page it was on.
The previous and next links also carry rel="prev" and rel="next", which is what tells a crawler how the pages of the set follow one another.
Selected page: 1
Accessibility
The pagination renders as a navigation landmark holding a list of page buttons, and marks the selected page with
aria-current="page".
Give it a name through AriaLabel whenever more than one pagination shares a page, so each of them can be told apart in the landmark list, and point it at the region it pages through
with a plain aria-controls attribute, which lands on the landmark along with anything else you splat onto the component.
The navigation buttons carry no text, so each of them takes its accessible name from
FirstButtonAriaLabel, PreviousButtonAriaLabel, NextButtonAriaLabel and LastButtonAriaLabel, which doubles as the tooltip until a
visible text makes the tooltip a repetition of what is already on screen.
GetPageAriaLabel replaces the default "Page {number}" label of a page button from its number and whether it is the selected one, which is the hook to localize them or to say what the page holds.
EllipsisAriaLabel names the collapsed range, and GoToPageAriaLabel and PageSizeAriaLabel name the jump input and the page size selector whenever their visible texts are dropped.
A navigation button that reaches the end of the range it points at disables itself, which would drop the keyboard focus on the document. The focus is handed over to the page the pagination settled on instead,
or to the navigation button pointing the other way while the page buttons are turned off, so a keyboard walk through the range never loses its place.
A clickable ellipsis hands it over the same way, since the jump can spell the pages it landed among out in place of the gap that was clicked.
Color
Offering a range of specialized color variants, providing visual cues for specific actions or states within your application.
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
Disabled:
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
External Icons
Use icons from external libraries like FontAwesome and Bootstrap Icons with the navigation button Icon parameters.
See the BitIconInfo section in the parameters table for usage.
FontAwesome:
Bootstrap:
Size
Varying sizes for paginations tailored to meet diverse design needs, ensuring flexibility and visual hierarchy within your interface.
Small
Medium
Large
Style & Class
Empower customization by overriding default styles and classes, allowing tailored design modifications to suit specific UI requirements.
Component's Style & Class:
Styles & Classes:
RTL
Use BitPagination in right-to-left (RTL). The chevrons of the navigation buttons are mirrored along with the layout, so the next button keeps pointing at the direction the reading goes.
API
Every parameter, public member, sub-class and enum this component exposes.
BitPagination parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| Alignment | BitAlignment? | null | The horizontal alignment of the pagination inside the room it is given, which stretches it across that room. The pagination is only as wide as its own controls without it. |
| 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 control that jumps into the middle of the pages it collapses. It follows the rest of the pagination as a button or a link, is named by EllipsisAriaLabel, and hands the focus over to the page the jump landed on. |
| Color | BitColor? | null | The general color of the pagination. |
| Count | int | 1 | The total number of pages. It is ignored while TotalItems is set, since the number of pages then follows from the number of items and the page size. |
| DefaultSelectedPage | int | 0 | The default selected page number. |
| EllipsisAriaLabel | string | "More pages" | The accessible label of the item standing in for the pages an ellipsis collapses. The glyph itself is hidden from assistive technologies and this label is announced in its place. |
| 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. |
| 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 a page control points at, from its one-based number, which turns every control of the pagination into a link instead of a button. A control with no address to point at reports aria-disabled and stays out of the tab order. |
| GetSummary | Func<int, int, string>? | null | Provides the text of the summary, from the selected page and the total number of pages, replacing the default "Page {number} of {count}" (or "1 - 10 of 240" while TotalItems is set) text. |
| GoToPageAriaLabel | string | "Go to page" | The accessible label of the go to page input, which steps in once the visible GoToPageText beside it is dropped. While that text is there it is the one naming the input. |
| GoToPageText | string? | "Go to" | The text rendered ahead of the go to page input, which names it. An empty text leaves the input on its own, named by GoToPageAriaLabel. |
| 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 the page size is picked out of the page size selector. It also runs when PageSize is bound one way, and it is where Count is recomputed from the new page size. |
| PageSize | int | 0 | The number of items a page holds, which the page size selector picks. A value that is not positive falls back to the first of the PageSizeOptions and the fallback is written back while the selector is shown, and one that is positive but not among them is offered by the selector along with them. |
| PageSizeAriaLabel | string | "Items per page" | The accessible label of the page size selector, which steps in once the visible PageSizeText beside it is dropped. While that text is there it is the one naming the selector. |
| PageSizeOptions | IEnumerable<int>? | null | The page sizes the page size selector offers. Sizes that are not positive are dropped, and an empty list falls back to the default 10, 25, 50 and 100. A PageSize the list does not hold is offered along with the others. |
| PageSizeText | string? | "Items per page" | The text rendered ahead of the page size selector, which names it. An empty text leaves the selector on its own, named by PageSizeAriaLabel. |
| 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 of the pagination with fully rounded (circular) corners. |
| 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 straight to the page number typed into it, at the end of the pagination. The jump runs when the input is committed and a number outside of the range lands on the nearest end of it. |
| 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, ahead of everything else in the pagination. Picking a size reports it through PageSize and OnPageSizeChange, and recomputes the range of pages while TotalItems is set. |
| ShowPreviousButton | bool | true | Determines whether to show the previous button. |
| ShowSummary | bool | false | Shows the position in the range, which reads "Page {number} of {count}" (or "1 - 10 of 240" while TotalItems is set) unless GetSummary replaces it, ahead of the buttons of the pagination. It is a status region, so a screen reader reports the new position as the page changes. |
| Size | BitSize? | null | The size of the buttons. |
| Styles | BitPaginationClassStyles? | null | Custom CSS styles for different parts of the BitPagination. |
| TotalItems | int | 0 | The total number of items the pagination pages through, which the number of pages is worked out from along with PageSize, replacing Count. Picking a new page size then keeps the first item of the current page in view, and the summary reports the items instead of the pages. |
| 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. This is what a consumer reloading the list behind the pagination calls to put the focus back on the navigation 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. |
| 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. |
| IsEnabled | bool | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| 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 | Info 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. |
| Standard | 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.