# Input

## Overview

The input component is a single-line control for short user-entered values such as names, titles, codes, search terms, and color values.

The component pattern uses a native `<label>` that wraps a native `<input>`, so the control can be styled without requiring a classed wrapper.

## When to use

Use an input for a short, single-line value, choosing the native input type that matches the data.

## When not to use

Do not use an input for content that may span multiple lines; use a textarea.

## Usage

```html
<label>
  <span data-role="label">Label</span>
  <input id="demo-input" type="text" placeholder="Type here" />
  <span data-role="message" data-invalid="This field is required."></span>
</label>
```

```html
<label>
  <span data-role="label">Rounded Search</span>
  <input id="demo-input-search" type="search" placeholder="Search tokens" />
</label>
```

Use this component when the user needs to enter a short, single-line value.

Use `type="color"` when the user needs to choose a color while keeping the same field height, border, radius, and focus treatment as other inputs.

Use a textarea instead when the expected response can span multiple lines.

The label should remain visible above the field, and the placeholder should act as an example rather than replacing the label.

The field should use native `<label>` and `<input>` elements so the control keeps browser form behavior, keyboard support, and autofill.

Wrap the visible label text in a `[data-role="label"]` element so required fields can render the red asterisk immediately after the label text.

For native validation, place a `[data-role="message"]` element directly after the input inside the same label. Pair that with native constraints such as `required`, `minlength`, `maxlength`, `pattern`, `min`, `max`, or `step`.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- INP-001: Single-line inputs should use the shared action padding and control minimum height so they match button height while still accommodating larger content.
- INP-002: Focus must remain clearly visible for keyboard users.
- INP-003: Comfortable and compact density should come from the layout theme tokens rather than input-specific spacing values.
- INP-004: Inputs can override the shared control radius with `--input-border-radius` when a field needs a different corner treatment.
- INP-005: Color inputs should keep the native color picker behavior while presenting the swatch inside the standard input shell.
- INP-006: Validation feedback should appear only after user interaction by using `:user-invalid` rather than showing errors on initial page load.
## Accessibility

- Use a native `<label>` so the field stays explicitly named.
- If the label does not wrap the input, associate them with matching `for` and `id` attributes.
- Do not rely on placeholder text as the only field description.
- Keep text contrast and focus indication strong enough to be visible in normal use.
- Provide helper text or error text outside the field when extra guidance is needed.
- When showing validation feedback, keep the message text in the DOM so it remains available to assistive technology.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--input-background` | `<color>` | Sets the input fill color for enabled and disabled states; change it when text fields need a filled, transparent, or disabled surface. |
| `--input-border-color` | `<color>` | Sets the text input border color, including validation overrides; change it to communicate neutral, focus-adjacent, or error state. |
| `--input-border-radius` | `<length>` | Sets text input corner radius and grouped-control radius; change it for pill search fields or sharper form controls. |
| `--input-color-accent-disabled` | `<color>` | Sets --input-color-accent-disabled so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-border-subtle` | `<color>` | Sets --input-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-error-strong` | `<color>` | Sets --input-color-error-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-focus-ring` | `<color>` | Sets --input-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-primary` | `<color>` | Sets --input-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text` | `<color>` | Sets --input-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text-accent` | `<color>` | Sets --input-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text-subtle` | `<color>` | Sets --input-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-border-width` | `<length>` | Sets --input-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-gap` | `<length>` | Sets --input-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-min-height` | `<length>` | Sets --input-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-padding-block` | `<length>` | Sets --input-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-padding-inline` | `<length>` | Sets --input-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-radius` | `<length>` | Sets --input-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-focus-ring-size` | `<length>` | Sets --input-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-font-size` | `<length>` | Sets --input-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-font-size-caption` | `<length>` | Sets --input-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-line-height` | `<number>` | Sets --input-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-message-color` | `<color>` | Sets helper and validation message text color for inputs; change it when field messaging should move between subtle and error emphasis. |

## Depends On

- `--color-accent-disabled`
- `--color-border-subtle`
- `--color-error-strong`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-action-padding-block`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`