Pagination

What is this?

Pagination triggers allow merchants to view the size of a list and navigate between pages.

Loading

Loading...

Query string pagination

You can persist the pagination state within the browser's query params using the useQueryPaginationState hook, instead of usePaginationState. Both hooks are used in the same way. The application should be wrapped by QueryStateProvider.

Watch how your url changes.

Loading...

Actions

Loading...

caution

Be careful when using the setTotal action, because if you set the total to a smaller value it may lead your current page to an invalid one.

Internationalization

Loading...

Usage

import { Pagination, usePaginationState } from '@vtex/admin-ui'

function Example() {
  const state = usePaginationState({ pageSize: 5, total: 35 })

  return <Pagination state={state} />
}

Props

Name	Type	Description	Required	Default
state	UsePaginationReturn	Component State	✅	-
loading	boolean	Whether the table is loading or not	🚫	false

State

The pagination state object is composed of the currentPage prop and the range prop. The currentPage represents the current page as the name says, and the range is an array that contains two numbers with the first and the last items positions of the current page.

usePaginationState parameters

Name	Type	Description	Required	Default
pageSize	number	Amount of items that will be displayed in a page	✅	-
total	number	Total amount of items in a collection	🚫	pageSize value
stateReducer	(state: PaginationState, action: PaginationAction) => PaginationState	Optional way to provide a function to be used inside usePagination hook useReducer	🚫	usePagination hook default reducer
initialPage	number	The initial state of pagination	🚫	1

useQueryPaginationState parameters

Name	Type	Description	Required	Default
pageSize	number	Amount of items that will be displayed in a page	✅	-
total	number	Total amount of items in a collection	🚫	pageSize value
stateReducer	(state: PaginationState, action: PaginationAction) => PaginationState	Optional way to provide a function to be used inside usePagination hook useReducer	🚫	usePagination hook default reducer

UsePaginationReturn

This represents the type of the props returned by both usePaginationState and useQueryPaginationState.

Name	Type	Description	Required	Default
numberOfPages	number	The total number of pages	✅	-
currentPage	number	The current page state	✅	-
range	[number, number]	It represents the positions of the first and last items in the page	✅	-
total	number	It represents the total number of items	✅	-
prevDisabled	boolean	Whether the navigation to the previous page is disabled or not	✅	-
nextDisabled	boolean	Whether the navigation to the next page is disabled or not	✅	-
paginate	(args: PaginationActionType) => void	The initial state of pagination	✅	-

PaginationActionType

export type PaginationActionType =
  | {
      type: 'next' | 'prev' | 'reset'
    }
  | {
      type: 'setTotal'
      total: number
    }
  | {
      type: 'navigate'
      page: number
    }

Components

When to use the Pagination component or infinite scroll?

Use Pagination when a list can have more than 25 results. Infinite scroll is not recommended in any scenario.

Position

Where should Pagination be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

• Pagination should always be in the top right of a container.
• If the list has a vertical scroll, the Pagination should also be in the bottom right.
• Use the DataView component to correctly position the Pagination.

What to avoid:

• Don’t position the Pagination in the header of a container.

Behavior

How many items should be shown per page of a list?

• The standard is to show 25 items per page of a list.
• When the list is inside a container where vertical scroll should be avoided, such as a Modal or a Card, limit the amount of items accordingly.

What to avoid:

• Don’t allow merchants to customize the number of results per page.

When to show a loading Pagination?

When the list is loading, since the number of results is not loaded and the user can’t navigate between pages yet.

When should the items in a list be updated?

• Only show new items when the user explicitly triggers an action to update the results, such as the Refresh button in the web browser.
• When the user has just created an item and returns to the listing page, they should go to the first page with updated results.
• When the user has just edited an item and returns to the listing page, they should see a list with the same items as before, but with the edited item updated.

What to avoid:

• Don’t update the number of results while the merchant is navigating between pages.

When should the current state of a list be stored in the URL?

The complete search query, which includes the filters, the current page and the search terms, should be reflected in the URL. This allows the merchant to easily return to the customized view and easily share it.

What to avoid:

• Don’t use local storage or cookies to store the query.

• What is this?
• Loading
• Query string pagination
• Actions
• Internationalization