Skip to main content
Unlock powerful debugging and effortless query monitoring with Refine DevtoolsLearn More
RefineDocumentation
Version: 4.xx.xx

Tables

Tables are essential in data-intensive applications, serving as the primary way for organizing and displaying data in a readable format using rows and columns. Their integration, however, is complex due to functionalities like sorting, filtering, and pagination. Refine's tables integration aims to make this process as simple as possible while providing as many real world features as possible out of the box. This guide will cover the basics of tables in Refine and how to use them.

Handling Data​

useTable allows us to fetch data according to the sorter, filter, and pagination states. Under the hood, it uses useList for the fetch. Its designed to be headless, but Refine offers seamless integration with several popular UI libraries, simplifying the use of their table components.

Basic Usage​

The usage of the useTable hooks may slightly differ between UI libraries, however, the core functionality of useTable hook in @refinedev/core stays consistent in all implementations. The useTable hook in Refine's core is the foundation of all the other useTable implementations.

import React from "react";
import { useTable, pageCount, pageSize, current, setCurrent } from "@refinedev/core";


export const ProductTable: React.FC = () => {
    const { tableQueryResult, pageCount, pageSize, current, setCurrent } = useTable<IProduct>({
        resource: "products",
        pagination: {
            current: 1, 
            pageSize: 10,
        },
    });
    const posts = tableQueryResult?.data?.data ?? [];

    if (tableQueryResult?.isLoading) {
        return <div>Loading...</div>;
    }

    return (
        <div style={{ padding:"8px" }}>
            <h1>Products</h1>
            <table>
                <thead>
                    <tr>
                        <th>ID</th>
                        <th>Name</th>
                        <th>Price</th>
                    </tr>
                </thead>
                <tbody>
                    {posts.map((post) => (
                        <tr key={post.id}>
                            <td>{post.id}</td>
                            <td>{post.name}</td>
                            <td>{post.price}</td>
                        </tr>
                    ))}
                </tbody>
            </table>
            <hr />
            <p>Current Page: {current}</p>
            <p>Page Size: {pageSize}</p>
            <button
              onClick={() => {
                setCurrent(current - 1);
              }}
              disabled={current < 2}
            >
              Previous Page
            </button>
            <button
              onClick={() => {
                setCurrent(current + 1);
              }}
              disabled={current === pageCount}
            >
              Next Page
            </button>
        </div>
    );
};

interface IProduct {
    id: number;
    name: string;
    price: string;
}
Open on CodeSandboxOpen Sandbox

Check out Refine's useTable reference page to learn more about the usage and see it in action.

Pagination
Check the guide
Please check the guide for more information on this topic.
​

useTable has a pagination feature. The pagination is done by passing the current, pageSize and, mode keys to pagination object.

  • current: The page index.
  • pageSize: The number of items per page.
  • mode: Whether to use server side pagination or not.
    • When server is selected, the pagination will be handled on the server side.
    • When client is selected, the pagination will be handled on the client side. No request will be sent to the server.
    • When off is selected, the pagination will be disabled. All data will be fetched from the server.

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 React from "react";
import { useTable } from "@refinedev/core";

export const ProductTable: React.FC = () => {
  const { tableQueryResult, pageCount, pageSize, current, setCurrent } = useTable<IProduct>({
    resource: "products",
    pagination: {
        current: 1, 
        pageSize: 10,
        mode: "server", // "client" or "server"
    },
  });
  const posts = tableQueryResult?.data?.data ?? [];

  if (tableQueryResult?.isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>Products</h1>
      <table>
        <thead>
          <tr>
            <th>ID</th>
            <th>Name</th>
            <th>Price</th>
          </tr>
        </thead>
        <tbody>
          {posts.map((post) => (
            <tr key={post.id}>
              <td>{post.id}</td>
              <td>{post.name}</td>
              <td>{post.price}</td>
            </tr>
          ))}
        </tbody>
      </table>
      <hr />
      <p>Current Page: {current}</p>
      <p>Page Size: {pageSize}</p>
      <button
        onClick={() => {
          setCurrent(current - 1);
        }}
        disabled={current < 2}
      >
        Previous Page
      </button>
      <button
        onClick={() => {
          setCurrent(current + 1);
        }}
        disabled={current === pageCount}
      >
        Next Page
      </button>
    </div>
  );
};

interface IProduct {
    id: number;
    name: string;
    price: string;
}
Open on CodeSandboxOpen Sandbox

Filtering
Check the guide
Please check the guide for more information on this topic.
​

useTable has a filter feature. The filter is done by using the initial, permanent, defaultBehavior and mode keys to filters object.

