Skip to main content

Table pagination

TablePagination divides and displays a large number of results across multiple pages. It contains a variety of navigation options that help present the content users require in a digestible way.

Source@atlas-ui/paginationFigmaDesign guidelines

Import​

import {
  TablePagination,
  TablePaginationSelect,
  TablePaginationSelectLabel,
  TablePaginationSelectInput,
  TablePaginationControls,
  TablePaginationControlsLabel,
  TablePaginationPreviousButton,
  TablePaginationNextButton,
} from "@atlas-ui/react";
  • TablePagination: Wrapper component for pagination.
  • TablePaginationSelect: Wrapper component for the select section.
  • TablePaginationSelectLabel: Label for the select section.
  • TablePaginationSelectInput: Dropdown to select the number of items on a page.
  • TablePaginationControls: Wrapper component for the TablePaginationControlsLabel, TablePaginationNextButton and TablePaginationPreviousButton components.
  • TablePaginationControlsLabel: Displays the number of items on the current page and total number of pages. e.g. 1 - 20 of 100.
  • TablePaginationNextButton: Button to navigate to the next page.
  • TablePaginationPreviousButton: Button to navigate to the previous page.

Usage​

Basic​

TablePagination is the overall container for the sub-components. TablePaginationSelect wraps the select subcomponents. TablePaginationSelectLabel is the string label for the select. TablePaginationSelectInput accepts a function that is called when the page size is changed which determines the content of the label that is rendered by TablePaginationControlsLabel.

TablePaginationControls wraps the TablePaginationControlsLabel, TablePaginationPreviousButton and TablePaginationNextButton components. TablePaginationControlsLabel displays the number of items on the current page and total number of pages. TablePaginationPreviousButton and TablePaginationNextButton both accept a function that navigates through the pages in the table.

Options​

Default​

