How to Implement Table Filtering with Table.Filter.DateRangePicker in refine-shadcn

Use the filter prop on Table.Column to render Table.Filter.DateRangePicker, which bridges a shadcn/ui calendar popover with react-table's column filtering API to enable start- and end-date range selection.

The ferdiunal/refine-shadcn library provides a powerful Table component built on @tanstack/react-table that simplifies implementing column filters. By using the built-in Table.Filter.DateRangePicker component, you can add intuitive date range selection to any column without manually managing complex filter state. This guide explains how to implement table filtering with Table.Filter.DateRangePicker using the actual source architecture from the repository.

Understanding the Date Range Filter Architecture

Table Component Integration

In /packages/theme/src/table/index.tsx, the core Table wrapper constructs column definitions for @tanstack/react-table. When enableFilters is active on the table instance, the header rendering logic checks isFilterable (derived from enableColumnFilters) for each column. If a column defines a filter prop, the table invokes that component with a TableFilterProps object containing column, title, numberOfMonths, and align parameters.

Date Range Picker Implementation

The actual UI implementation resides in /packages/theme/src/table/fields/table-filter-date-range-picker.tsx. The internal TableFilterDateRangePickerFilter component maintains local date state using DateRange | undefined. When a user selects a range in the Calendar popover, a useEffect hook synchronizes the selection with the table state by calling column.setFilterValue([startDate, endDate]), formatting both dates as yyyy-MM-dd strings. The component renders the selected range as a Badge inside the filter button and provides a clear-filter button (FilterX) that resets both the column filter and local state.

Implementing Date Range Filtering

Enable Filtering on the Table

First, ensure your table instance supports filtering by setting the enableFilters prop on the Table component.

import { ListPage, Table } from "@ferdiunal/refine-shadcn";

const UserList = () => {
  return (
    <ListPage>
      <Table enableSorting enableFilters>
        {/* columns */}
      </Table>
    </ListPage>
  );
};

Add the Date Range Column Filter

Define a column that uses the date range picker by passing a function to the filter prop. The function receives TableFilterProps and should return the Table.Filter.DateRangePicker component.

import { TableFilterProps } from "@ferdiunal/refine-shadcn";

// Inside your Table component
<Table.Column
  header="Birthday"
  accessorKey="birthday"
  id="birthday"
  enableSorting
  enableHiding
  filter={(props: TableFilterProps) => (
    <Table.Filter.DateRangePicker {...props} align="end" />
  )}
/>

This pattern is taken from the real-world implementation in /templates/vite-react/src/pages/users/list.tsx, which renders the filter UI directly in the column header.

Complete Minimal Example

Here is a fully functional page implementing date range filtering:

import { ListPage, Table, TableFilterProps } from "@ferdiunal/refine-shadcn";

export const SimpleList = () => (
  <ListPage>
    <Table enableSorting enableFilters>
      <Table.Column
        header="Name"
        accessorKey="name"
        enableSorting
      />
      <Table.Column
        header="Created"
        accessorKey="createdAt"
        enableSorting
        filter={(props: TableFilterProps) => (
          <Table.Filter.DateRangePicker {...props} align="end" />
        )}
      />
    </Table>
  </ListPage>
);

When a user selects a date range, the filter value becomes an array of ISO date strings (e.g., ["2024-01-01", "2024-01-31"]). If your table uses useTable with a Refine resource, this filter automatically propagates to your data provider for server-side filtering.

Customizing the Date Range Picker

The TableFilterProps interface exposes several customization options that control the popover behavior:

• align: Controls the popover alignment ("start", "center", or "end")
• numberOfMonths: Specifies how many months to display in the calendar popover (defaults to 1)
• title: Overrides the default filter button text

filter={(props: TableFilterProps) => (
  <Table.Filter.DateRangePicker 
    {...props} 
    align="start" 
    numberOfMonths={2}
    title="Select Period"
  />
)}

Summary

• Table.Filter.DateRangePicker is a built-in filter component in refine-shadcn that wraps a shadcn/ui calendar popover and synchronizes with react-table's filter state.
• The component automatically formats selected dates as yyyy-MM-dd strings and updates the column via column.setFilterValue() when the user selects or clears a range.
• To implement, set enableFilters on the Table component and provide the filter prop on Table.Column with the TableFilterProps spread into Table.Filter.DateRangePicker.
• Key source files: /packages/theme/src/table/index.tsx (core table logic) and /packages/theme/src/table/fields/table-filter-date-range-picker.tsx (filter UI implementation).
• The filter value array is compatible with Refine's server-side data providers when using the integrated useTable hook.

Frequently Asked Questions

How does Table.Filter.DateRangePicker format the selected dates?

According to the source code in /packages/theme/src/table/fields/table-filter-date-range-picker.tsx, the component formats dates as yyyy-MM-dd strings using a date-fns utility before calling column.setFilterValue([startDate, endDate]). This standard format ensures compatibility with most backend APIs and SQL date columns.

Can I display multiple months in the date picker calendar?

Yes. The TableFilterProps interface includes a numberOfMonths property that is passed through to the underlying shadcn/ui Calendar component. Set this in your filter function: <Table.Filter.DateRangePicker {...props} numberOfMonths={2} /> to show a two-month range view, making it easier for users to select dates across month boundaries.

How do I clear the date range filter programmatically?

The component includes a built-in clear button (FilterX) that resets both the local React state and the column filter value by calling column.setFilterValue(undefined). To clear programmatically from outside the component, access the specific column instance via the table's getColumn(id) API and call setFilterValue(undefined) on it.

Does this filter work with server-side filtering in Refine?

Yes. When using useTable from @refinedev/react-table (integrated in refine-shadcn), the filter value array is automatically included in the filters object sent to your data provider's getList method. Ensure your API endpoint can parse the date range array format ["yyyy-MM-dd", "yyyy-MM-dd"] to apply the range against your database queries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}