4.32.2

Pagination

Control for paginating record sets

Demo

API

Tag

Name Description
<s-pagination> Custom Element, no content

Attributes

Name Value Required Description
totalrecords Integer string (e.g. "10" not 10)

Total number of records in record set (or current subset, if full total is not known).
startindex Integer string

Index in record set to start current page, defaults to "0". See below
rowsperpage Integer string

Number of rows per page to display, defaults to "10". Other options are "20", "50", and "100".
rowsperpageoptions Array

Array of option objects, cascades down to s-select element. See the Select page for more information.
hiderowsperpage Boolean attribute

Hides the rowsperpage select and label.
indeterminate Boolean attribute

Indicates that the total number of records is unknown.
disabled Boolean attribute

Disables all interactive parts of the component.
perpagelabel String value

Prefix label for the "rowsperpage" select input. Defaults to "Rows per page".
i18n string

A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name Value Required Description
totalRecords Integer string (e.g. "10" not 10)

Total number of records in record set (or current subset, if full total is not known).
startIndex Integer string

Index in record set to start current page, defaults to "0". See below
rowsPerPage Integer string

Number of rows per page to display, defaults to "10". Other options are "20", "50", and "100".
rowsPerPageOptions Array

Array of option objects, cascades down to s-select element. See the Select page for more information.
hideRowsPerPage Boolean attribute

Hides the rowsperpage select and label.
indeterminate Boolean attribute

Indicates that the total number of records is unknown.
disabled Boolean attribute

Disables all interactive parts of the component.
perPageLabel String value

Prefix label for the "rowsperpage" select input. Defaults to "Rows per page".
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Classes

Name Description
width-md Applies medium viewport width responsive styling.
width-sm Applies small viewport width responsive styling.
width-xs Applies extra small viewport width responsive styling.

Events

Name Detail Description
s-paginate

The current page's startIndex, endIndex, currentPage, rowsPerPage, and flag are available on e.detail.

Fired initially when component is instantiated and then when either attributes are changed or user interacts with pagination controls.

Demo

API

Tag

Name
<SPagination>

Props

Name Value Required Description
totalRecords Integer

Total number of records in record set (or current subset, if full total is not known).
startIndex Integer

Index in record set to start current page, defaults to 0.
rowsPerPage Integer

Number of rows per page to display, defaults to 10. Other options are 20, 50, and 100.
rowsPerPageOptions Array

Array of option objects, cascades down to s-select element. See the Select page for more information.
hideRowsPerPage Boolean

Hides the rowsperpage select and label.
indeterminate Boolean

Indicates that the total number of records is unknown.
disabled Boolean

Disables all interactive parts of the component.
i18n object

A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
onS-paginate Function

Handles the s-paginate event fired in response to pagination events. The current page's startIndex, endIndex, currentPage, and rowsPerPage are available on e.detail

perPageLabel String value

Prefix label for the "rowsperpage" select input. Defaults to "Rows per page".

Classes

Name Description
width-md Applies medium viewport width responsive styling.
width-sm Applies small viewport width responsive styling.
width-xs Applies extra small viewport width responsive styling.

Skylab React links

General information about using our React package

Typescript

Exported types

// s-paginate event's e.detail export type SPaginateData = { startIndex: number; endIndex: number; currentPage: number; rowsPerPage: number; flag: string; };

i18n Strings

ID Description Default value
"pagination.rowsPerPage" The default "rows per page" text. Rows per page
"pagination.page" Part of the "Page {#} of {total-pages}" text. Page
"pagination.of" Part of the "Page {#} of {total-pages}" text. of
"pagination.currentRecordsAnnouncement" Text that desribes the current record range. Must include the strings {START_ROW}, {END_ROW}, and {TOTAL_ROWS} as placeholders. {START_ROW} to {END_ROW} of {TOTAL_ROWS} total rows
"pagination.ariaLabel.firstPage" aria-label for the "first page" icon button. First page
"pagination.ariaLabel.previousGroup" aria-label for the "previous group" icon button. Must include the string {ROWS_PER_PAGE} as a placeholder. Previous group of {ROWS_PER_PAGE} rows
"pagination.ariaLabel.nextGroup" aria-label for the "next group" icon button. Must include the string {ROWS_PER_PAGE} as a placeholder. Next group of {ROWS_PER_PAGE} rows
"pagination.ariaLabel.lastPage" aria-label for the "last page" icon button. Last page

Guidelines

Managing s-paginate events

The design of this component is such that it emits events based on user interaction, but does not actively manage the record set. Rather, the consuming app must listen to the s-paginate events and display the pertinent records accordingly.

The flag property indicates the type of change and the following are valid values:

  • "" (emitted on initialization)
  • "rows-per-page-change"
  • "page-number-change"
  • "first-page"
  • "previous-page"
  • "next-page"
  • "last-page"

Width classes

By default, the Pagination component's responsive design assumes it occupies the full width of the page. However, in cases where the component only spans a portion of the page, the width can be declaratively adjusted using the width-* classes described above.

Programmatically controlling current page

Using the start index, you can update the current page without user interaction. It is a requirement that the start index be a multiple of the rows per page (e.g. "10" or "30" is a valid start index with default 10 rows per page, but "15" is not).

Pairing with a table

One common use case for the Pagination component is with a <table>. Sample usage is shown directly below.

Note: It is strongly advised to use the default perPageLabel and rowsPerPageOptions when paired with a table. This can be achieved by simply omitting the properties from the element declaration.

let recordSet = []; for (let i = 0; i < 155; i++) { recordSet.push([`Row ${i + 1} Data`, `Row ${i + 1} Data`, `Row ${i + 1} Data`, `Row ${i + 1} Data`, `Row ${i + 1} Data`, `Row ${i + 1} Data`, `Row ${i + 1} Data`]) }; // in practice, the JS framework's rendering conventions should be used rather than the declarative browser APIs shown here function renderRows(startIndex, endIndex) { const tbody = document.querySelector('#guidelines-table-body'); tbody.innerHTML = ''; for (let i = startIndex; i < endIndex + 1; i++) { const tr = document.createElement('tr'); const currentRowData = recordSet[i]; for (let j = 0; j < currentRowData.length; j++) { const td = document.createElement('td'); td.innerText = currentRowData[j]; tr.appendChild(td); } tbody.appendChild(tr); } } renderRows(0, 9); // initialize data set document.querySelector("#table-pagination").addEventListener('s-paginate', e => { renderRows(e.detail.startIndex, e.detail.endIndex); });

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com