Configuring fields

This guide covers how to define which fields users can filter by, how to supply value options for autocomplete, and how field labels relate to the IDs stored in the query value.

How fields work

The fields prop is an array of fields objects that describes your data schema to the component. Each field definition affects three parts of the query behavior. Autocomplete suggestions show the field's label, syntax highlighting validates field names against the list, and the parser uses the field's type to determine which operators are available.

Every field has three required properties:

• id — the stable identifier used in the stored query string and in the filtering rules output
• label — the human-readable name shown in the autocomplete dropdown and in the input itself
• type — "text", "number", or "date"; determines which operators the parser accepts for that field

The type controls what syntax is valid for that field:

• "text" fields support wildcard patterns (name: Alex*), word operators (contains, starts, ends), and exact or exclusion matching
• "number" fields support comparison operators (>, >=, <, <=) and range syntax (25 .. 50)
• "date" fields support comparisons, ranges, date predicates (field.year, field.month), and partial date values (2024, 2024-06)

When fields is empty (the default), autocomplete offers no suggestions and the parser can't validate field names — typed text is treated as free text or an unknown field.

Defining fields

Pass a fields array to make the component aware of your data schema:

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

  const fields = [
    { id: "first_name", label: "First Name", type: "text" },
    { id: "last_name",  label: "Last Name",  type: "text" },
    { id: "age",        label: "Age",         type: "number" },
    { id: "country",    label: "Country",     type: "text" },
    { id: "start",      label: "Start Date",  type: "date" },
  ];
</script>

<FilterQuery {fields} />

With these fields configured, the autocomplete dropdown suggests FirstName, LastName, Age, Country, and StartDate as the user types. Queries like Age: >30 and StartDate: 2024 are valid; unrecognized field names are underlined as errors.

Providing value options

To collect options from the array of data to filter, use the getOptionsMap helper:

<script>
  import { getData } from "../data";
  import { FilterQuery, getOptionsMap } from "@svar-ui/svelte-filter";

  const { fields, data } = getData();
</script>

<FilterQuery {fields} options={getOptionsMap(data)}/>

For fields with a known set of values, pass an options object keyed by field ID. The component uses these as autocomplete suggestions when the cursor is in value position.

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

  const fields = [
    { id: "first_name", label: "First Name", type: "text" },
    { id: "country",    label: "Country",    type: "text" },
    { id: "age",        label: "Age",         type: "number" },
  ];

  const options = {
    first_name: ["Alex", "Daisy", "John", "Jane"],
    country:    ["USA", "China", "Germany"],
    age:        [24, 33, 44, 62],
  };
</script>

<FilterQuery {fields} {options} />

If a field accepts open-ended values, omit its key from the options object. The component will still parse typed values, but it won't show autocomplete suggestions for that field.

Tag suggestions

The special "#" key in the options hash provides suggestions for tag-style queries (#Urgent, #todo). Tags match exactly against any field, regardless of which field it belongs to.

<script>
  const options = {
    country: ["USA", "Germany"],
    "#":     ["urgent", "todo", "review", "blocked"],
  };
</script>

<FilterQuery {fields} {options} />

When the user types #, the dropdown shows values from the "#" key. This works well for status labels or priority flags that cut across multiple fields.

Field labels vs IDs

The component keeps two representations of the query in sync at all times:

• The input text uses field labels — what the user sees and types (FirstName: Alex)
• The value prop uses field IDs — the stored form (first_name: Alex)

When the user selects First Name from the dropdown, the component inserts FirstName (the sanitized label) into the input and simultaneously writes first_name: Alex to value. When you set value externally, the component converts IDs back to labels before displaying the query.

This keeps stored query strings compact and stable while users always see readable field names in the input.

Label sanitization

The component strips parser-special characters from labels before using them in the query text. "First Name" becomes FirstName (space removed); "Created (at)" becomes Createdat (space and parentheses removed). The stripped characters include whitespace, :, ,, ", ', (, ), #, -, *, >, <, =, and ..

Date predicates work with sanitized labels: StartDate.year: 2024 resolves correctly to field start with predicate year.

Pre-populating the query

Set the value prop using field IDs to pre-fill the input. The component converts them to labels on display:

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

  const fields = [
    { id: "first_name", label: "First Name", type: "text" },
    { id: "country",    label: "Country",    type: "text" },
  ];

  // Stored in ID form; displays as "FirstName: Alex and Country: USA"
  let value = $state("first_name: Alex and country: USA");
</script>

<FilterQuery {fields} bind:value />

Both the label and the ID are accepted in typed input. Users can type either form, and the component resolves it to the same field.