# <aihio-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`.

## Attributes

- `pressed` (boolean): Whether the toggle is pressed. Default: `false`.
- `disabled` (boolean): Disables the toggle. Default: `false`.
- `variant` (`default` | `outline`): Visual style variant. Default: `default`.
- `size` (`sm` | `md` | `lg`): Toggle size. Default: `md`.

## 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()`: Activates the native button, toggling the pressed state.
- `focus()`: Moves focus to the native button.
- `blur()`: Removes focus from the native button.

## Events

- `aihio-toggle` (detail: pressed: boolean): Fired when the pressed state changes.

## Slots

- `default`: Toggle label content.

## Accessibility obligations

- (error, toggle-accessible-name) When toggle has no visible text (icon-only): Provide aria-label describing what the toggle controls (e.g. aria-label="Bold").
- (warn, toggle-state-name) 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.

## Examples

### Unpressed

```html
<aihio-toggle>Bold</aihio-toggle>
```

### Pressed and outlined

pressed is a boolean attribute: present means on.

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

## Mistakes

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

Don't (aihio lint: forbidden-descendant):

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

Do:

```html
<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 lint: boolean-attribute-value):

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

Do:

```html
<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 (aihio lint: toggle-state-name):

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

Do:

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