Checkbox

Native checked/indeterminate state; group ownership and submitted value are explicit.

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 unchecked archive-inclusion checkbox with a stable form name.

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<AeliqoCheckboxElement>("aeliqo-checkbox", root);
		element.label = "Include archived records";
		element.name = "includeArchived";
		element.value = "yes";
		element.checked = false;
	}))(root);

Purpose

A native checkbox for one checked value, with an explicit indeterminate display. The host can set checked; a user change updates that local property, clears indeterminate, and emits a typed change. The host decides what to retain or persist.

When to use it

You need a yes/no answer inside a submitted form.
One item can be included or excluded on its own.
The group needs an indeterminate state, such as a partial selection.

When to use a different component

Use Switch for a preference that takes effect outside form submission.
Use RadioGroup when the person must pick exactly one named option.

Properties and defaults

checked is the boolean state; value is the submitted token chosen by the host.

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`
`checked`	Controls the current boolean state. Update it from accepted change proposals.	`boolean`	`false`
`defaultChecked`	Provides the initial uncontrolled checked. Later updates come from component interaction.	`boolean`	`false`
`indeterminate`	Enables or disables indeterminate as explicit host-controlled state.	`boolean`	`false`
`value`	Controls the current value. Apply accepted user proposals back to this property.	`string`	`'on'`

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-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-checkbox');<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-checkbox');</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 checkbox exposes its checked state and emits a typed boolean change.

Changing checked 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:

Tab
Space

Exposed semantics:

aria-checked
aria-describedby
aria-invalid
aria-readonly
input
role

Responsive behavior

Let the label wrap beside the control without shrinking its target. Keep the text associated when fields stack.

Style hooks

Shadow parts: description, error, field, input, label, pending
Varendo design tokens referenced: --aeliqo-color-accent, --aeliqo-control-min-target, --aeliqo-space-8

Generated TypeScript declaration

View generated declaration

export declare class AeliqoCheckboxElement extends AeliqoFieldElement<boolean> {
    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;
        };
        checked: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        defaultChecked: {
            attribute: string;
            type: BooleanConstructor;
        };
        indeterminate: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        value: {
            type: StringConstructor;
        };
    };
    checked: boolean;
    defaultChecked: boolean;
    indeterminate: boolean;
    value: string;
    connectedCallback(): void;
    protected updated(): void;
    protected isCurrentValidationValue(value: boolean): boolean;
    protected resetField(): void;
    protected render(): import("lit").TemplateResult<1>;
    focus(options?: FocusOptions): void;
    protected readonly handleChange: (event: Event) => void;
    private native;
    private syncNative;
    static readonly styles: import("lit").CSSResult[];
}

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-validation

States and failure handling#

Keyboard, focus, and accessibility#

Responsive behavior#

Style hooks#

Related components#

Generated TypeScript declaration#

Version#