These states are a CrudFilters type for creating complex single or multiple queries.

  • initial: The initial filter state. It can be changed by the setFilters function.
  • permanent: The default and unchangeable filter state. It can't be changed by the setFilters function.
  • defaultBehavior: The default behavior of the setFilters function.
    • When merge is selected, the new filters will be merged with the old ones.
    • When replace is selected, the new filters will replace the old ones. It means that the old filters will be deleted.
  • mode: Whether to use server side filter or not.
    • When server is selected, the filters will be sent to the server.
    • When off is selected, the filters will be applied on the client side.

useTable will pass these states to dataProvider for making it possible to fetch the data you need. Handling and adapting these states for API requests is the responsibility of the dataProvider

import React from "react";
import { useTable } from "@refinedev/core";


export const ProductTable: React.FC = () => {
  const { tableQueryResult, filters, setFilters } = useTable<IProduct>({
      resource: "products",
      filters: {
          permanent: [
              {
                  field: "price",
                  value: "200",
                  operator: "lte",
              },
          ],
          initial: [{ field: "category.id", operator: "eq", value: "1" }],
      },
  });
  const products = tableQueryResult?.data?.data ?? [];

  const getFilterByField = (field: string) => {
      return filters.find((filter) => {
          if ("field" in filter && filter.field === field) {
              return filter;
          }
      }) as LogicalFilter | undefined;
  };

  const resetFilters = () => {
    setFilters([], "replace");
  };


  if (tableQueryResult.isLoading) {
      return <div>Loading...</div>;
  }

  return (
      <div>
          <h1>Products with price less than 200</h1>
          <table>
              <thead>
                  <tr>
                      <th>ID</th>
                      <th>Name</th>
                      <th>Price</th>
                      <th>categoryId</th>
                  </tr>
              </thead>
              <tbody>
                  {products.map((product) => (
                      <tr key={product.id}>
                          <td>{product.id}</td>
                          <td>{product.name}</td>
                          <td>{product.price}</td>
                          <td>{product.category.id}</td>
                      </tr>
                  ))}
              </tbody>
          </table>
          <hr />
          Filtering by field:
          <b>
              {getFilterByField("category.id")?.field}, operator{" "}
              {getFilterByField("category.id")?.operator}, value
              {getFilterByField("category.id")?.value}
          </b>
          <br />
          <button
              onClick={() => {
                  setFilters([
                      {
                          field: "category.id",
                          operator: "eq",
                          value:
                              getFilterByField("category.id")?.value === "1"
                                  ? "2"
                                  : "1",
                      },
                  ]);
              }}
          >
              Toggle Filter
          </button>
          <button onClick={resetFilters}>Reset filter</button>
      </div>
  );
};

interface IProduct {
  id: number;
  name: string;
  price: string;
  category: {
      id: number;
  };
}
Open on CodeSandboxOpen Sandbox

Sorting
Check the guide
Please check the guide for more information on this topic.
​

useTable has a sorter feature. The sorter is done by passing the initial and permanent keys to sorters object. These states are a CrudSorter type for creating single or multiple queries.

  • initial: The initial sorter state. It can be changed by the setSorters function.
  • permanent: The default and unchangeable sorter state. It can't be changed by the setSorters function.

useTable will pass these states to dataProvider for making it possible to fetch the data you need. Handling and adapting these states for API requests is the responsibility of the dataProvider

You can change the sorters state by using the setSorters function. Every change will trigger a new fetch.

import React from "react";
import { useTable } from "@refinedev/core";

export const ProductTable: React.FC = () => {
    const { tableQueryResult, sorters, setSorters } = useTable<IProduct>({
        resource: "products",
        sorters: {
            initial: [{ field: "price", order: "asc" }],
        },
    });
    const products = tableQueryResult?.data?.data ?? [];

    const findSorterByFieldName = (fieldName: string) => {
        return sorters.find((sorter) => sorter.field === fieldName);
    };


    if (tableQueryResult.isLoading) {
        return <div>Loading...</div>;
    }
    
    return (
        <div>
            <h1>Products</h1>
            <table>
                <thead>
                    <tr>
                        <th>ID</th>
                        <th>Name</th>
                        <th>Price</th>
                    </tr>
                </thead>
                <tbody>
                    {products.map((product) => (
                        <tr key={product.id}>
                            <td>{product.id}</td>
                            <td>{product.name}</td>
                            <td>{product.price}</td>
                        </tr>
                    ))}
                </tbody>
            </table>
            <hr />
            <hr />
            Sorting by field:
            <b>
                {findSorterByFieldName("price")?.field}, order{" "}
                {findSorterByFieldName("price")?.order}
            </b>
            <br />
            <button
                onClick={() => {
                    setSorters([
                        {
                            field: "price",
                            order:
                                findSorterByFieldName("price")?.order === "asc"
                                    ? "desc"
                                    : "asc",
                        },
                    ]);
                }}
            >
                Toggle Sort
            </button>
        </div>
    );
};

