Skip to content
Aihio v2.3.0
Search
GitHub
Search Describe what you are building, or name a component, intent, or token. Components and patterns are ranked the way the MCP server's find tool ranks them for an agent.

<aihio-switch> v1.0.0 Markdown for agents

Switch

An on/off setting that submits with its form, such as Email notifications on a settings page. Renders a real <input type="checkbox" role="switch">. Put it inside aihio-field for a label and description; for a pressed state in a toolbar (Bold, Italic) use aihio-toggle instead.

Intents form-field toggle-state

Examples

Each one rendered live, over the markup that produces it.

In a field

Laid out as a row beside its label, with a description beneath.

A digest of activity, sent weekly. 
<aihio-field>
  <label slot="label">Email notifications</label>
  <aihio-switch name="email-notifications" checked></aihio-switch>
  <span slot="description">A digest of activity, sent weekly.</span>
</aihio-field>

Wrapped in a label

<label>
  <aihio-switch name="remember"></aihio-switch>
  Remember this device
</label>

Mistakes

Each one beside its fix, with what aihio lint says about it. The prompt fragment gives agents the same pairs, and the build fails if the linter stops catching one or a fix stops passing.

The visible text is not associated with the switch, so it is announced as an unnamed switch.

Use aihio-field with <label slot="label">, or wrap both in a <label>.

Don't

<span>Email notifications</span>
<aihio-switch name="email-notifications"></aihio-switch>

aihio lint reports

  • switch-label error Name the switch after the setting it controls: put it in aihio-field with a <label slot="label">, wrap it in a <label>, or give it aria-label. Never label it with its state ("On", "Enabled").

Do

<aihio-field>
  <label slot="label">Email notifications</label>
  <aihio-switch name="email-notifications"></aihio-switch>
</aihio-field>

A switch named by its state is announced as "On, switch, on".

Name it after the setting it controls.

Don't

<aihio-switch aria-label="On" checked></aihio-switch>

aihio lint reports

  • switch-state-name warn Name the switch after the setting it controls. The switch announces its own state, so a switch named "On" is read as "On, switch, on" and never says what is on.

Do

<aihio-switch aria-label="Email notifications" checked></aihio-switch>

Boolean attributes are on by presence. checked="false" starts the switch on; omit the attribute for off.

Don't

<aihio-switch checked="false" aria-label="Weekly summary"></aihio-switch>

aihio lint reports

  • boolean-attribute-value error checked="false" turns checked on: a boolean attribute is on whenever it is present, whatever its value. Remove it for off.

Do

<aihio-switch aria-label="Weekly summary"></aihio-switch>

API

Every attribute, property, method, and event the schema declares for aihio-switch.

Attributes

checked
boolean default false
Whether the switch starts on. Like a native checkbox's checked attribute, this is the reset default; the checked property is live state.
disabled
boolean default false
Disables the switch
required
boolean default false
The form cannot submit until the switch is on
name
string
Form field name. The switch submits name=value when on and nothing when off.
value
string default on
Value submitted when the switch is on
form
string
Id of an external form that owns the switch

Properties

checked
boolean
Live on/off state
defaultChecked
boolean
Reset state; reflects the checked attribute
control
HTMLInputElement | null read-only
The native checkbox the component delegates to
form
HTMLFormElement | null read-only
The owning form, or null outside one
validity
ValidityState | null read-only
Native constraint validation state
validationMessage
string read-only
Native validation message
willValidate
boolean read-only
Whether the switch takes part in constraint validation

Methods

click(): void
Flips the switch, as a click on it would.
focus(options?: FocusOptions): void
Moves focus to the native checkbox.
checkValidity(): boolean
Runs native constraint validation.
reportValidity(): boolean
Runs native constraint validation and shows the browser's message.
setCustomValidity(message: string): void
Sets a custom validation message; an empty string clears it.

Events

aihio-change
detail { checked: boolean }
Fired when the user turns the switch on or off. The native change and input events also bubble from the inner checkbox.

Composition

Allowed children
none

Accessibility

What you have to provide, and what the component already does. The obligations with a rule are checked by aihio lint and by the dev build's console warnings.

Your obligations

  • error When the switch has no label

    Name the switch after the setting it controls: put it in aihio-field with a <label slot="label">, wrap it in a <label>, or give it aria-label. Never label it with its state ("On", "Enabled").

    Checked as switch-label

  • warn When the switch is inside a <form> and its state should be submitted

    Set name. A switch without a name is omitted from FormData entirely.

    Checked as switch-form-name

  • warn When the switch is named by a state word (On, Off, Enabled)

    Name the switch after the setting it controls. The switch announces its own state, so a switch named "On" is read as "On, switch, on" and never says what is on.

    Checked as switch-state-name

Handled for you

  • The component renders a real <input type="checkbox" role="switch">, so Space toggles it, it is announced as a switch that is on or off, and focus and disabled semantics are native
  • Form participation is native: it submits name=value when on, resets with its form, and <fieldset disabled> disables it
  • aria-label, aria-labelledby, aria-describedby, and aria-invalid set on the host are forwarded to the checkbox
  • Inside aihio-field the label, description, and error are wired to the checkbox, and the field lays out as a row with the switch beside its label
  • On and off stay distinguishable under forced colours: the track keeps a border and the on state uses Highlight

In patterns

Canonical compositions that use aihio-switch.