SearchField

Explicit/debounced query policy; composition input is not submitted mid-IME.

FamilyinputLicenseApache-2.0

StandaloneAvailable

Use the web element directly without the semantic runtime.

Semantic bindingAvailable

A registered presentation adapter can bind this component to host-owned meaning and state.

Automatic adaptationNo standard recipe

The standard recipe resolver does not select this component automatically.

Import and live example

One report search field with a debounced query-on-input policy.

Interactive preview requires JavaScript.

View the complete example source

import {registerAeliqoElements} from "@varendo/web";
import {
  AeliqoCheckboxElement,
  AeliqoComboboxElement,
  AeliqoDateFieldElement,
  AeliqoDateRangeElement,
  AeliqoFieldGroupElement,
  AeliqoFileInputElement,
  AeliqoFormElement,
  AeliqoNumberFieldElement,
  AeliqoRadioGroupElement,
  AeliqoSearchFieldElement,
  AeliqoSelectElement,
  AeliqoSliderElement,
  AeliqoSwitchElement,
  AeliqoTextAreaElement,
  AeliqoTextFieldElement,
  type AeliqoOption,
} from "@varendo/web/inputs";

const options: readonly AeliqoOption[] = [
  {value: "ada", label: "Ada Lovelace", description: "Research"},
  {value: "grace", label: "Grace Hopper", description: "Product"},
  {value: "lin", label: "Lin Chen", disabled: true},
];

registerAeliqoElements();

const host = document.querySelector<HTMLElement>("#aeliqo-example") ?? (() => {
  const created = document.createElement("div");
  created.id = "aeliqo-example";
  (document.body ?? document.documentElement).append(created);
  return created;
})();

function createCatalogRoot(container: HTMLElement): HTMLElement {
  const root = document.createElement("div");
  root.dataset.catalogSourceRoot = "true";
  root.style.display = "grid";
  root.style.gap = "12px";
  container.append(root);
  return root;
}

function createCatalogElement<T extends HTMLElement>(tagName: string, container: HTMLElement): T {
  const element = document.createElement(tagName) as T;
  element.setAttribute("data-aeliqo-theme", "light");
  container.append(element);
  return element;
}

function appendSlottedText(root: HTMLElement, slot: string, textContent: string): void {
  const content = document.createElement("span");
  content.slot = slot;
  content.textContent = textContent;
  root.append(content);
}

const root = createCatalogRoot(host);
(((root) => {
		const element = createCatalogElement<AeliqoSearchFieldElement>("aeliqo-search-field", root);
		element.label = "Search reports";
		element.name = "query";
		element.value = "retention";
		element.queryOnInput = true;
		element.debounceMs = 150;
		element.placeholder = "Search by name";
	}))(root);

Purpose

A search field whose local value is the query. The host can set it; user input updates it and emits a search request on Enter or submitQuery(). With queryOnInput, typing debounces that request and IME composition never submits early. The host decides whether to run or persist the query.

When to use it

People type a query the host runs against its own data.
You want an explicit submit gesture, a debounce policy, or both.
The query text is the value; nothing is picked from a list.

When to use a different component

Use Combobox when the query must resolve to a known option.
Use TextField when the text is stored data, not a query.

Properties and defaults

The component emits a query proposal; the host decides whether and how to execute it.

Properties, ownership, and initial values
Property	Use and ownership	Declared type	Initial value
`label`	Provides the visible label and accessible name for the component.	`string`	`''`
`description`	Provides supporting text associated with the control or value.	`string`	`''`
`error`	Provides the current validation or operation error associated with the control.	`string`	`''`
`required`	Marks the control as required for validation and native accessibility semantics.	`boolean`	`false`
`disabled`	Prevents user interaction while keeping the control and its current value visible.	`boolean`	`false`
`readOnly`	Keeps the current value focusable and readable while preventing edits.	`boolean`	`false`
`name`	Provides the stable form or action name used by the host to identify this control.	`string`	`''`
`autocomplete`	Passes an autocomplete purpose to the native input so browsers can offer an appropriate saved value.	`string`	`'off'`
`locale`	Selects locale-sensitive formatting and parsing behavior.	`string`	`'en-US'`
`validationState`	Controls the current idle, pending, valid, or invalid validation state.	`AeliqoValidationState`	`'idle'`
`validator`	Runs host-provided synchronous validation for a proposed input value.	`AeliqoValidator<T> \| undefined`	`undefined`
`value`	Controls the current value. Apply accepted user proposals back to this property.	`string`	`''`
`defaultValue`	Provides the initial uncontrolled value. Later updates come from component interaction.	`string`	`''`
`inputType`	Supplies input type to the component as application-owned input.	`AeliqoTextFieldInputType`	`'text'`
`placeholder`	Provides a short input hint when the current draft is empty; it does not replace a visible label.	`string`	`''`
`maxLength`	Sets the upper bound for max length.	`inferred from initializer`	`-1`
`minLength`	Sets the lower bound for min length.	`inferred from initializer`	`-1`
`pattern`	Provides the native validation pattern for text input.	`string`	`''`
`inputMode`	Supplies input mode to the component as application-owned input.	`string`	`'text'`
`rows`	Supplies the bounded records to render. The component never fetches or widens this set.	`number`	`4`
`spellcheck`	Enables or disables browser spelling suggestions for text drafts.	`boolean`	`true`
`queryOnInput`	Chooses whether typing emits debounced search proposals before explicit commit.	`boolean`	`false`
`debounceMs`	Sets the delay before an input-driven search proposal is emitted.	`number`	`250`

