usePagingList

Tags:

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

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 (params) => {
      const { page, pageSize, form } = params
      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 UsePagingListFetcherParams<FormState extends object, Data> {
  /**
   * Data from the last request
   */
  previousData: Data | undefined
  /**
   * Current page number
   */
  page: number
  /**
   * Quantity per page
   */
  pageSize: number
  /**
   * Form state
   */
  form: FormState
  /**
   * Set the total number of data
   */
  setTotal: ReactSetState<number>
}

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

export interface UsePagingListOptions<Fetcher extends AnyFunc, FormState extends object> {
  /**
   * Data fetcher function
   */
  fetcher?: Fetcher
  /**
   * `useForm` configuration, see useForm documentation
   *
   * @defaultValue undefined
   */
  form?: UseFormOptions<FormState>
  /**
   * `useQuery` configuration, see `useQuery` documentation
   *
   * @defaultValue undefined
   */
  query?: Omit<UseQueryOptions<Fetcher>, 'initialParams' | 'initialData'>
  /**
   * `usePagination` configuration, see `usePagination` documentation
   *
   * @defaultValue undefined
   */
  pagination?: UsePaginationOptions<ReturnType<Fetcher>>
  /**
   * Form fields for immediate querying, changes in these fields will automatically trigger querying
   *
   * @defaultValue []
   */
  immediateQueryKeys?: (keyof FormState)[]
}

Returns

export interface UsePagingListReturns<
  Item,
  FormState extends object,
  Data extends Item[],
  Fetcher extends UsePagingListFetcher<FormState, Data>,
> {
  /**
   * Whether it is loading
   */
  loading: boolean
  /**
   * Data list
   */
  list: Data
  /**
   * Form instance, see useForm documentation
   */
  form: UseFormReturns<FormState>
  /**
   * Refresh data using the last request parameters (form state, etc.)
   */
  refresh: () => void
  /**
   * Selection status and operations, see useMultiSelect documentation
   */
  selection: UseMultiSelectReturnsState<Item> & UseMultiSelectReturns<Item>
  /**
   * Pagination status and operations, see usePagination documentation
   */
  pagination: UsePaginationReturnsState<Data> & UsePaginationReturnsActions
}

#usePagingList

#Scenes

#Demo

#Usage

#Source

#API

#Options

#Returns