FilterQuery overview

FilterQuery is a text input component that lets users type structured filter queries, such as Status: Open and Age: >30. It converts these queries into a parsed filter configuration that your app can use.

For data-heavy apps where users need to filter large datasets quickly, FilterQuery provides a keyboard-driven alternative to clicking through dropdowns. It offers syntax highlighting, autocomplete, and outputs structured rules that your filtering logic can use directly.

Basic usage

<script>
  import { FilterQuery, createArrayFilter } from "@svar-ui/svelte-filter";

  const fields = [
    { id: "status", label: "Status", type: "text" },
    { id: "age",    label: "Age",    type: "number" },
  ];

  const options = {
    status: ["Open", "Closed", "In Progress"],
  };

  let data = [/* your records */];
  let filteredData = data;

  function handleFilter({ value, error }) {
    if (error && error.code !== "NO_DATA") return;
    const filter = createArrayFilter(value, {}, fields);
    filteredData = filter(data);
  }
</script>

<FilterQuery
  {fields}
  {options}
  onchange={handleFilter}
/>

This renders a single-line input with a search button. As the user types, a syntax highlighting overlay colorizes field names, values, and operators in real time. An autocomplete dropdown shows matching fields or values from options. When the user presses Enter or clicks Search, onchange fires with the parsed filter config.

Pass that config to createArrayFilter to filter a local array, or send it to your backend.

How it works

1. The user starts typing a query like Status: — the autocomplete dropdown lists available fields.
2. After the colon, suggestions switch to values from options.
3. Syntax highlighting shows query structure in real time and underlines unknown fields or bad syntax in red.
4. Pressing Enter (or clicking the search button) fires onchange.
5. The event payload carries value (a parsed filtering rule), text (the normalized query string), and an error field when validation fails.

When to use FilterQuery

FilterQuery is suited for dashboards, admin panels, task managers, and CRMs where users need fast, keyboard-driven filtering. It performs best when users understand the data schema and want to type queries directly. Typical users include developers, analysts, and operations teams who require precise control over record filtering.

Next steps

• Configuring Fields — define your schema, supply value options, and understand the label/ID model
• Query Syntax — operators, wildcards, date predicates, and logical grouping
• Filtering Data — using the onchange payload, filtering local arrays, and handling errors
• Natural Language Mode — forward plain text to an AI or NLP endpoint
• API Reference — all props and event payload fields