Skip to main content
useList is a modified version of TanStack Query’s useQuery for retrieving items from a resource with pagination, sorting, and filtering. It uses the getList method from the dataProvider.

​
Usage

import { useList } from "@refinedev/core";

interface IProduct {
  id: number;
  name: string;
  price: number;
  category: string;
}

const productList = useList<IProduct>({
  resource: "products",
  pagination: {
    current: 1,
    pageSize: 10,
  },
  sorters: [
    {
      field: "createdAt",
      order: "desc",
    },
  ],
  filters: [
    {
      field: "category",
      operator: "eq",
      value: "electronics",
    },
  ],
});

​
Parameters

​
resource
string
Resource name for API data interactions. If not provided, it will be inferred from the route.
​
pagination
Pagination
Pagination configuration for the query.
​
sorters
CrudSort[]
Sorter parameters for ordering results.
​
filters
CrudFilter[]
Filter parameters for narrowing down results.
​
meta
MetaQuery
Meta data for the dataProvider. Can be used to pass additional parameters to data provider methods.
​
dataProviderName
string
If there is more than one dataProvider, you should specify which one to use.
​
queryOptions
UseQueryOptions
TanStack Query’s useQuery options.
​
successNotification
OpenNotificationParams | false | ((data, params) => OpenNotificationParams | false)
Success notification configuration. Set to false to disable.
​
errorNotification
OpenNotificationParams | false | ((error, params) => OpenNotificationParams | false)
Error notification configuration. Set to false to disable.
​
liveMode
'auto' | 'manual' | 'off'
Live/Realtime mode configuration.
​
onLiveEvent
(event) => void
Callback to handle live events.
​
liveParams
object
Additional parameters for live queries.
​
overtimeOptions
UseLoadingOvertimeOptionsProps
Configuration for loading overtime behavior.

​
Return Values

​
result
object
Simplified result object.
​
query
QueryObserverResult
TanStack Query’s useQuery return object.
​
overtime
object
Loading overtime information.

​
Examples

​
Basic Usage

import { useList } from "@refinedev/core";

const { result, query } = useList({
  resource: "posts",
});

const posts = result.data;
const total = result.total;

​
With Pagination

const { result } = useList({
  resource: "posts",
  pagination: {
    currentPage: 2,
    pageSize: 20,
  },
});

​
With Sorting

const { result } = useList({
  resource: "posts",
  sorters: [
    {
      field: "createdAt",
      order: "desc",
    },
    {
      field: "title",
      order: "asc",
    },
  ],
});

​
With Filters

const { result } = useList({
  resource: "posts",
  filters: [
    {
      field: "status",
      operator: "eq",
      value: "published",
    },
    {
      field: "category.id",
      operator: "in",
      value: [1, 2, 3],
    },
  ],
});

​
With Complex Filters (OR/AND)

const { result } = useList({
  resource: "posts",
  filters: [
    {
      operator: "or",
      value: [
        {
          field: "status",
          operator: "eq",
          value: "published",
        },
        {
          field: "status",
          operator: "eq",
          value: "draft",
        },
      ],
    },
  ],
});

​
Client-Side Pagination

const { result } = useList({
  resource: "posts",
  pagination: {
    mode: "client",
    currentPage: 1,
    pageSize: 10,
  },
});

​
With Query Options

const { result } = useList({
  resource: "posts",
  queryOptions: {
    enabled: true,
    staleTime: 5 * 60 * 1000, // 5 minutes
    select: (data) => ({
      ...data,
      data: data.data.map((post) => ({
        ...post,
        title: post.title.toUpperCase(),
      })),
    }),
  },
});

​
Type Parameters

  • TQueryFnData - Result data type returned by the query function. Extends BaseRecord.
  • TError - Custom error type that extends HttpError.
  • TData - Result data type returned by the select function. Extends BaseRecord. Defaults to TQueryFnData.

​
FAQ

Use the queryOptions.enabled parameter:
const { result } = useList({
  resource: "posts",
  queryOptions: {
    enabled: false,
  },
});
Use the queryOptions.select parameter:
const { result } = useList({
  resource: "posts",
  queryOptions: {
    select: (data) => ({
      ...data,
      data: data.data.filter(post => post.status === 'published'),
    }),
  },
});
  • isLoading is true only on the initial load (when there’s no cached data)
  • isFetching is true whenever data is being fetched, including refetches

Build docs developers (and LLMs) love

Get started for freeTalk to us