Configuration

All SVAR filtering widgets (FilterBuilder, FilterBar, FilterEditor) rely on a common configuration model that defines:

• The description of the fields for filtering
• The types of filters available for each field type
• How filter options are provided
• How rules are constructed and processed
• Special handling for numeric and date filters

This section outlines the shared configuration concepts across all filter components. For a quick overview of what each component is best for, see When to use each component.

To enable filtering with any component you need to:

• List data fields or a single field that are used for filtering
• Provide options for each field: an array of data the end users can choose from
• Track value changes to create client-side filtering functions or SQL queries on the server side

Filter fields

The fields array defines all the fields users can filter on. Each object in the array should specify:

• id - a unique identifier for the field (must match your data keys)
• label - the human-readable label used in the UI
• type - the type of the filter you want for this field
  • text - for string values
  • number - for numeric values filtered with an input
  • tuple - for numeric values filtered with a dropdown
  • select - for FilterBar options
• format - display format for number, tuple and date filters

Example:

<script>
  import { FilterBuilder } from "wx-svelte-filter";
  const fields = [
    { id: "first_name", label: "First Name", type: "text"},
    { id: "age", label: "Age", type: "number"},
    { id: "start", label: "Start Date", type: "date", format: "%y-%m-%d" }
  ];
</script>

<FilterBuilder {fields} /> 

While FilterBuilder widget works with multiple fields, FilterEditor typically has only one of them, so field settings are passed directly as properties:

<script>
  import { FilterEditor } from "wx-svelte-filter";
</script>

<FilterEditor field={"start"} type={"date"} format={"%y-%m-%d"}/> 

Filter types and operators

Each field in the fields configuration must contain a filter type, which determines the input UI and available comparison operators.

Type	Input UI	Description	Supported Filters
text	Text input	Freeform string input	contains, notContains, equal, notEqual, beginsWith, notBeginsWith, endsWith, notEndsWith
number	Number input	Integer or decimal input	greater, less, greaterOrEqual, lessOrEqual, equal, notEqual, contains, notContains, beginsWith, notBeginsWith, endsWith, notEndsWith
date	Date picker / range calendar	Date or range selector	greater, less, greaterOrEqual, lessOrEqual, equal, notEqual, between, notBetween
tuple	Dropdown	List of numbers with formatted values	greater, less, greaterOrEqual, lessOrEqual, equal, notEqual

Example:

<script>
  import { FilterBuilder } from "wx-svelte-filter";

  const fields = [
    { id: "first_name", label: "First Name", type: "text" },
    { id: "age", label: "Age", type: "number" },
    { id: "start", label: "Start Date", type: "date"},
    { id: "month", label: "Month", type: "tuple", format:getMonth }
  ];

  const value = {
    glue: "and",
    rules: [
      { field: "first_name", filter:"contains", value: "a"},
      { field: "age", filter:"greater", value: 21},
      { field: "start", filter:"not equal", value: new Date(14, 5, 1999)},
      { field: "month", filter:"less", value: 5},
    ]
  };

  function onChange({ value }) {
    console.log("Updated filter rules:", value);
  }
</script>

<FilterBuilder {fields} {value} onchange={onChange} />

Filter options

Options for Filter widgets represent all possible values of their fields.

FilterBuilder works with multiple fields, so its options contain the object with field ids as keys:

<script>
  import { FilterBuilder } from "wx-svelte-filter";

  const fields = [
    { id: "first_name", label: "Name", type: "text" },
    { id: "age", label: "Age", type: "number" },
    { id: "start", label: "Start Date", type: "date"},
  ];

  const options = {
    first_name: [ "Alex", "Adam", "John", "Jane"],
    age: [ 17, 21, 35, 42]
    start: [ new Date(2025, 4, 7), new Date(2025, 4, 10)]
  };
</script>

<FilterBuilder {fields} {options} />  

FilterEditor works with a single field at a time, so its options contain an array of possible values for this field:

<script>
  import { FilterEditor } from "wx-svelte-filter";

  const options = [ "Alex","Adam", "John", "Jane"];
</script>

<FilterEditor field={"first_name"} {options} />  

Options for FilterBuilder and FilterEditor can be collected from the array of data to filter. Use getOptionsMap or getOptions helpers correspondingly.

Rule structure

Filter widgets can visualize, create and edit filtering rules. A single rule describes one condition and contains:

