useTable

useTable allows us to fetch data according to the sorter state, the filter state and the pagination states.

info

If you're looking for a complete table library, Refine supports two table libraries out-of-the-box.

• React Table (for Headless users) - Documentation - Example
• Ant Design Table (for Ant Design users) - Documentation - Example

Lets say you have a endpoint that returns the following data:

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

[
    {
        "id": 182,
        "title": "A aspernatur rerum molestiae.",
        "content": "Natus molestias incidunt voluptatibus. Libero delectus facilis...",
        "status": "published",
        "createdAt": "2021-04-18T00:09:11.607Z"
    },
    {
        "id": 989,
        "title": "A molestiae vel voluptatem enim.",
        "content": "Voluptas consequatur quia beatae. Ipsa est qui culpa deleniti...",
        "status": "draft",
        "createdAt": "2020-01-28T02:57:58.892Z"
    }
]

Basic Usage

In basic usage useTable returns the data as it comes from the endpoint.

import { useTable } from "@pankod/core";

interface IPost {
    id: string;
    title: string;
    content: string;
    status: "published" | "draft" | "rejected";
}

const { tableQueryResult } = useTable<IPost>({
    resource: "posts",
});

Pagination

useTable has a pagination feature. The pagination is done by using the current and pageSize props. The current is the current page and the pageSize is the number of records per page.

By default, the current is 1 and the pageSize is 10. You can change default values by passing the initialCurrent and initialPageSize props to the useTable hook.

You can also change the current and pageSize values by using the setCurrent and setPageSize functions that are returned by the useTable hook. Every change will trigger a new fetch.

import { useTable } from "@pankod/core";

const { pageSize, setPageSize, current, setCurrent } = useTable({
    resource: "posts",
    initialCurrent: 1,
    initialPageSize: 10,
});

console.log(pageSize); // 10
console.log(current); // 1

setPageSize(20);
console.log(pageSize); // 20

setCurrent(2);
console.log(current); // 2

Sorting

useTable has a sorter feature. The sorter is done by using the sorter state. The sorter state is a CrudSorting type that contains the field and the order of the sort. You can change the sorter state by using the setSorter function. Every change will trigger a new fetch.

Also you can add initial sorter state by passing the initialSorter prop and permanent sorter state by passing the permanentSorter prop to the useTable hook. Even if you change the sorter state, the permanentSorter will be used together with the sorter state.

import { useTable } from "@pankod/core";

const { sorter, setSorter } = useTable({
    resource: "posts",
    initialSorter: [
        {
            field: "title",
            order: "asc",
        },
    ],
    permanentSorter: [
        {
            field: "id",
            order: "desc",
        },
    ],
});

console.log(sorter); // [{ field: "id", order: "desc" }, { field: "title", order: "asc" }]

setSorter([
    {
        field: "createdAt",
        order: "desc",
    },
]);

console.log(sorter); // [{ field: "createdAt", order: "desc" }, { field: "id", order: "desc" }]

Filtering

useTable has a filter feature. The filter is done by using the filters state. The filters state is a CrudFilters type that contains the field, the operator and the value of the filter. You can change the filter state by using the setFilters function. Every change will trigger a new fetch.

Also you can add initial filter state by passing the initialFilter prop and permanent filter state by passing the permanentFilter prop to the useTable hook. Even if you change the filter state, the permanentFilter will be used together with the filter state.

import { useTable } from "@pankod/core";

const { filters, setFilters } = useTable({
    resource: "posts",
    initialFilter: [
        {
            field: "title",
            operator: "contains",
            value: "rerum",
        },
    ],
    permanentFilter: [
        {
            field: "status",
            operator: "equals",
            value: "published",
        },
    ],
});

console.log(filters); // [{ field: "title", operator: "contains", value: "rerum" }, { field: "status", operator: "equals", value: "published" }]

setFilter([
    {
        field: "title",
        operator: "contains",
        value: "A",
    },
]);

console.log(filters); // [{ field: "title", operator: "contains", value: "A" }, { field: "status", operator: "equals", value: "published" }]

API

Properties

Key	Description	Type	Default
resource	Resource name for API data interactions	string | undefined	Resource name that it reads from the URL
initialCurrent	Initial page index	number	1
initialPageSize	Initial number of items per page	number	10
initialSorter	Initial sorter state	CrudSorting
permanentSorter	Default and unchangeable sorter state	CrudSorting	[]
initialFilter	Initial filter state	CrudFilters
permanentFilter	Default and unchangeable filter state	CrudFilters	[]
syncWithLocation	Sortings, filters, page index and records shown per page are tracked by browser history	boolean	Value set in Refine. If a custom resource is given, it will be false
queryOptions	react-query's useQuery options	UseQueryOptions< { data: TData[]; }, TError>
metaData	Metadata query for dataProvider	MetaDataQuery	{}
dataProviderName	If there is more than one dataProvider, you should use the dataProviderName that you will use.	string	default
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?: BaseKey[]; [key: string]: any; }	undefined
onLiveEvent	Callback to handle all related live events of this hook.	(event: LiveEvent) => void	undefined

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

Property	Description	Type
tableQueryResult	Result of the react-query's useQuery	QueryObserverResult<{ data: TData[]; total: number; }, TError>
current	Current page index state	number
totalPage	Total page count	number
setCurrent	A function that changes the current	React.Dispatch<React.SetStateAction<number>>
pageSize	Current pageSize state	number
setPageSize	A function that changes the pageSize.	React.Dispatch<React.SetStateAction<number>>
sorter	Current sorting state	CrudSorting
setSorter	A function that accepts a new sorter state.	(sorter: CrudSorting) => void
filters	Current filters state	CrudFilters
setFilters	A function that accepts a new filter state	(filters: CrudFilters) => void