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:

import { useState, useMemo } from "react";
import { getQueryHtml } from "@svar-ui/react-filter";

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

  const [query, setQuery] = useState("status: Open and age: >25");
  const [cursorPos, setCursorPos] = useState(-1);

  function handleInput(e) {
    setQuery(e.target.innerText);
    setCursorPos(e.target.selectionEnd ?? -1);
  }

  const html = useMemo(
    () => getQueryHtml(query, {
      fields,
      showErrors: cursorPos,
      cursorPos,
    }),
    [query, cursorPos]
  );

  return (
    <div
      contentEditable="true"
      onInput={handleInput}
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

export default App;

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