Loading...
function Example() {
  return (
    <TablePagination
     itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultItemsPerPage={20}
      defaultPageIndex={0}
      totalItems={100}
    >
     <TablePaginationSelect>
          <TablePaginationSelectLabel />
          <TablePaginationSelectInput />
        </TablePaginationSelect>
        <TablePaginationControls>
          <TablePaginationControlsLabel />
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Disabled​

All components can be disabled by setting the isDisabled prop to true.

Loading...
function Example() {


  return (
    <TablePagination
      isDisabled
      itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultItemsPerPage={20}
      defaultPageIndex={0}
      totalItems={100}
    >
      <TablePaginationSelect>
          <TablePaginationSelectLabel />
          <TablePaginationSelectInput />
        </TablePaginationSelect>
        <TablePaginationControls>
          <TablePaginationControlsLabel />
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

No default page size​

It is not necessary to set a default page size. If no default page size is set, the first option in the defaultItemsPerPage array will be used.

Loading...
function Example() {
  return (
    <TablePagination
       itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultPageIndex={0}
      totalItems={100}
    >
     <TablePaginationSelect>
          <TablePaginationSelectLabel />
          <TablePaginationSelectInput />
        </TablePaginationSelect>
        <TablePaginationControls>
          <TablePaginationControlsLabel />
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Without select​

The TablePaginationSelect component can be removed if the select is not required.

Loading...
function Example() {
  return (
    <TablePagination
    defaultItemsPerPage={20}
    defaultPageIndex={0}
    totalItems={100}
    >
      <TablePaginationControls>
          <TablePaginationControlsLabel />
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Select disabled​

In order to disable the TablePaginationSelect component, use isDisabled in the Table pagination select component.

Loading...
function Example() {
  return (
    <TablePagination
      itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultPageIndex={20}
      totalItems={100}>
    <TablePaginationSelect isDisabled>
          <TablePaginationSelectLabel />
          <TablePaginationSelectInput />
        </TablePaginationSelect>
        <TablePaginationControls>
          <TablePaginationControlsLabel />
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Controlled state​

The value of the pageIndex and pageSize can be controlled programmatically with the pageSize & pageIndex props.

Loading...
function Example() {
  const [pageIndex, setPageIndex] = React.useState(0);
  const [itemsPerPage, setItemsPerPage] = React.useState(20);
  const totalItems = 100;

  const handleNext = () => {
    setPageIndex((prevPageIndex) => prevPageIndex + 1);
  };

  const handlePrevious = () => {
    setPageIndex((prevPageIndex) => prevPageIndex - 1);
  };


  const handleItemsPerPageChange = (newItemsPerPage) => {
    setItemsPerPage(newItemsPerPage);
    const numberOfPages = Math.ceil(totalItems / newItemsPerPage);
    if (pageIndex + 1 > numberOfPages) {
      setPageIndex(0);
    }
  };

  return (
    <TablePagination
      itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      onItemsPerPageChange={handleItemsPerPageChange}
      pageIndex={pageIndex}
      itemsPerPage={itemsPerPage}
      totalItems={totalItems}
    >
      <TablePaginationSelect>
        <TablePaginationSelectLabel />
        <TablePaginationSelectInput />
      </TablePaginationSelect>
      <TablePaginationControls>
         <TablePaginationControlsLabel />
        <TablePaginationPreviousButton onPress={handlePrevious} />
        <TablePaginationNextButton onPress={handleNext} />
      </TablePaginationControls>
    </TablePagination>
  );
}
Editable example

Modifying the TablePaginationControlsLabel​

The TablePaginationControlsLabel can be modified by creating a label with firstItem, lastItem and totalItems and creating a string label from instead of the default label structure of 1 - 20 of 100.

Loading...
function Example() {
  const label = ({ firstItem, lastItem, totalItems }) => {
    return `${firstItem} to ${lastItem} of ${totalItems}`;
  };

  return (
    <TablePagination
      itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultPageIndex={20}
      totalItems={100}>
    <TablePaginationSelect>
          <TablePaginationSelectLabel />
          <TablePaginationSelectInput />
        </TablePaginationSelect>
        <TablePaginationControls>
          <TablePaginationControlsLabel>{label}</TablePaginationControlsLabel>
          <TablePaginationPreviousButton />
          <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Modifying the TablePaginationSelectLabel​

The TablePaginationSelectLabel can be modified by passing a child string to the TablePaginationSelectLabel component.

Loading...
function Example() {
  return (
    <TablePagination
      itemsPerPageOptions={[
        { label: "10", value: 10 },
        { label: "20", value: 20 },
        { label: "50", value: 50 },
        { label: "100", value: 100 },
      ]}
      defaultPageIndex={20}
      totalItems={100}>
      <TablePaginationSelect>
        <TablePaginationSelectLabel>Items per page</TablePaginationSelectLabel>
        <TablePaginationSelectInput />
      </TablePaginationSelect>
      <TablePaginationControls>
        <TablePaginationControlsLabel/>
        <TablePaginationPreviousButton />
        <TablePaginationNextButton />
        </TablePaginationControls>
      </TablePagination>
  );
}
Editable example

Props​

Pagination Props
PropDefaultType
children
*
-ReactNode
The content of the pagination component
isDisabled
-boolean
If the pagination is disabled
pageIndex
-number
The index of the current page
itemsPerPageOptions
*
-ItemsPerPageOption[]
The available options for items per page to be displayed in the PaginationSelect component.
defaultItemsPerPage
-number
Default page size for the pagination
totalItems
*
-number
The total number of items
itemsPerPage
-number
The number of items per page
onPageIndexChange
-(pageIndex: number) => void
Callback when the index of the current page changes
onItemsPerPageChange
-(itemsPerPage: number) => void
Callback when the number of items per page changes
defaultPageIndex
-number
The default page index

PaginationSelect Props
PropDefaultType
ref
-Ref<HTMLDivElement>
isDisabled
-boolean

PaginationSelectInput Props
PropDefaultType
getOptionLabel
-(option: ItemsPerPageOption) => string | ReactElement<any, string | JSXElementConstructor<any>>
formatOptionLabel
-(option: ItemsPerPageOption, formatOptionLabelMeta: FormatOptionLabelMeta<ItemsPerPageOption>) => string | ReactElement<...>
components
-Partial<SelectComponents<ItemsPerPageOption, false, GroupBase<ItemsPerPageOption>>>
This complex object includes all the compositional components that are used in `react-select`. If you wish to overwrite a component, pass in an object with the appropriate namespace. If you only wish to restyle a component, we recommend using the `styles` prop instead.
formatGroupLabel
-(group: GroupBase<ItemsPerPageOption>) => ReactNode
Formats group labels in the menu as React components
isOptionDisabled
-(option: ItemsPerPageOption, selectValue: Options<ItemsPerPageOption>) => boolean
Override the built-in logic to detect whether an option is disabled
menuPortalTarget
-HTMLElement
Whether the menu should use a portal, and where it should attach
styles
-StylesConfig<ItemsPerPageOption, false, GroupBase<ItemsPerPageOption>>
Style modifier methods
form
-string
Sets the form attribute on the input
option
-ItemsPerPageOption
defaultValue
-PropsValue<ItemsPerPageOption>
autoFocus
-boolean
Focus the control when it is mounted
className
-string
Sets a className attribute on the outer component
id
-string
The id to set on the SelectContainer component.
tabIndex
-number
Sets the tabIndex attribute on the input
aria-errormessage
-string
HTML ID of an element containing an error message related to the input*
aria-label
-string
Aria label (for assistive tech)
aria-labelledby
-string
HTML ID of an element that should be used as the label (for assistive tech)
aria-live
-"off""assertive""polite"
Used to set the priority with which screen reader should treat updates to live regions. The possible settings are: off, polite (default) or assertive
onFocus
-FocusEventHandler<HTMLInputElement>
Handle focus events on the control
onBlur
-FocusEventHandler<HTMLInputElement>
Handle blur events on the control
onChange
-(newValue: ItemsPerPageOption, actionMeta: ActionMeta<ItemsPerPageOption>) => void
Handle change events on the select
onKeyDown
-KeyboardEventHandler<HTMLDivElement>
Handle key down events on the select
group
-GroupBase<ItemsPerPageOption>
theme
-ThemeConfig
Theme modifier method
isDisabled
-boolean
Is the select disabled
name
-string
Name of the HTML Input (optional - without this, no input will be rendered)
value
-PropsValue<ItemsPerPageOption>
The value of the select; reflected by the selected option
isInvalid
-boolean
placeholder
-ReactNode
Placeholder for the select value
required
-boolean
Marks the value-holding input as required for form validation
ariaLiveMessages
-AriaLiveMessages<ItemsPerPageOption, false, GroupBase<ItemsPerPageOption>>
Customise the messages used by the aria-live component
backspaceRemovesValue
-boolean
Remove the currently focused option when the user presses backspace when Select isClearable or isMulti
blurInputOnSelect
-boolean
Remove focus from the input when the user selects an option (handy for dismissing the keyboard on touch devices)
captureMenuScroll
-boolean
When the user reaches the top/bottom of the menu, prevent scroll on the scroll-parent
classNamePrefix
-string
If provided, all inner components will be given a prefixed className attribute. This is useful when styling via CSS classes instead of the Styles API approach.
classNames
-ClassNamesConfig<ItemsPerPageOption, false, GroupBase<ItemsPerPageOption>>
Provide classNames based on state for each inner component
closeMenuOnSelect
-boolean
Close the select menu when the user selects an option
closeMenuOnScroll
-boolean | ((event: Event) => boolean)
If `true`, close the select menu when the user scrolls the document/body. If a function, takes a standard javascript `ScrollEvent` you return a boolean: `true` => The menu closes `false` => The menu stays open This is useful when you have a scrollable modal and want to portal the menu out, but want to avoid graphical issues.
controlShouldRenderValue
-boolean
Whether the value of the select, e.g. SingleValue, should be displayed in the control.
delimiter
-string
Delimiter used to join multiple values into a single HTML Input value
escapeClearsValue
-boolean
Clear all values when the user presses escape AND the menu is closed
filterOption
-(option: FilterOptionOption<ItemsPerPageOption>, inputValue: string) => boolean
Custom method to filter whether an option should be displayed in the menu
getOptionValue
-GetOptionValue<ItemsPerPageOption>
Resolves option data to a string to compare options and specify value attributes
hideSelectedOptions
-boolean
Hide the selected option from the menu
inputValue
-string
The value of the search input
inputId
-string
The id of the search input
instanceId
-string | number
Define an id prefix for the select components e.g. {your-id}-value
isClearable
-boolean
Is the select value clearable
isLoading
-boolean
Is the select in a state of loading (async)
isOptionSelected
-(option: ItemsPerPageOption, selectValue: Options<ItemsPerPageOption>) => boolean
Override the built-in logic to detect whether an option is selected
isMulti
-false
Support multiple selected options
isRtl
-boolean
Is the select direction right-to-left
isSearchable
-boolean
Whether to enable search functionality
loadingMessage
-(obj: { inputValue: string; }) => ReactNode
Async: Text to display when loading options
minMenuHeight
-number
Minimum height of the menu before flipping
maxMenuHeight
-number
Maximum height of the menu before scrolling
menuIsOpen
-boolean
Whether the menu is open
menuPlacement
-"top""bottom""auto"
Default placement of the menu in relation to the control. 'auto' will flip when there isn't enough space below the control.
menuPosition
-"fixed""absolute"
The CSS position value of the menu, when "fixed" extra layout management is required
menuShouldBlockScroll
-boolean
Whether to block scroll events when the menu is open
menuShouldScrollIntoView
-boolean
Whether the menu should be scrolled into view when it opens
noOptionsMessage
-(obj: { inputValue: string; }) => ReactNode
Text to display when there are no options
onInputChange
-(newValue: string, actionMeta: InputActionMeta) => void
Handle change events on the input
onMenuOpen
-() => void
Handle the menu opening
onMenuClose
-() => void
Handle the menu closing
onMenuScrollToTop
-(event: TouchEvent | WheelEvent) => void
Fired when the user scrolls to the top of the menu
onMenuScrollToBottom
-(event: TouchEvent | WheelEvent) => void
Fired when the user scrolls to the bottom of the menu
openMenuOnFocus
-boolean
Allows control of whether the menu is opened when the Select is focused
openMenuOnClick
-boolean
Allows control of whether the menu is opened when the Select is clicked
options
-OptionsOrGroups<ItemsPerPageOption, GroupBase<ItemsPerPageOption>>
Array of options that populate the select menu
pageSize
-number
Number of options to jump in menu when page{up|down} keys are used
screenReaderStatus
-(obj: { count: number; }) => string
Status to relay to screen readers
tabSelectsValue
-boolean
Select the currently focused option when the user presses tab
unstyled
-boolean
Remove all non-essential styles
displayMode
-DisplayMode<ItemsPerPageOption>
startIcon
-ReactNode
endIcon
-ReactNode
hideDropdownIcon
-boolean
getOptionDescription
-(option: ItemsPerPageOption) => string
getOptionStartIcon
-(option: ItemsPerPageOption) => ReactNode
getOptionEndIcon
-(option: ItemsPerPageOption) => ReactNode
isOptionInvalid
-(option: ItemsPerPageOption) => boolean
showGroupDividers
-boolean
headerMenuList
-ReactNode
footerMenuList
-ReactNode
defaultInputValue
-string
defaultMenuIsOpen
-boolean

PaginationNextButton Props
PropDefaultType
autoFocus
-boolean
Whether the element should receive focus on render.
id
-string
The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
rel
-string
The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
aria-controls
-string
Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-describedby
-string
Identifies the element (or elements) that describes the object.
aria-details
-string
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-expanded
-boolean | "true" | "false"
Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopup
-boolean | "dialog" | "menu" | "true" | "false" | "grid" | "listbox" | "tree"
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-label
-string
Defines a string value that labels the current element.
aria-labelledby
-string
Identifies the element (or elements) that labels the current element.
aria-pressed
-boolean | "true" | "false" | "mixed"
Indicates the current "pressed" state of toggle buttons.
onFocus
-(e: FocusEvent<Element, Element>) => void
Handler that is called when the element receives focus.
onBlur
-(e: FocusEvent<Element, Element>) => void
Handler that is called when the element loses focus.
onKeyDown
-(e: KeyboardEvent) => void
Handler that is called when a key is pressed.
onKeyUp
-(e: KeyboardEvent) => void
Handler that is called when a key is released.
as
-ElementType
The HTML element or React element used to render the button, e.g. 'div', 'a', or RouterLink.
size
-"small""large""medium"
Defines the size of the button.
isDisabled
-boolean
Whether the button is disabled.
onPress
-(e: PressEvent) => void
Handler that is called when the press is released over the target.
onPressStart
-(e: PressEvent) => void
Handler that is called when a press interaction starts.
onPressEnd
-(e: PressEvent) => void
Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange
-(isPressed: boolean) => void
Handler that is called when the press state changes.
onPressUp
-(e: PressEvent) => void
Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocusChange
-(isFocused: boolean) => void
Handler that is called when the element's focus status changes.
href
-string
A URL to link to if elementType="a".
target
-string
The target window for the link.
type
"'button'""button""submit""reset"
The behavior of the button when used in an HTML form.
preventFocusOnPress
-boolean
Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
excludeFromTabOrder
-boolean
Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
appearance
-"primary""secondary""tertiary""secondaryReverse""primaryReverse""destructive""primaryLink""secondaryLink"
Defines the appearance of the button.
startIcon
-ReactElement<any, string | JSXElementConstructor<any>>
Defines the icon to display at the start of the content.
endIcon
-ReactElement<any, string | JSXElementConstructor<any>>
Defines the icon to display at the end of the content.

PaginationPreviousButton Props
PropDefaultType
autoFocus
-boolean
Whether the element should receive focus on render.
id
-string
The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
rel
-string
The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
aria-controls
-string
Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-describedby
-string
Identifies the element (or elements) that describes the object.
aria-details
-string
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-expanded
-boolean | "true" | "false"
Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopup
-boolean | "dialog" | "menu" | "true" | "false" | "grid" | "listbox" | "tree"
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-label
-string
Defines a string value that labels the current element.
aria-labelledby
-string
Identifies the element (or elements) that labels the current element.
aria-pressed
-boolean | "true" | "false" | "mixed"
Indicates the current "pressed" state of toggle buttons.
onFocus
-(e: FocusEvent<Element, Element>) => void
Handler that is called when the element receives focus.
onBlur
-(e: FocusEvent<Element, Element>) => void
Handler that is called when the element loses focus.
onKeyDown
-(e: KeyboardEvent) => void
Handler that is called when a key is pressed.
onKeyUp
-(e: KeyboardEvent) => void
Handler that is called when a key is released.
as
-ElementType
The HTML element or React element used to render the button, e.g. 'div', 'a', or RouterLink.
size
-"small""large""medium"
Defines the size of the button.
isDisabled
-boolean
Whether the button is disabled.
onPress
-(e: PressEvent) => void
Handler that is called when the press is released over the target.
onPressStart
-(e: PressEvent) => void
Handler that is called when a press interaction starts.
onPressEnd
-(e: PressEvent) => void
Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange
-(isPressed: boolean) => void
Handler that is called when the press state changes.
onPressUp
-(e: PressEvent) => void
Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocusChange
-(isFocused: boolean) => void
Handler that is called when the element's focus status changes.
href
-string
A URL to link to if elementType="a".
target
-string
The target window for the link.
type
"'button'""button""submit""reset"
The behavior of the button when used in an HTML form.
preventFocusOnPress
-boolean
Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
excludeFromTabOrder
-boolean
Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
appearance
-"primary""secondary""tertiary""secondaryReverse""primaryReverse""destructive""primaryLink""secondaryLink"
Defines the appearance of the button.
startIcon
-ReactElement<any, string | JSXElementConstructor<any>>
Defines the icon to display at the start of the content.
endIcon
-ReactElement<any, string | JSXElementConstructor<any>>
Defines the icon to display at the end of the content.