useTable

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

信息

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
Material UI Table (for Material UI 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: number;
    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.

If you want to disable pagination, you can use hasPagination property in useTable config and set it to false

信息

If hasPagination is set to false, current, setCurrent, pageSize, setPageSize and pageCount will return undefined

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.

setFilters function can work in two different behaviors; merge (default) and replace. You can set the behavior by passing it as the 2nd parameter.

You can also call setFilters with a setter function.

信息

If you are using merge behavior and want to remove one of the filters; you should set the value to undefined or null. For or filters, you should set the value to an empty array [] to remove the filter.

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: "F",
    },
]);

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

setFilter([
    {
        field: "author",
        operator: "contains",
        value: "Foo",
    },
    "merge", // default
]);

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

setFilter([
    {
        field: "author",
        operator: "ne",
        value: "Foo",
    },
    "replace",
]);

console.log(filters);
/*
[
    { field: "author", operator: "ne", value: "Foo" },
    { field: "status", operator: "equals", value: "published" }
]
*/

setFilters((prev) => prev.filter((filter) => filter.field !== "author"));

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

API

Properties

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 (returns `undefined` if pagination is disabled)	`number` \| `undefined`
totalPage	Total page count (returns `undefined` if pagination is disabled)	`number` \| `undefined`
setCurrent	A function that changes the current (returns `undefined` if pagination is disabled)	`React.Dispatch<React.SetStateAction<number>>` \| `undefined`
pageSize	Current pageSize state (returns `undefined` if pagination is disabled)	`number` \| `undefined`
setPageSize	A function that changes the pageSize. (returns `undefined` if pagination is disabled)	`React.Dispatch<React.SetStateAction<number>>` \| `undefined`
sorter	Current sorting state s	`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, behavior?: "merge" \\| "replace" = "merge") => void` - `(setter: (previousFilters: CrudFilters) => CrudFilters) => void`
createLinkForSyncWithLocation	A function create accessible links for syncWithLocation	`(params:` SyncWithLocationParams`) => string;`

Basic Usage​

Pagination​

Sorting​

Filtering​

API​

Properties​

Type Parameters​

Return values​