Documentation

X-Filter is a filter-builder toolkit for React applications that need a portable query model. The core package owns the filter tree, validation, JSON serialization, DSL formatting, parsing, and SQL generation. UI packages render that same state through product-native adapters.

The npm packages are planned for pre-release. The local workspace package names are already stable: @x-filter/core, @x-filter/react, @x-filter/antd, and @x-filter/shadcn.

Package roles

Package	Role
`@x-filter/core`	Filter types, mutations, validation, JSON, DSL, and SQL helpers.
`@x-filter/react`	Controlled and uncontrolled hooks for builders, DSL editing, URL sync, and view models.
`@x-filter/antd`	Ant Design filter-builder components over the shared React contract.
`@x-filter/shadcn`	shadcn-style primitives and builder components over the same contract.

Architecture

Define a typed field schema.
Store a Filter tree in application state.
Render the tree with an adapter.
Validate and export JSON, DSL, or parameterized SQL.

import { validate } from '@x-filter/core';
import { formatDSL } from '@x-filter/core/dsl';
import { toSQL } from '@x-filter/core/sql';
 
const validation = validate(filter, schema);
const dsl = formatDSL(filter);
const sql = toSQL(filter, { fieldMap: { status: 'tickets.status' } });

Live parity demo

AND

Not

Account tier

equals

Enterprise

Not

Contract value

Not

Region

is any of

North America

EMEA

{
  "combinator": "and",
  "children": [
    {
      "field": "accountTier",
      "operator": "equals",
      "value": "enterprise"
    },
    {
      "field": "contractValue",
      "operator": "gt",
      "value": 50000
    },
    {
      "field": "region",
      "operator": "in",
      "value": [
        "na",
        "emea"
      ]
    }
  ]
}

Continue with Getting Started to wire the first builder.