• field - field identifier from the fields array
• filter - comparison operator, depends on filter type
• value - value to compare
• type - (optional) filter type. If not provided, can be taken from the fields array
• includes - (optional) an array of exact matches. If stated, overrides filter / value pair

Rules combined with AND or OR glue:

{
  glue: "and", // or "or"
  rules: [
    { field: "country", filter: "equal", value: "USA" },
    { field: "age", filter: "greater", value: 25 }
  ]
}

Groups can be nested for complex query logic. This example demonstrates three levels of grouping, mixing "and" "or" glues:

{
  glue: "and",
  rules: [
    {
      glue: "or",
      rules: [
        { field: "first_name", filter: "contains", value: "Alex" },
        {
          glue: "and",
          rules: [
            { field: "last_name", filter: "contains", value: "Smith" },
            { field: "age", filter: "greater", value: 40 }
          ]
        }
      ]
    },
    { field: "country", filter: "equal", value: "USA" }
  ]
};

Working with dates

Filter widgets work with valid JavaScript Date objects. If you have date strings in your data, you need to parse them to objects before defining options or value.

By default, dates are formatted in UI according to the current locale. If you need a specific display format for certain fields, set it via the format property in the fields configuration.

Output value with rules contains Date objects, so you will need to format them before sending to server.

const fields = [
  { id:"start", label: "Start Date", type:"date" }
];

const value = {
  rules: [
    {
      field: "start",
      filter: "greater",
      value: new Date(2024, 4, 21), 
      type: "date"
    }
  ]
};

const options = { 
  start:[ new Date(2024, 4, 21), new Date(2024, 8, 5)]
};

To extract only year and month parts for field options and filter them as numbers, pass a predicate into the getOptions / getOptionsMap helpers:

const data = [
  { start: new Date(2025, 0, 3) },
	{	start: new Date(2025, 2, 13) },
];

const options =  getOptionsMap(data, config:[
  {id:"start", predicate: "month" }
]);
// { start: [0, 2]}

const fields = [
  { id:"start", label:"Start Month", type:"number"}
]

Data formatting

You can use the format property on a field to control how values are displayed in the UI.

Supported format types:

Field Type	Accepted format value	Description
number	(value: number) => string	Formats numbers (e.g., 1000 → "1,000")
tuple	(value: any) => string	Maps numbers to human-readable labels in a dropdown list
date	string or (date: Date) => string	Formats dates by providing a format string or custom function

Format date value with a built-in formatter by providing a string format according to the rules:

<script>
  import { FilterEditor } from "wx-svelte-filter";
</script>

<FilterEditor type="date" {options} format={"%Y-%m-%d"} />

Format date values using a custom formatter:

<script>
  import { FilterEditor } from "wx-svelte-filter";

  const formatDate = (date) =>
    new Intl.DateTimeFormat("en-GB").format(new Date(date));
  const options = [ new Date(2024, 4, 21), new Date(2024, 8, 5)];
</script>

<FilterEditor type="date" {options} format={formatDate} />

Format month numbers to month names for tuple filter:

<script>
  import { FilterEditor } from "wx-svelte-filter";
  import { en } from "wx-core-locales";
 
  const options = [0, 1, 2]; // months
  const numberToMonth = (v) => en.calendar.monthFull[v]; // "January", "February", etc.
</script>

<FilterEditor type="tuple" {options} format={numberToMonth} />

Format numbers with commas in number filter:

<script>
  import { FilterEditor } from "wx-svelte-filter";

  const formatNumber = (n) => n.toLocaleString(); // 1000 -> "1,000"
  const options = [1548, 1000, 1654];
</script>

<FilterEditor type="number" {options} format={formatNumber} />

How to apply filter to data

The Filter components do not apply the filters automatically. To apply filters to an array of data, use the createArrayFilter helper. This helper returns a filtering function based on the current filter structure, which you can use to filter your dataset.

<script>
  import { FilterBuilder, createArrayFilter } from "wx-svelte-filter";

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

  const data = [
    { first_name: "Alice", age: 30 },
    { first_name: "Bob", age: 20 },
  ];

  let filteredData = [];

  function applyFilter(value) {
    const filter = createArrayFilter(value);
    filteredData = filter(data);
  }

  applyFilter(value);
</script>

<FilterBuilder {fields} onchange={({ value }) => applyFilter(value)} />