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:
[
{
"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 |