interface IProduct {
    id: number;
    name: string;
    price: string;
}
Open on CodeSandboxOpen Sandbox

useTable has a search feature with onSearch. The search is done by using the onSearch function with searchFormProps. These feature enables you to easily connect form state to the table filters.

  • onSearch: function is triggered when the searchFormProps.onFinish is called. It receives the form values as the first argument and expects a promise that returns a CrudFilters type.
  • searchFormProps: Has necessary props for the <form>.

For example we can fetch product with the name that contains the search value.

import React from "react";
import { HttpError } from "@refinedev/core";
import { useTable } from "@refinedev/antd";
import { Button, Form, Input, Space, Table } from "antd";

export const ProductTable: React.FC = () => {
    const { tableProps, searchFormProps } = useTable<
        IProduct,
        HttpError,
        IProduct
    >({
        resource: "products",
        onSearch: (values) => {
            return [
                {
                    field: "name",
                    operator: "contains",
                    value: values.name,
                },
            ];
        },
    });

    return (
        <div style={{ padding: "4px" }}>
            <h2>Products</h2>
            <Form {...searchFormProps}>
                <Space>
                    <Form.Item name="name">
                        <Input placeholder="Search by name" />
                    </Form.Item>
                    <Form.Item>
                        <Button htmlType="submit">Search</Button>
                    </Form.Item>
                </Space>
            </Form>
            <Table {...tableProps} rowKey="id">
                <Table.Column dataIndex="id" title="ID" />
                <Table.Column dataIndex="name" title="Name" />
                <Table.Column dataIndex="price" title="Price" />
            </Table>
        </div>
    );
};

interface IProduct {
    id: number;
    name: string;
    price: string;
}
Open on CodeSandboxOpen Sandbox

Check out Ant Design's useTable reference page to learn more about the usage and see it in action.

Integrating with Routers​

Resource
Router Integrated
This value can be inferred from the route. Click to see the guide for more information.
​

useTable can infer current resource from the current route based on your resource definitions. This eliminates the need of passing these parameters to the hooks manually.

useTable({
  // When the current route is `/products`, the resource prop can be omitted.
  resource: "products",
});

Sync with Location
Router Integrated
This value can be inferred from the route. Click to see the guide for more information.
Globally Configurable
This value can be configured globally. Click to see the guide for more information.
​

When you use the syncWithLocation feature, the useTable's state (e.g., sort order, filters, pagination) is automatically encoded in the query parameters of the URL, and when the URL changes, the useTable state is automatically updated to match. This makes it easy to share table state across different routes or pages, and to allow users to bookmark or share links to specific table views.

Relationships
Check the guide
Please check the guide for more information on this topic.
​

Refine handles data relations with data hooks(eg: useOne, useMany, etc.). This compositional design allows you to flexibly and efficiently manage data relationships to suit your specific requirements.

For example imagine each post has a many category. We can fetch the categories of the post by using the useMany hook.

import React from "react";
import { useTable, HttpError, useMany } from "@refinedev/core";

export const HomePage: React.FC = () => {
    const { tableQueryResult } = useTable<IPost, HttpError>({
        resource: "posts",
    });
    const posts = tableQueryResult?.data?.data ?? [];

    const categoryIds = posts.map((item) => item.category.id);
    const { data: categoriesData, isLoading } = useMany<ICategory>({
        resource: "categories",
        ids: categoryIds,
        queryOptions: {
            enabled: categoryIds.length > 0,
        },
    });

    if (tableQueryResult?.isLoading) {
        return <div>Loading...</div>;
    }

    return (
        <div>
            <h1>Posts</h1>
            <table>
                <thead>
                    <tr>
                        <th>ID</th>
                        <th>Title</th>
                        <th>Category</th>
                    </tr>
                </thead>
                <tbody>
                    {posts.map((post) => (
                        <tr key={post.id}>
                            <td>{post.id}</td>
                            <td>{post.title}</td>
                            <td>
                                {isLoading ? (
                                    <div>Loading...</div>
                                ) : (
                                    categoriesData?.data.find(
                                        (item) => item.id === post.category.id,
                                    )?.title
                                )}
                            </td>
                        </tr>
                    ))}
                </tbody>
            </table>
        </div>
    );
};

interface IPost {
    id: number;
    title: string;
    category: {
        id: number;
    };
}

interface ICategory {
    id: number;
    title: string;
}
Open on CodeSandboxOpen Sandbox
Previous
Forms
Next
Routing
Was this helpful?