Varendo

Select

Bounded enumerated choice with native-first semantics; empty and unknown value are distinct.

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 closed team select with a bounded option list and placeholder label.

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<AeliqoSelectElement>("aeliqo-select", root);
		element.label = "Team";
		element.name = "team";
		element.options = [
			{ value: "research", label: "Research" },
			{ value: "product", label: "Product" }
		];
		element.value = "research";
		element.emptyLabel = "Choose a team";
	}))(root);

Purpose

A bounded choice with a styled trigger and chevron; the option popup and keyboard stay native. The host can set value; choosing an option updates that local property and emits a typed change. An empty value is no selection, and an unknown value stays visible instead of picking another option; the host decides what to persist.

When to use it

When to use a different component

Properties and defaults

The host supplies the complete bounded options and controls selected value semantics.

Properties, ownership, and initial values
PropertyUse and ownershipDeclared typeInitial value
labelProvides the visible label and accessible name for the component.string''
descriptionProvides supporting text associated with the control or value.string''
errorProvides the current validation or operation error associated with the control.string''
requiredMarks the control as required for validation and native accessibility semantics.booleanfalse
disabledPrevents user interaction while keeping the control and its current value visible.booleanfalse
readOnlyKeeps the current value focusable and readable while preventing edits.booleanfalse
nameProvides the stable form or action name used by the host to identify this control.string''
autocompletePasses an autocomplete purpose to the native input so browsers can offer an appropriate saved value.string'off'
localeSelects locale-sensitive formatting and parsing behavior.string'en-US'
validationStateControls the current idle, pending, valid, or invalid validation state.AeliqoValidationState'idle'
validatorRuns host-provided synchronous validation for a proposed input value.AeliqoValidator<T> | undefinedundefined
optionsSupplies the complete bounded choice list, including stable values, labels, descriptions, and disabled states.readonly AeliqoOption[][]
valueControls the current value. Apply accepted user proposals back to this property.string''
defaultValueProvides the initial uncontrolled value. Later updates come from component interaction.string''
emptyLabelProvides the text shown when no value or row is available.string'Select an option'
unknownLabelProvides recovery text when a controlled select value is absent from the supplied options.string'Unknown option'

Events

Events, payloads, timing, and application responsibilities
EventPayloadEmittedApplication 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-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-select');<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-validation

TypeScript example
const element = document.querySelector('aeliqo-select');</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:

Expected result: The selected team remains one of the supplied options and emits a typed change.

Changing value or replacing validator cancels validation for the previous value and clears its validator-owned error. An independently supplied host error survives the change. Late results after a reset or disconnect are ignored.

Keyboard, focus, and accessibility

Keyboard behavior:

Exposed semantics:

Responsive behavior

Give the field enough width to show its selected label. Keep options bounded so the list fits the visible viewport.

Style hooks

Generated TypeScript declaration

View generated declaration
export declare class AeliqoSelectElement extends AeliqoFieldElement<string> {
    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;
        };
        options: {
            attribute: boolean;
        };
        value: {
            type: StringConstructor;
            reflect: boolean;
        };
        defaultValue: {
            attribute: string;
            type: StringConstructor;
        };
        emptyLabel: {
            attribute: string;
            type: StringConstructor;
        };
        unknownLabel: {
            attribute: string;
            type: StringConstructor;
        };
    };
    options: readonly AeliqoOption[];
    value: string;
    defaultValue: string;
    emptyLabel: string;
    unknownLabel: string;
    connectedCallback(): void;
    protected updated(): void;
    protected isCurrentValidationValue(value: string): boolean;
    protected resetField(): void;
    protected render(): import("lit").TemplateResult<1>;
    focus(options?: FocusOptions): void;
    private readonly handleChange;
    private native;
    private syncNative;
    static readonly styles: import("lit").CSSResult[];
}

Version

This page documents the Varendo 0.6 component contract.