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

## Attributes

- `checked` (boolean): Whether the switch starts on. Like a native checkbox's checked attribute, this is the reset default; the checked property is live state. Default: `false`.
- `disabled` (boolean): Disables the switch. Default: `false`.
- `required` (boolean): The form cannot submit until the switch is on. Default: `false`.
- `name` (string): Form field name. The switch submits name=value when on and nothing when off.
- `value` (string): Value submitted when the switch is on. Default: `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()`: Flips the switch, as a click on it would.
- `focus()`: Moves focus to the native checkbox.
- `checkValidity()`: Runs native constraint validation.
- `reportValidity()`: Runs native constraint validation and shows the browser's message.
- `setCustomValidity()`: 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.

## Accessibility obligations

- (error, switch-label) 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").
- (warn, switch-form-name) 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.
- (warn, switch-state-name) 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.

## Examples

### In a field

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

```html
<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

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

## Mistakes

### 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 (aihio lint: switch-label):

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

Do:

```html
<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 lint: switch-state-name):

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

Do:

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

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

Do:

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