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

const result = usePagination<TData, TParams>(service, options)

Field	Type	Description
current	Ref<number>	Current page
pageSize	Ref<number>	Items per page
total	Ref<number>	Total items
totalPages	Ref<number>	Total pages
data	ShallowRef<TData | undefined>	Response data (usually containing list and total)
loading	Ref<boolean>	Loading state
refreshing	Ref<boolean>	Refreshing state
loadingMore	Ref<boolean>	Loading more state (used when coordinating with other hooks)
error	ShallowRef<unknown>	Request error
params	Ref<TParams>	Extra request arguments
noMore	Ref<boolean>	Whether there is no more data to load
pagination.loadPage(page)	(page: number) => void	Load specified page
pagination.nextPage()	() => void	Load next page
pagination.prevPage()	() => void	Load previous page
pagination.firstPage()	() => void	Jump to the first page
pagination.lastPage()	() => void	Jump to the last page
pagination.refresh()	() => void	Refresh the current page
pagination.setPageSize(size)	(size: number) => void	Modify page size and refresh automatically (except in manual mode)
pagination.setTotal(total)	(total: number) => void	Set 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:

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").

Related Hooks

• useLoadMore - Infinite scroll / load more
• useQueue - Request queue / concurrency control