Events

Events, payloads, timing, and application responsibilities
Event	Payload	Emitted	Application responsibility
`aeliqo-input-change`	`{source, value, composing?}`	Whenever the user proposes a draft value change.	Validate or store the draft and reassign controlled `value` or `checked` state.
`aeliqo-input-commit`	`{source, value}`	After explicit commit, blur, or Enter where the control supports it.	Accept or reject the committed value and update authoritative form state.
`aeliqo-search`	`{source, query}`	After an explicit search commit or valid debounced input.	Execute a bounded authorized search and update result revision and rows.
`aeliqo-validation`	`{source, state, message}`	When validation enters pending, valid, or invalid state.	Merge the result with application validation and display authoritative errors.

Events cross the component boundary as user proposals. Validate their detail and current authority before applying a business effect.

Listen for `aeliqo-input-change`

TypeScript example

const element = document.querySelector('aeliqo-search-field');<p>element?.addEventListener('aeliqo-input-change', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

Listen for `aeliqo-input-commit`

TypeScript example

const element = document.querySelector('aeliqo-search-field');</p>
<p>element?.addEventListener('aeliqo-input-commit', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

Listen for `aeliqo-search`

TypeScript example

const element = document.querySelector('aeliqo-search-field');</p>
<p>element?.addEventListener('aeliqo-search', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

Listen for `aeliqo-validation`

TypeScript example

const element = document.querySelector('aeliqo-search-field');</p>
<p>element?.addEventListener('aeliqo-validation', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

States and failure handling

Relevant states:

ready
disabled
invalid
pending

Expected result: The query draft is editable and emits bounded search proposals without owning data access.

The default queryOnInput value is false. When enabled, debounceMs is clamped to 0–10,000 milliseconds (250 by default); a host-driven value change or disconnection cancels a pending timer. The component emits a query proposal, never performs the search or decides whether zero results means empty data, a denied source, or a failed request.

Keyboard, focus, and accessibility

Keyboard behavior:

Tab
Type and edit
Enter
Escape
IME composition

Exposed semantics:

aria-describedby
aria-invalid
aria-readonly
input
role
textarea

Responsive behavior

Let the query field use the available row width. Keep search policy and empty feedback visible when the form stacks.

Style hooks

Shadow parts: description, error, field, input, label, pending
Varendo design tokens referenced: --aeliqo-color-muted

Performance limits

Public workload controls: `maxLength` (default -1).

Generated TypeScript declaration

View generated declaration

export declare class AeliqoSearchFieldElement extends AeliqoTextFieldElement {
    static readonly properties: {
        label: {
            type: StringConstructor;
        };
        description: {
            type: StringConstructor;
        };
        error: {
            type: StringConstructor;
        };
        required: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        disabled: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        readOnly: {
            attribute: string;
            type: BooleanConstructor;
            reflect: boolean;
        };
        name: {
            type: StringConstructor;
            reflect: boolean;
        };
        autocomplete: {
            type: StringConstructor;
        };
        locale: {
            type: StringConstructor;
        };
        validationState: {
            attribute: string;
            type: StringConstructor;
            reflect: boolean;
        };
        validator: {
            attribute: boolean;
        };
        value: {
            type: StringConstructor;
            reflect: boolean;
        };
        defaultValue: {
            attribute: string;
            type: StringConstructor;
        };
        inputType: {
            attribute: string;
            type: StringConstructor;
        };
        placeholder: {
            type: StringConstructor;
        };
        maxLength: {
            attribute: string;
            type: NumberConstructor;
        };
        minLength: {
            attribute: string;
            type: NumberConstructor;
        };
        pattern: {
            type: StringConstructor;
        };
        inputMode: {
            attribute: string;
            type: StringConstructor;
        };
        rows: {
            type: NumberConstructor;
        };
        spellcheck: {
            type: BooleanConstructor;
        };
        queryOnInput: {
            attribute: string;
            type: BooleanConstructor;
        };
        debounceMs: {
            attribute: string;
            type: NumberConstructor;
        };
    };
    queryOnInput: boolean;
    debounceMs: number;
    private queryTimer;
    private compositionActive;
    private userValueChange;
    connectedCallback(): void;
    disconnectedCallback(): void;
    protected willUpdate(changed: PropertyValues<this>): void;
    /** Commit the current query from a host action or a keyboard Enter. */
    submitQuery(): void;
    private readonly handleProposal;
    private readonly handleSearchCompositionStart;
    private readonly handleSearchCompositionEnd;
    private readonly handleSearchKeyDown;
    private scheduleQuery;
    private clearQueryTimer;
}

Version

This page documents the Varendo 0.6 component contract.

Import and live example#

Purpose#

When to use it#

When to use a different component#

Properties and defaults#

Events#

Listen for aeliqo-input-change

Listen for aeliqo-input-commit

Listen for aeliqo-search

Listen for aeliqo-validation

States and failure handling#

Keyboard, focus, and accessibility#

Responsive behavior#

Style hooks#

Performance limits#

Related components#

Generated TypeScript declaration#

Version#

Import and live example

Purpose

When to use it

When to use a different component

Properties and defaults

Events

Listen for `aeliqo-input-change`

Listen for `aeliqo-input-commit`

Listen for `aeliqo-search`

Listen for `aeliqo-validation`

States and failure handling

Keyboard, focus, and accessibility

Responsive behavior

Style hooks

Performance limits

Related components

Generated TypeScript declaration

Version