useList

useList is a modified version of react-query's useQuery used for retrieving items from a resource with pagination, sort, and filter configurations.

It uses the getList method as the query function from the dataProvider which is passed to <Refine>.

Usage

Let's say that we have a resource named posts

https://api.fake-rest.refine.dev/posts

{
    [
        {
            id: 1,
            title: "E-business",
            status: "draft",
        },
        {
            id: 2,
            title: "Virtual Invoice Avon",
            status: "published",
        },
        {
            id: 3,
            title: "Powerful Crypto",
            status: "rejected",
        },
    ];
}

useList passes the query configuration to getList method from the dataProvider. We will be using the dataProvider from @pankod/refine-simple-rest

First of all, we will use useList without passing any query configurations.

import { useList } from "@pankod/refine";

type IPost = {
    id: string;
    title: string;
    status: "rejected" | "published" | "draft";
};

const postListQueryResult = useList<IPost>({ resource: "posts" });

postListQueryResult.data

{
    data: [
        {
            id: 3,
            title: "Powerful Crypto",
            status: "rejected"
        },
        {
            id: 2,
            title: "Virtual Invoice Avon",
            status: "published"
        },
        {
            id: 1,
            title: "E-business",
            status: "draft"
        },
    ],
    total: 3
}

Although we didn't pass any sort order configurations to useList, data comes in descending order according to id since getList has default values for sort order:

{
    sort: [{ order: "desc", field: "id" }];
}

info

getList also has default values for pagination:

{
    pagination: { current: 1, pageSize: 10 }
}

caution

If you want to create your own getList method, it will automatically implement default query configurations since useList can work with no configuration parameters.

Query Configuration

pagination

Allows us to set page and items per page values.

For example imagine that we have 1000 post records:

import { useList } from "@pankod/refine";

const postListQueryResult = useList<IPost>({
    resource: "posts",
    config: {
        pagination: { current: 3, pageSize: 8 },
    },
});

Listing will start from page 3 showing 8 records.

sort

Allows us to sort records by the speficified order and field.

import { useList } from "@pankod/refine";

const postListQueryResult = useList<IPost>({
    resource: "posts",
    config: {
        sort: [{ order: "asc", field: "title" }],
    },
});

postListQueryResult.data

{
    data: [
        {
            id: 1,
            title: "E-business",
            status: "draft"
        },
        {
            id: 3,
            title: "Powerful Crypto",
            status: "rejected"
        },
        {
            id: 2,
            title: "Virtual Invoice Avon",
            status: "published"
        },
    ],
    total: 3
}

Listing starts from ascending alphabetical order on the title field.

filters

Allows us to filter queries using refine's filter operators. It is configured via field, operator and value properites.

import { useList } from "@pankod/refine";

const postListQueryResult = useList<IPost>({
    resource: "posts",
    config: {
        filters: [
            {
                field: "status",
                operator: "eq",
                value: "rejected",
            },
        ],
    },
});

postListQueryResult.data

{
    data: [
        {
            id: 3,
            title: "Powerful Crypto",
            status: "rejected"
        },
    ],
    total: 1
}

Only lists records whose status equals to "rejected".

Supported operators

Filter	Description
eq	Equal
ne	Not equal
lt	Less than
gt	Greater than
lte	Less than or equal to
gte	Greater than or equal to
in	Included in an array
nin	Not included in an array
contains	Contains
ncontains	Doesn't contain
containss	Contains, case sensitive
ncontainss	Doesn't contain, case sensitive
null	Is null or not null

tip

useList can also accept all useQuery options as a third parameter.
Refer to react-query docs for further information. →

• For example, to disable query from running automatically you can set enabled to false.

import { useList } from "@pankod/refine";

const postListQueryResult = useList<IPost>({
    resource: "posts",
    queryOptions: { enabled: false },
});

tip

useList returns the result of react-query's useQuery which includes many properties such as isLoading and isFetching. Refer to react-query docs for further information. →

API

Properties

Property	Description	Type
resource Required	Resource name for API data interactions	string
config	Configuration for pagination, sorting and filtering	UseListConfig
queryOptions	react-query's useQuery options	UseQueryOptions< { data: TData[]; }, TError>
successNotification	Successful Query notification	SuccessErrorNotification	false
errorNotification	Unsuccessful Query notification	SuccessErrorNotification	"Error (status code: statusCode)"
metaData	Metadata query for dataProvider	MetaDataQuery	{}
liveMode	Whether to update data automatically ("auto") or not ("manual") if a related live event is received. The "off" value is used to avoid creating a subscription.	"auto" | "manual" | "off"	"off"
liveParams	Params to pass to liveProvider's subscribe method if liveMode is enabled.	{ ids?: string[]; [key: string]: any; }	undefined
onLiveEvent	Callback to handle all related live events of this hook.	(event: LiveEvent) => void	undefined

Config parameters

interface UseListConfig {
    pagination?: {
        current?: number;
        pageSize?: number;
    };
    sort?: Array<{
        field: string;
        order: "asc" | "desc";
    }>;
    filters?: Array<{
        field: string;
        operator: CrudOperators;
        value: any;
    }>;
}

Type Parameters

Property	Desription	Type	Default
TData	Result data of the query. Extends BaseRecord	BaseRecord	BaseRecord
TError	Custom error object that extends HttpError	HttpError	HttpError

Return values

Description	Type
Result of the react-query's useQuery	QueryObserverResult<{ data: TData[]; total: number; }, TError>