# <aihio-input>

A single-line text field (text, email, password, number, search, and the other native types) that submits with its form. Put it inside aihio-field to get a label, description, and error message.

Intents: `form-field`, `text-entry`.

## Attributes

- `type` (string): HTML input type (text, email, password, number, etc.). Default: `text`.
- `size` (`sm` | `md` | `lg`): Input size. Default: `md`.
- `placeholder` (string): Placeholder text.
- `disabled` (boolean): Disables the input. Default: `false`.
- `error` (boolean): Shows error styling. Default: `false`.
- `value` (string): Initial value.
- `name` (string): Form field name. Required for the value to appear in FormData — without it the field submits nothing.
- `required` (boolean): Marks the field required for native constraint validation. Default: `false`.
- `readonly` (boolean): Makes the field read-only while still submitting its value. Default: `false`.
- `autocomplete` (string): Forwarded to the inner input (e.g. email, current-password, one-time-code).
- `min` (string): Minimum value for number and date-like inputs.
- `max` (string): Maximum value for number and date-like inputs.
- `minlength` (number): Minimum permitted text length.
- `maxlength` (number): Maximum permitted text length.
- `pattern` (string): Regular expression the value must match.
- `step` (string): Permitted numeric or date step.
- `inputmode` (string): Hint for the virtual keyboard to display.
- `enterkeyhint` (string): Hint for the virtual keyboard Enter key label.
- `autocapitalize` (string): Automatic capitalization behavior.
- `spellcheck` (boolean): Whether spelling and grammar checking is enabled.
- `multiple` (boolean): Allows multiple values for supported input types.
- `accept` (string): Accepted file types when type=file.
- `capture` (string): Preferred capture source when type=file.
- `list` (string): Id of a datalist providing suggestions.
- `form` (string): Id of an external form that owns the input.

## Properties

- `value` (`string`): Get or set the current value.
- `defaultValue` (`string`): Get or set the reset value reflected by the value attribute.
- `control` (`HTMLInputElement | null`, read-only): The native input delegated to by the component.
- `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 control participates in constraint validation.

## Methods

- `checkValidity()`: Runs native constraint validation and returns whether the field is valid.
- `reportValidity()`: Runs native constraint validation and shows the browser message if invalid.
- `setCustomValidity()`: Sets a custom validation message.
- `select()`: Selects the input text.
- `focus()`: Moves focus to the native input.

## Events

- `aihio-input` (detail: value: string): Fired on every keystroke. The live value is available through detail and the value property; it is never copied into the value attribute.
- `aihio-change` (detail: value: string): Fired when the value is committed (blur or Enter).

## Accessibility obligations

- (error, input-label) When input has no visible <label> associated by for/id: Provide aria-label on aihio-input, or wrap in a <label>. Placeholder is not a label.
- (error, input-error-description) When error=true: Describe the error via aria-describedby pointing to a visible message; the red border alone is not conveyed to screen readers.
- (warn, input-form-name) When the field is inside a <form> and its value should be submitted: Set name. A field without a name is omitted from FormData entirely.

## Examples

### Wrapped in a label

```html
<label>
  Email
  <aihio-input type="email" placeholder="you@example.com"></aihio-input>
</label>
```

### Named by aria-label

For a field with no visible label, such as a search box.

```html
<aihio-input aria-label="Search" placeholder="Search…"></aihio-input>
```

### In a field, with an error

```html
<aihio-field>
  <label slot="label">Password</label>
  <aihio-input type="password" name="password" autocomplete="new-password"></aihio-input>
  <span slot="error">Password is too short.</span>
</aihio-field>
```

## Mistakes

### Placeholder is not a label. Associate a <label> or add aria-label.

Don't (aihio lint: input-label):

```html
<aihio-input placeholder="Email"></aihio-input>
```

Do:

```html
<aihio-field>
  <label slot="label">Email</label>
  <aihio-input type="email" name="email" placeholder="you@example.com"></aihio-input>
</aihio-field>
```

### error=true without an aria-describedby message leaves screen reader users without context.

Don't (aihio lint: input-error-description):

```html
<aihio-input error></aihio-input>
```

Do:

```html
<aihio-field>
  <label slot="label">Email</label>
  <aihio-input name="email"></aihio-input>
  <span slot="error">Enter an email address.</span>
</aihio-field>
```

### No name attribute, so this field submits nothing. Add name="email".

Don't (aihio lint: input-form-name):

```html
<form>
  <aihio-input aria-label="Email" type="email"></aihio-input>
</form>
```

Do:

```html
<form>
  <aihio-input aria-label="Email" type="email" name="email"></aihio-input>
</form>
```