getQueryHtml

Description

Converts a FilterQuery query string into an HTML string with inline style spans for syntax coloring.

Returns an empty string for empty input.

Usage

getQueryHtml(
  text: string, 
  config?: {
    fields?: IField[];
    options?: IDataHash<AnyData[]>;
    showErrors?: boolean | number;                  
    cursorPos?: number;                                           
    allowFreeText?: boolean;
  }
): string;

Parameters

• text: string — (required) text value from the FilerQuery input
• config — (optional) an object with configuration options:
  • fields? - (opitional) field definitions object with the next parameters:
    • id: string — field identifier used in query syntax
    • label: string — display label of the field
    • type: "number" | "text" | "date" | "tuple" — field data type
    • predicate?: "month" | "year" | "yearMonth" — optional date predicate used when filtering date fields
    • format?: string | ((value: AnyData) => string) — optional formatter for displaying field values
  • options?: IDataHash<AnyData[]> - (opitional) options definitions. A hash of available values per field used for value validation and autocomplete suggestions.
    Example:

    {
      status: ["Open", "Closed", "Pending"]
    }

  • showErrors - controls when error styling appears:
    • true — always highlight invalid tokens
    • false — never highlight errors
    • number — suppress error highlighting at the specified cursor position
  • cursorPos - (opitional) cursor position for active-token detection. Used together with showErrors to avoid highlighting the token the user is currently editing.
  • allowFreeText - (opitional) if true, skips highlighting for plain text that has no query syntax

Details

Behavior:

When allowFreeText is true, highlighting is skipped entirely (returns escaped plain text) unless the input starts with field:, #tag, or (.

Error tokens get a wavy underline. When showErrors is a cursor position, error styling is suppressed on the token under the cursor, the one the user is currently editing.

Colors are CSS custom properties with hex fallbacks:

--wx-filter-query-field-color, #2563eb

--wx-filter-query-value-color, #16a34a

--wx-filter-query-operator-color, #9333ea

--wx-filter-query-operator-color, #9333ea

--wx-filter-query-comparison-color, #ea580c

--wx-filter-query-symbol-color, #6b7280

--wx-filter-query-symbol-color, #6b7280

--wx-filter-query-negation-color, #dc2626

--wx-filter-query-symbol-color, #6b7280

--wx-filter-query-error-color, #dc2626

Example

Render a syntax-highlighted query in a contenteditable div:

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

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

  let query = $state("status: Open and age: >25");
  let cursorPos = $state(-1);

  function handleInput(e) {
    query = e.target.innerText;
    cursorPos = e.target.selectionEnd ?? -1;
  }

  let html = $derived(
    getQueryHtml(query, {
      fields,
      showErrors: cursorPos,
      cursorPos,
    })
  );
</script>

<div
  contenteditable="true"
  oninput={handleInput}
>{@html html}</div>

With allowFreeText enabled, plain words not matching query syntax are returned unstyled:

getQueryHtml("hello world", { allowFreeText: true });
// → "hello world"  (HTML-escaped, no spans)

getQueryHtml("status: Open", { allowFreeText: true });
// → highlighted HTML with colored spans

---

Related articles:

• Query syntax
• Styling