<aihio-toggle> v2.0.0 Markdown for agents

Toggle

A button that stays pressed or unpressed, such as Bold in a text toolbar. It renders a real <button aria-pressed>.

Intents toggle-state action

Variants

Every value of the attributes that change how it looks. The values come from the schema.

`variant`

Visual style variant

Default

variant="default"

Outline

variant="outline"

`size`

Toggle size

Size sm

size="sm"

Size md

size="md"

Size lg

size="lg"

Examples

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

Unpressed

Bold

<aihio-toggle>Bold</aihio-toggle>

Pressed and outlined

pressed is a boolean attribute: present means on.

Italic

<aihio-toggle pressed variant="outline">Italic</aihio-toggle>

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.

Nested interactives.

Use aihio-toggle alone — it already renders a button.

Don't

<aihio-toggle><aihio-button>B</aihio-button></aihio-toggle>

aihio lint reports

forbidden-descendant error descendant <aihio-button> is forbidden inside <aihio-toggle>.

<aihio-toggle aria-label="Bold">B</aihio-toggle>

Boolean attributes toggle on presence.

Omit the attribute for unpressed; write `pressed` for pressed.

Don't

<aihio-toggle pressed="false">Bold</aihio-toggle>

aihio lint reports

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

Bold

<aihio-toggle>Bold</aihio-toggle>

The toggle is named by its state and the visible label is not associated with it, so assistive technology announces "Enabled, toggle button, pressed" with no idea what is enabled.

An on/off setting is a switch: use aihio-switch in aihio-field, which also submits with the form.

Don't

<span>Email notifications</span>
<aihio-toggle pressed>Enabled</aihio-toggle>

aihio lint reports

toggle-state-name warn Name the toggle after what it controls (e.g. "Bold"), never after its state: a toggle labelled "Enabled" is announced as "Enabled, toggle button, pressed" and never says what is enabled. For an on/off setting in a form, use aihio-switch.

Email notifications

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

API

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

Attributes

pressed: boolean default false; Whether the toggle is pressed
disabled: boolean default false; Disables the toggle
variant: one of defaultoutline default default; Visual style variant
size: one of smmdlg default md; Toggle size

Properties

control: HTMLButtonElement | null read-only; The native button delegated to by the component
pressed: boolean; Whether the toggle is pressed; reflects the pressed attribute

Methods

click(): void: Activates the native button, toggling the pressed state.
focus(options?: FocusOptions): void: Moves focus to the native button.
blur(): void: Removes focus from the native button.

Events

aihio-toggle: detail { pressed: boolean }; Fired when the pressed state changes

Slots

default: Toggle label content

Composition

Forbidden descendants: aihio-button aihio-toggle aihio-input

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 toggle has no visible text (icon-only)

Provide aria-label describing what the toggle controls (e.g. aria-label="Bold").

Checked as toggle-accessible-name
warn When the toggle turns a setting on or off, or is named by a state word (On, Enabled)

Name the toggle after what it controls (e.g. "Bold"), never after its state: a toggle labelled "Enabled" is announced as "Enabled, toggle button, pressed" and never says what is enabled. For an on/off setting in a form, use aihio-switch.

Checked as toggle-state-name

Handled for you

The component renders a real <button> with aria-pressed, so the role, Enter and Space activation, focus behaviour, disabled semantics, and the forced-colours mapping are the platform's rather than an emulation of them
aria-pressed on that control reflects the pressed attribute
aria-* set on the host is mirrored onto the control
The control is always type="button", so a toggle inside a form never submits it