Skip to content
Latestv1.0.63

usePagination ​

usePagination is a Hook designed for traditional page-by-page list scenarios, responsible for page numbers, total counts, loading states, and pagination methods, allowing you to focus on rendering the table or list.

Basic Usage ​

usePagination Traditional Pagination

Return Values ​

typescript
const result = usePagination<TData, TParams>(service, options)
FieldTypeDescription
currentRef<number>Current page
pageSizeRef<number>Items per page
totalRef<number>Total items
totalPagesRef<number>Total pages
dataShallowRef<TData | undefined>Response data (usually containing list and total)
loadingRef<boolean>Loading state
refreshingRef<boolean>Refreshing state
loadingMoreRef<boolean>Loading more state (used when coordinating with other hooks)
errorShallowRef<unknown>Request error
paramsRef<TParams>Extra request arguments
noMoreRef<boolean>Whether there is no more data to load
pagination.loadPage(page)(page: number) => voidLoad specified page
pagination.nextPage()() => voidLoad next page
pagination.prevPage()() => voidLoad previous page
pagination.firstPage()() => voidJump to the first page
pagination.lastPage()() => voidJump to the last page
pagination.refresh()() => voidRefresh the current page
pagination.setPageSize(size)(size: number) => voidModify page size and refresh automatically (except in manual mode)
pagination.setTotal(total)(total: number) => voidSet total items count manually

Options ​

The first parameter of usePagination(service, options) is the request function service(page, pageSize, ...args), and the second is the config:

typescript
interface UsePaginationOptions<TData, TParams extends unknown[]> {
  defaultPagination?: PaginationOptions // Default page info { current, pageSize }
  request?: Request // Custom request client
  onSuccess?: (data: TData, params: TParams) => void
  onError?: (error: unknown, params: TParams) => void
  onFinally?: (params: TParams) => void
  manual?: boolean // Whether to manually trigger the first load
  defaultParams?: TParams // Extra request params besides page and pageSize
}

The first two parameters of service are fixed as (current, pageSize). Any subsequent params are supplied via defaultParams or by manually updating params.

Difference from useRequest ​

  • useRequest: General purpose, fits any single-request/debounce/throttle/SWR scenario.
  • usePagination: Specialized in handling traditional page switching layouts (e.g. "List + Pagination controls").

Released under the MIT License.