Async List

A hook for managing asynchronous data operations in list collections including loading, filtering, sorting, and pagination.

The useAsyncList hook manages asynchronous data operations for list collections. It provides a comprehensive solution for loading, filtering, sorting, and paginating data with built-in loading states, error handling, and request cancellation.

import { useAsyncList } from '@ark-ui/react/collection'

const list = useAsyncList<User>({
  async load({ signal }) {
    const response = await fetch('/api/users', { signal })
    const users = await response.json()
    return { items: users }
  },
})

console.log(list.items) // User[]
console.log(list.loading) // boolean
console.log(list.error) // Error | null

Examples

Loading Data

Load data asynchronously from an API using the load function and update the list when the data is ready.

Infinite Loading

Implement pagination by returning a cursor that indicates more data is available.

Filtering

Filter data based on user input with automatic debouncing and loading states.

Sorting (Client-side)

Sort data on the client side after loading from the server.

Sorting (Server-side)

Send sort parameters to the server and reload data when sorting changes.

Dependencies

Automatically reload data when dependencies change, such as filter selections or external state.

API Reference

Props

• load ((params: LoadParams<C>) => Promise<LoadResult<T, C>>) - Function to load data asynchronously
• sort ((params: SortParams<T>) => Promise<SortResult<T>> | SortResult<T>) - Optional function for client-side sorting
• autoReload (boolean, default: false) - Whether to automatically reload data on mount
• initialItems (T[], default: []) - Initial items to display before first load
• dependencies (any[], default: []) - Values that trigger a reload when changed
• initialFilterText (string, default: '') - Initial filter text value
• initialSortDescriptor (SortDescriptor | null) - Initial sort configuration

Load Parameters

The load function receives an object with the following properties:

• cursor (C | undefined) - Current cursor for pagination
• filterText (string) - Current filter text
• sortDescriptor (SortDescriptor | null) - Current sort configuration
• signal (AbortSignal) - AbortController signal for request cancellation

Load Result

The load function should return an object with:

• items (T[]) - The loaded items
• cursor (C | undefined) - Optional cursor for next page

Sort Parameters

The sort function receives an object with:

• items (T[]) - Current items to sort
• descriptor (SortDescriptor) - Sort configuration with column and direction

Return Value

The hook returns an object with the following properties and methods:

State Properties

• items (T[]) - Current list of items
• loading (boolean) - Whether a load operation is in progress
• error (Error | null) - Any error from the last operation
• cursor (C | undefined) - Current cursor for pagination
• filterText (string) - Current filter text
• sortDescriptor (SortDescriptor | null) - Current sort configuration

Methods

• reload (() => void) - Reload data from the beginning
• loadMore (() => void) - Load more items (when cursor is available)
• setFilterText ((text: string) => void) - Set filter text and reload
• sort ((descriptor: SortDescriptor) => void) - Apply sorting

Types

interface SortDescriptor {
  column: string
  direction: 'ascending' | 'descending'
}

interface LoadParams<C> {
  cursor?: C
  filterText: string
  sortDescriptor?: SortDescriptor | null
  signal: AbortSignal
}

interface LoadResult<T, C> {
  items: T[]
  cursor?: C
}