HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
PaginationView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorControls for moving between the pages of a long set of results.StableSince 0.1.0NavigationUsageimport'@fusion.dev/helix/pagination'import'@fusion.dev/helix-headless/pagination'Preview
API ReferenceRoothelix-paginationControls for moving between the pages of a long set of results.
PropTypeDescriptionboundariesnumberDefault1How many pages to show at each end, whatever the current one is.compactbooleanDefaultfalseReplaces the page numbers with the current page and the page count, as
written by status-label.defaultPagenumberDefault1The page to open on when page is not set.endsbooleanDefaultfalseShows controls that jump to the first and last pages.firstLabelstringDefault"First page"Accessible name for the control that jumps to the first page.gapLabelstringDefault"Skip to page {page}"Accessible name for a gap. {page} is replaced with the page it jumps to.hrefstringDefault""The URL for each page. {page} is replaced with the page number.labelstringDefault"Pagination"Accessible name for the navigation landmark.lastLabelstringDefault"Last page"Accessible name for the control that jumps to the last page.localestringDefault""The locale the words and the page numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.nextLabelstringDefault"Next page"Accessible name for the control that moves forward.pagenumberThe current page, counting from one.pageLabelstringDefault"Page {page}"Accessible name for one page. {page} and {pages} are replaced with the
page number and the page count.pagesnumberDefault0How many pages there are in total.pageSizenumberDefault0How many items are on a page.previousLabelstringDefault"Previous page"Accessible name for the control that moves back.siblingsnumberDefault1How many pages to show either side of the current one.statusLabelstringDefault"{page} of {pages}"The text shown in compact. {page} and {pages} are replaced with the
current page and the page count.totalnumberDefault0How many items there are across every page.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionfirst-iconThe glyph on the jump-to-first control, usually a double caret.last-iconThe glyph on the jump-to-last control, usually a double caret.next-iconThe glyph on the forward-one-page control, usually a caret.previous-iconThe glyph on the back-one-page control, usually a caret.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the page changes, with the new page as a string in detail.value. In href mode it comes a task after the click, once the page has moved.helix-navigateHelixNavigateEventFired before the page changes, and cancelable. Canceling it is the only way to stop a page change. detail.page is the page asked for, as a number, and detail.value is the same page as a string.
PartDescriptionfirstThe control that jumps to the first page, under ends.gapThe control in place of hidden pages, which jumps into them.itemOne slot in the run, holding a page or a gap.lastThe control that jumps to the last page, under ends.listThe run of pages.liveThe live region that announces a page change. Visually hidden in the styled tier.markThe glyph on a first, previous, next, or last control, where none is slotted.nextThe control that moves forward one page.pageThe control for one page.page-currentThe page you are on, beside page.previousThe control that moves back one page.statusThe text that says which page you are on, in compact.
CSS PropertyDescription--pagination-current-border-colorEdge of the page you are on.--pagination-current-colorFill behind the page you are on.--pagination-current-font-weightWeight of the number of the page you are on.--pagination-current-foreground-colorColor of the number of the page you are on.--pagination-disabled-foreground-colorColor of a first, previous, next or last control with nowhere to go.--pagination-disabled-opacityHow faint a control with nowhere to go is drawn.--pagination-ellipsis-foreground-colorColor of the control that stands in for hidden pages.--pagination-font-sizeSize of the numbers and the status text.--pagination-font-weightWeight of the numbers and the status text.--pagination-foreground-colorColor of the numbers and the marks on every control.--pagination-gapSpace between one control and the next.--pagination-hover-colorFill behind a control under the pointer.--pagination-hover-foreground-colorColor of a control's number or mark under the pointer.--pagination-icon-sizeSize of the mark on a first, previous, next or last control, drawn or slotted.--pagination-paddingSpace either side of a control's number or mark.--pagination-radiusCorner radius of every control in the row.--pagination-sizeThe box every control in the row takes.--pagination-status-foreground-colorColor of the text that says which page you are on, in compact.
Custom stateDescriptionemptyThere is one page or none, so there is nothing to page through.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Sizehelix-pagination-sizeA control for choosing how many items each page shows.
PropTypeDescriptiondefaultValuenumberDefault0The size to start on when value is not set.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.labelstringDefault"Per page"The label beside the control.localestringDefault""The locale the words and the numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.namestringDefault""The name the control's value is submitted under.sizesstringDefault"10,25,50,100"The sizes offered, comma separated.valuenumberThe current page size.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
EventTypeDescriptionchangeEventFired after the size changes.helix-before-changeHelixBeforeChangeEventFired before the size changes, and cancelable. Canceling it is the only way to stop a size change.inputEventFired after the size changes, with change.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptioncontrolThe select.control-feedbackThe message that says what is wrong with the value.control-hintHelp under the trigger.control-indicatorThe caret that shows the control opens.control-labelThe label beside the number.control-listboxThe list inside the panel.control-listbox-emptyThe text shown when the filter hides every option.control-listbox-errorThe inner list's error part, shown while its load-error is set.control-listbox-feedbackThe inner list's message that says what is wrong with the value.control-listbox-filter-iconThe icon beside the filter field.control-listbox-filter-markThe default icon beside the filter field, shown when none is slotted.control-listbox-hintHelp under the list.control-listbox-itemsThe list of options.control-listbox-labelThe label above the list.control-listbox-liveThe inner list's live part, the region screen readers announce its empty and loading text from.control-listbox-loadingThe text shown while the options load.control-listbox-searchThe region that holds the filter field.control-listbox-search-fieldThe filter field.control-liveThe select's live part, the region a screen reader hears a choice made on the closed trigger from.control-surfaceThe floating panel.control-triggerThe closed control, which shows the chosen size.control-valueThe chosen size inside the trigger.optionOne size on offer.option-descriptionThe caption under the number, when there is one.option-itemThe row.option-item-activeThe row the keyboard is on.option-item-selectedThe row of the chosen size.option-labelThe number.option-textThe number and the caption, as one column.
CSS PropertyDescription--pagination-sizeHeight of the select's trigger, the same hook that sizes every control in the page row.--pagination-size-gapSpace between the label and the select.
Custom stateDescriptionemptyWhile there are no sizes to offer.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Summaryhelix-pagination-summaryText that shows which items are on the current page, out of the total.
PropTypeDescriptionformatstringDefault"{from}-{to} of {total}"The text shown. {from}, {to}, and {total} are replaced with the first
item, the last item, and the item count, written in the locale.localestringDefault""The locale the words and the numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.pagenumberDefault1The current page, counting from one.pageSizenumberDefault0How many items are on a page.totalnumberDefault0How many items there are across every page.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
CSS PropertyDescription--pagination-font-sizeSize of the text, the same hook that sizes the page numbers.--pagination-summary-foreground-colorColor of the text.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-paginationControls for moving between the pages of a long set of results.
PropTypeDescriptionboundariesnumberDefault1How many pages to show at each end, whatever the current one is.compactbooleanDefaultfalseReplaces the page numbers with the current page and the page count, as
written by status-label.defaultPagenumberDefault1The page to open on when page is not set.endsbooleanDefaultfalseShows controls that jump to the first and last pages.firstLabelstringDefault"First page"Accessible name for the control that jumps to the first page.gapLabelstringDefault"Skip to page {page}"Accessible name for a gap. {page} is replaced with the page it jumps to.hrefstringDefault""The URL for each page. {page} is replaced with the page number.labelstringDefault"Pagination"Accessible name for the navigation landmark.lastLabelstringDefault"Last page"Accessible name for the control that jumps to the last page.localestringDefault""The locale the words and the page numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.nextLabelstringDefault"Next page"Accessible name for the control that moves forward.pagenumberThe current page, counting from one.pageLabelstringDefault"Page {page}"Accessible name for one page. {page} and {pages} are replaced with the
page number and the page count.pagesnumberDefault0How many pages there are in total.pageSizenumberDefault0How many items are on a page.previousLabelstringDefault"Previous page"Accessible name for the control that moves back.siblingsnumberDefault1How many pages to show either side of the current one.statusLabelstringDefault"{page} of {pages}"The text shown in compact. {page} and {pages} are replaced with the
current page and the page count.totalnumberDefault0How many items there are across every page.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionfirst-iconThe glyph on the jump-to-first control, usually a double caret.last-iconThe glyph on the jump-to-last control, usually a double caret.next-iconThe glyph on the forward-one-page control, usually a caret.previous-iconThe glyph on the back-one-page control, usually a caret.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the page changes, with the new page as a string in detail.value. In href mode it comes a task after the click, once the page has moved.helix-navigateHelixNavigateEventFired before the page changes, and cancelable. Canceling it is the only way to stop a page change. detail.page is the page asked for, as a number, and detail.value is the same page as a string.
PartDescriptionfirstThe control that jumps to the first page, under ends.gapThe control in place of hidden pages, which jumps into them.itemOne slot in the run, holding a page or a gap.lastThe control that jumps to the last page, under ends.listThe run of pages.liveThe live region that announces a page change. Visually hidden in the styled tier.markThe glyph on a first, previous, next, or last control, where none is slotted.nextThe control that moves forward one page.pageThe control for one page.page-currentThe page you are on, beside page.previousThe control that moves back one page.statusThe text that says which page you are on, in compact.
Custom stateDescriptionemptyThere is one page or none, so there is nothing to page through.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Sizehelix-headless-pagination-sizeA control for choosing how many items each page shows.
PropTypeDescriptiondefaultValuenumberDefault0The size to start on when value is not set.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.labelstringDefault"Per page"The label beside the control.localestringDefault""The locale the words and the numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.namestringDefault""The name the control's value is submitted under.sizesstringDefault"10,25,50,100"The sizes offered, comma separated.valuenumberThe current page size.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
EventTypeDescriptionchangeEventFired after the size changes.helix-before-changeHelixBeforeChangeEventFired before the size changes, and cancelable. Canceling it is the only way to stop a size change.inputEventFired after the size changes, with change.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptioncontrolThe select.control-feedbackThe message that says what is wrong with the value.control-hintHelp under the trigger.control-indicatorThe caret that shows the control opens.control-labelThe label beside the number.control-listboxThe list inside the panel.control-listbox-emptyThe text shown when the filter hides every option.control-listbox-errorThe inner list's error part, shown while its load-error is set.control-listbox-feedbackThe inner list's message that says what is wrong with the value.control-listbox-filter-iconThe icon beside the filter field.control-listbox-filter-markThe default icon beside the filter field, shown when none is slotted.control-listbox-hintHelp under the list.control-listbox-itemsThe list of options.control-listbox-labelThe label above the list.control-listbox-liveThe inner list's live part, the region screen readers announce its empty and loading text from.control-listbox-loadingThe text shown while the options load.control-listbox-searchThe region that holds the filter field.control-listbox-search-fieldThe filter field.control-liveThe select's live part, the region a screen reader hears a choice made on the closed trigger from.control-surfaceThe floating panel.control-triggerThe closed control, which shows the chosen size.control-valueThe chosen size inside the trigger.optionOne size on offer.option-descriptionThe caption under the number, when there is one.option-itemThe row.option-item-activeThe row the keyboard is on.option-item-selectedThe row of the chosen size.option-labelThe number.option-textThe number and the caption, as one column.
Custom stateDescriptionemptyWhile there are no sizes to offer.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Summaryhelix-headless-pagination-summaryText that shows which items are on the current page, out of the total.
PropTypeDescriptionformatstringDefault"{from}-{to} of {total}"The text shown. {from}, {to}, and {total} are replaced with the first
item, the last item, and the item count, written in the locale.localestringDefault""The locale the words and the numbers are in, as a BCP 47 tag such as
de. Empty reads the nearest lang, then the browser's language.pagenumberDefault1The current page, counting from one.pageSizenumberDefault0How many items are on a page.totalnumberDefault0How many items there are across every page.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCompactOnly the arrows and a count, for a footer with little room.EventsPaging sends helix-navigate with the page it is going to, because it changes the view and chooses nothing.FooterPagination in a table footer beside a total.Large TotalsA total of 120,000 grouped for the en-GB locale, with a shorter format so the summary stays on one line.LinksPages as links, so each page has a URL you can keep.PreviewNumbered pages with the current one marked.PreviewNumbered pages with the current one marked.Siblings And BoundariesThree settings of siblings and boundaries, which set how many page numbers show beside the current page and at each end.