Filter ^1.0.0 Beta

Filter is a built-in column header filter component. Click the filter icon in the column header to open the filter panel. It supports manually specified options and automatically extracting options from data.

Basic Usage

Create a Filter component via the createFilterCell factory function and use it as customHeaderCell.

loading

Auto Extract Options

Set autoOptions: true, and Filter will automatically extract unique values from the current column's data as filter options.

{
    title: t('city'),
    dataIndex: 'city',
    customHeaderCell: Filter({
        autoOptions: true, // Automatically extract options from data
    }),
}

Limitations

• autoOptions is convenient for small datasets. For large datasets, a full traversal may cause performance issues.
• Option order is not guaranteed.

autoOptions Cache Invalidation

autoOptions caches the extracted results. When the props.dataSource reference changes (e.g., in sort-remote scenarios where the parent passes filtered data back as dataSource), the cache is cleared and options are re-extracted from the new data the next time the dropdown opens, which may result in fewer options. Use the options parameter with a fixed list to keep options stable.

Custom Filter Logic

You can customize the filter logic via the filter parameter:

{
    title: t('age'),
    dataIndex: 'age',
    customHeaderCell: Filter({
        options: [
            { label: 'Under 30', value: 'young' },
            { label: '30 and above', value: 'old' },
        ],
        filter: ({ row, cellValue, filterValues }) => {
            return filterValues.some(v => {
                if (v === 'young') return cellValue < 30;
                if (v === 'old') return cellValue >= 30;
                return false;
            });
        },
    }),
}

loading

createFilterCell Options

The createFilterCell factory function accepts a configuration object:

interface CreateFilterCellOption {
    /** Whether to use remote filtering, default false */
    remote?: boolean;
    /** Triggered when filter status changes */
    onChange?: (data: { colKey: UniqKey; status: FilterStatus }) => void;
}

Property	Type	Default	Description
remote	boolean	false	Whether to use remote filtering, when set to true, automatic data filtering will not be triggered
onChange	(data) => void	-	Callback when filter status changes, parameters include colKey (column key) and status (current column filter status)

Configuration Options

FilterComponent accepts a configuration object:

interface FilterComponentConfig {
    options?: FilterOption[];       // Filter options list
    filter?: (args) => boolean;     // Custom filter function
    autoOptions?: boolean;          // Whether to automatically extract options from data, default false
}

interface FilterOption {
    label: string;     // Display text
    value: any;        // Filter value
    selected?: boolean; // Whether selected by default
}

FilterStatus Type

interface FilterStatus {
    /** Currently selected filter values array */
    value: any[];
    /** Custom filter logic function */
    filter?: (args: { row: any; cellValue: any; filterValues: any[] }) => boolean;
}

Note on Remote Sorting Conflicts

In sort-remote mode, the third parameter data of the @sort-change event is the table's current working data copy. If there are active filter conditions at this time, this data only contains the filtered rows, not the complete original props.dataSource.

If you directly assign this data to dataSource, the filtered-out rows will be permanently lost.

Correct Approach

When using remote sorting, the parent component should always sort based on its own maintained original data source, rather than using the data parameter from the sort-change event.

// ✘ Wrong: data may already be filtered, direct assignment will lose data
function handleSortChange(col, order, data) {
    dataSource.value = data;
}

// ✔ Correct: sort based on original data source
function handleSortChange(col, order) {
    // originalData = dataSource.value
    dataSource.value = sortMyData(originalData, col, order);
}