Skip to main content

onchange

Description​

Fires when the user presses Enter or clicks the search button or value is set externally

Use it to receive the parsed filter config and apply it to your data or forward it to a backend.

Usage​

interface IRule {
  field?: string | number;
  type?: "number" | "text" | "date" | "tuple";
  predicate?: "month" | "year";
  filter?: string;
  includes?: any[];
  value?: any;

  rules?: IRule[];
  glue?: "and" | "or";
}

interface ValidationError {
  code: "UNKNOWN_FIELD"|"EXPECTED_NUMBER"|"EXPECTED_DATE"|"PARSE_ERROR"|"NO_DATA";
  field?: string;
  value?: string;
  message?: string;
}

onchange:(ev: {
  value: string | IRule | null;
  text: string;
  parsed?: {
    config: IRule | null;
    isInvalid: boolean | ValidationError;
    startOperation: string | null;
    tokens: {
      type: "field"| "value"| "operator"| "textop"
        |"comparison"| "symbol"| "wildcard"| "negation"| "hash"| "error";
      start: number;
      end: number;
      invalid?: boolean;
    }[];
    naturalText: string | null;
  };
  error?: ValidationError | null;
  startProgress: () => void;
  endProgress: () => void;
 }
) => void;

Parameters​

  • value - (required) the current filter value. Its type depends on the parse prop:
    • "none" — a free text string
    • "strict" or "allowFreeText" — a single filtering rule or a set of filtering rules or null`
  • text - (required) normalized query text using field labels (not IDs), suitable for display or storage
  • parsed - (optional) full parse result. Present only when parse != "none". Contains:
    • config — (required) structured filter config which is a single filtering rule or a set of filtering rules or null
    • naturalText (string) — (required) normalized query text
    • isInvalid (ValidationError | false) — (required) validation error, or false if the query is valid
    • tokens - (required) token stream array. Each token contains:
      • type - (required) token type: "field", "value", "operator", "textop", "comparison", "symbol", "wildcard", "negation", "hash", or "error"
      • start - (required) start position of the token in the query string (number)
      • end - (required) end position of the token in the query string (number)
      • invalid - (optional) true if the token failed validation (boolean)
  • error (ValidationError | null) - (optional) present when parse != "none" and the query fails validation; null when the query is valid or empty
  • startProgress - (required) call to show the inline progress bar during async operations (e.g. backend requests)
  • endProgress - (required) call to hide the inline progress bar once the async operation completes

ValidationError contains:

  • code — (required) validation error code: "NO_DATA", "UNKNOWN_FIELD", "EXPECTED_NUMBER", "EXPECTED_DATE", "PARSE_ERROR"
  • field — (optional) field name for which the error occurred
  • value — (optional) field value for which the error occurred
  • message — (optional) localized, human-readable error description ready to display

When error.code is "NO_DATA", the filter is structurally valid but matches no records. value is still a filtering rule and safe to apply and it will return an empty result set. For all other error codes, value may be null.

Example​

Filtering a local array and showing a notification on error:

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

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

  const data = getData();
  let filteredData = $state(data);

  function handleFilter({ value, error }) {
    if (error) {
      console.warn(error.message);
      if (error.code !== "NO_DATA") return;
    }

    const filter = createArrayFilter(value, {}, fields);
    filteredData = filter(data);
  }
</script>

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

For async operations such as backend requests, use startProgress and endProgress to show the progress bar while the request is in progress:

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

  const { fields, options, data } = getData();
  let filteredData = $state(data);

  async function handleFilter({ value, error, startProgress, endProgress }) {
    if (error && error.code !== "NO_DATA") return;

    try {
      startProgress();
      const results = await fetchFiltered(value);
      filteredData = results;
    } finally {
      endProgress();
    }
  }
</script>

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

Details​

The onchange action fires whenever the user submits a query — by pressing Enter, clicking the search button, or when a value is set programmatically.

The value field is the primary output. When parsing is enabled, it contains a structured filtering rule that can be passed directly to createArrayFilter or serialized to a backend. When parse="none", it is a plain string.

Use the error field to check validity before applying a filter. An error.code of "NO_DATA" is informational — the query parsed successfully but will return no results. All other codes indicate a malformed or unrecognized query, and value should not be applied.

The startProgress and endProgress functions control a progress indicator in the component header. Call them around any asynchronous operation, such as a debounced API request or an AI-powered filtering step, to give users visual feedback.

Related articles: