Filtering

gp-grid provides powerful column filtering.

Basic Filtering

Click the filter icon in a column header to open the filter popup:

<script setup lang="ts">
const columns: ColumnDefinition[] = [
  {
    field: "name",
    cellDataType: "text",
    width: 150,
    filterable: true,
  },
  {
    field: "salary",
    cellDataType: "number",
    width: 120,
    filterable: true,
  },
];
</script>

Filter Operators

Text Filters

Number Filters

Values Mode

Text filter popups also offer a checkbox list of the column's distinct values. Entries are grouped by display label: with a valueFormatter, several raw values can share one label, and ticking it selects all of them. The applied filter always stores the raw values (selectedValues: Set<CellValue>), so a formatter never changes what a server data source receives.

When the column contains blank cells — null, empty strings, or empty arrays such as a tags column with no tags — the list shows a (Blanks) entry. Untick it to exclude blank rows from the result.

Disable Filtering

<script setup lang="ts">
const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 80, filterable: false },
  { field: "name", cellDataType: "text", width: 150 },  // filterable by default
];
</script>

Grouped Conditions

The condition editor makes Boolean precedence explicit. Conditions live inside group cards: one AND/OR selector joins the conditions in a group, while a separate selector joins the groups themselves.

• Use Add condition to extend the current group.
• Use Add group to create a separate branch.
• Empty conditions and groups are discarded when you apply the filter.

This means the popup can distinguish (A AND B) OR C from A AND (B OR C). The first expression is represented as:

import type { ColumnFilterModel } from "@gp-grid/vue";

const filter: ColumnFilterModel = {
  groups: [
    {
      conditions: [
        { type: "text", operator: "startsWith", value: "A" },
        { type: "text", operator: "endsWith", value: "z" },
      ],
      combination: "and",
    },
    {
      conditions: [
        { type: "text", operator: "equals", value: "Giovanni" },
      ],
      combination: "and",
    },
  ],
  combination: "or",
};

ColumnFilterModel.combination joins groups. Each FilterConditionGroup.combination joins the conditions inside that group. Filters belonging to different columns are combined with AND at row level.

Migrating Flat Condition Models

The underlying GridCore.setFilter() still accepts the previous flat model with conditions, combination, and optional per-condition nextOperator properties. It preserves the old left-to-right result and normalizes it into equivalent groups. The grid's filter state and server-side DataSourceRequest.filter always use the grouped shape.

Use normalizeColumnFilterModel(legacyFilter) when you want to migrate stored filter state explicitly.