Guide
Reference
Roadmap
Guide
Reference
Roadmap

usePagingList

Tags:
ProUtilities
DepCollect
This Hook is available since v1.7.0.

A Hook for handling pagination lists that integrates functionalities from useQuery, useForm, useMultiSelect, and usePagination.

It possesses the following features:

  • Based on useQuery, it is built-in with multiple data fetching functionalities, which can be enabled as needed
  • Uses useForm to automatically manage form state, providing various statuses and life cycles, and auto-fetching
  • Uses usePagination to automatically manage pagination state, providing pagination events and operations, built-in state monitoring, and auto-re-fetching
  • Uses useMultiSelect for multiple selection operations on list data, supporting select all, inverse selection, clear, etc.

Scenes

usePagingList = UseQuery features + Pagination state and management + Form querying (optional) + Multiple selection operation (optional)

Demo

Source
Name:
Gender:
Color:
No data
No selected
Total:
10
Current:
1 - 5
Page Size:

Usage

const {
  form, pagination, selection,
  list, refresh, loading
} = usePagingList(options)

// Pass in a function that accepts page, pageSize pagination parameters, it should return a data list
// Use setTotal within this function to set the total number of data, so that the paginator can display the total correctly
const { form, pagination, selection, list, refresh, loading } = usePagingList(
  {
    fetcher: async (payload) => {
      const { page, pageSize, form, setTotal } = payload
      const { list, total } = await fetchPaginationList({ page, pageSize })
      setTotal(total)
      return list
    },
    // Pass in useQuery configuration, such as refreshInterval for timed refresh
    query: { refreshInterval: 3_000 },
    // Pass in useForm configuration, such as initialValues for form initialization
    form: { initialValues: { name: '', select: '' } },
    // Pass in usePagination configuration, such as setting default page number and quantity per page
    pagination: { page: 1, pageSize: 10 },
    // Declare form fields for immediate querying, changes in these fields will automatically trigger querying
    immediateQueryKeys: ['select'],
  },
)

Source

Click links below to view source on GitHub.

🪝 Hook🎨 Demo📄 Document

API

const {
  form, pagination, selection,
  list, refresh, loading
} = usePagingList(options)

Options

export interface UsePagingListOptions<Item, FormState extends object> {
  /**
   * fetcher function that will be called when the query is triggered
   */
  fetcher?: UsePagingListFetcher<Item, FormState>
  /**
   * options for `useForm`, see `useForm` for more details
   *
   * @defaultValue undefined
   */
  form?: UseFormOptions<FormState>
  /**
   * options for `useQuery`, see `useQuery` for more details
   *
   * @defaultValue undefined
   */
  query?: Omit<UseQueryOptions<UsePagingListFetcher<Item, FormState>>, 'initialParams' | 'initialData'>
  /**
   * options for `usePagination`, see `usePagination` for more details
   *
   * @defaultValue undefined
   */
  pagination?: UsePaginationOptions<Item[]>
  /**
   * keys of form state that will trigger a new query when changed
   *
   * @defaultValue []
   */
  immediateQueryKeys?: (keyof FormState)[]
}

export interface UsePagingListFetcherParams<Item, FormState extends object> {
  /**
   * previous data
   */
  previousData: Item[] | undefined
  /**
   * current page
   */
  page: number
  /**
   * page size
   */
  pageSize: number
  /**
   * form state
   */
  form: FormState
  /**
   * set total count
   */
  setTotal: ReactSetState<number>
}

export type UsePagingListFetcher<Item, FormState extends object> = (
  params: UsePagingListFetcherParams<Item, FormState>,
) => Promise<Item[]>

Returns

export interface UsePagingListReturns<Item, FormState extends object>
  extends Pick<
    UseQueryReturns<any, any>,
    'loading' | 'params' | 'error' | 'initializing' | 'refreshing' | 'loadingSlow'
  > {
  /**
   * list data
   */
  list: Item[]
  /**
   * form state
   */
  form: UseFormReturns<FormState>
  /**
   * refresh query
   */
  refresh: () => void
  /**
   * selection state
   */
  selection: UseMultiSelectReturnsState<Item> & UseMultiSelectReturnsActions<Item>
  /**
   * pagination state
   */
  pagination: UsePaginationReturnsState<Item[]> & UsePaginationReturnsActions
}