> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Input

> Inputs are used for short text in forms and toolbars, with support for labels, helper text, prefixes, and validation states.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-input--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--default" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--default&viewMode=story&globals=theme:light" title="Input default story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* When users need to provide specific text-based information, such as assets, name, or other details.
* In forms or for entering credentials like usernames, passwords, or email addresses.
* For search bars and filters where users need to enter keywords to find specific items or content.

## When to use something else

* If users need to choose from a predefined set of options, consider [Select](/cdf/aura/primitives/select), [Combobox](/cdf/aura/primitives/combobox), [Checkbox](/cdf/aura/primitives/checkbox), or [Radio](/cdf/aura/primitives/radio).
* If the user can add options or benefits from suggestions while typing, consider [Combobox](/cdf/aura/primitives/combobox).
* For date and time input, use [Date picker](/cdf/aura/primitives/date-picker) primitives.
* For long text such as descriptions, use [Textarea](/cdf/aura/primitives/textarea).

## Dos and don'ts

* **Do** use concise labels and placeholder copy to help users understand what information is being requested.
* **Do** left align text Inputs with other input types in forms.
* **Don't** use long placeholder descriptions that repeat the label name.
* **Don't** repeat the label in placeholder copy.
* **Don't** use placeholder text that could be misunderstood as pre-filled text.
* **Don't** wrap text. Truncate or use a [Textarea](/cdf/aura/primitives/textarea) instead.
* **Don't** use any default filled text as users may overlook it.

## Anatomy

* Leading content: Optional content that appears to the left of the input field. It is not recommended to use multiple leading content items unless it is absolutely necessary.
  * Icon: An optional icon that appears to the left of the input field to help the user understand the context of the input.
  * Prefix: An optional, fixed formatted text that appears to the left of the input field, e.g., a currency symbol.
* Trailing content: Optional content that appears to the right of the input field. It is not recommended to use multiple trailing content items unless it is absolutely necessary.
  * Button: Helpful for quick actions related to the input, e.g., "Copy" or "Search". A tooltip may be helpful to explain the action.
  * Suffix: An optional, fixed formatted text that appears to the right of the input field, e.g., a unit of measurement.
  * Stepper: Allows the user to increment or decrement a value by a fixed amount.
  * Shortcut: Helpful shortcut key related to the input, e.g., "Ctrl + C" for "Copy". A [Tooltip](/cdf/aura/primitives/tooltip) may help explain the shortcut.

## Behavior

### Validation

It is recommended to display a validation error before the user submits a form if possible. This can be triggered when:

* The Input component goes from a focus to default state after the user has interacted with it. For example, a user types in a password but does not include all required characters. When the focus leaves the Input, an error message can be triggered; or
* While the user is typing and they have entered wrong information. For example, the user typed a symbol, but only alphanumeric characters are supported.

### Clearing text

There are two ways in which content can be cleared from the container of an Input:

* The user can click anywhere inside the Input and hit Delete or Backspace on their keyboard.
* Inputs can, optionally, display a Clear all button to the right of the text, allowing the user to quickly clear all content within the field. Clear all button is not enabled by default, however it is recommended to appear once the user starts typing. Avoid displaying a Clear all button and trailing content at the same time as it can visually clutter the Input.

## Often used with

[Label](/cdf/aura/primitives/label), [Helper text](/cdf/aura/primitives/helper-text); input-group layout (leading icon, prefix, suffix, trailing [Button](/cdf/aura/primitives/button)) per [Anatomy](#anatomy); [Tooltip](/cdf/aura/primitives/tooltip) on trailing icon [Button](/cdf/aura/primitives/button)s.

## Accessibility

Aura's Input is a thin wrapper around the native HTML `<input>`, so accessibility compliance depends on how you label, describe, and manage states around the component.

### Labeling and programmatic identification

* **Pair with Label:** Connect a [Label](/cdf/aura/primitives/label) `htmlFor="input-id"` to an `<Input id="input-id">`. Never use placeholder as a replacement for a label — placeholder text disappears on input and fails contrast and persistence rules.
* **Visually hidden labels:** If design omits a visible label (for example, an inline search field), pass an explicit `aria-label="Search directory"` or `aria-labelledby` directly to the `<Input>`.

### Helper text and error associations

* **Link help text:** Connect persistent instructions (for example, formatting rules) by setting `aria-describedby="helper-id"` on the `<Input>` matching the `id` of the descriptive text. See [Helper text](/cdf/aura/primitives/helper-text).
* **Expose error states:** When validation fails, set `aria-invalid="true"` on the `<Input>` and link the error message element via `aria-errormessage="error-id"`. Ensure the error message container includes `role="alert"` for live announcements.

### Semantics and keyboard support

* **Set explicit type attributes:** Use semantic input types (`type="email"`, `type="tel"`, `type="url"`) to trigger correct mobile keyboard layouts and inform screen readers of expected data structures.
* **Provide autocomplete tokens:** Pass valid `autocomplete` values (for example, `autocomplete="email"`, `autocomplete="one-time-code"`) to assist auto-fill tools and reduce cognitive load for users.
* **Indicate required fields:** Add `aria-required="true"` or `required` to mandatory inputs so screen reader users know a value is necessary before submitting.

### Input decorations and interactive adornments

* **Hide decorative icons:** If embedding icons inside or beside the input (for example, a search icon), set `aria-hidden="true"` on the SVG to prevent screen readers from reading raw icon paths or decorative labels.
* **Label action buttons:** For interactive adornments inside the input box (for example, "Show password" eye toggles or "Clear input" buttons), use a semantic `<button type="button">` with an explicit `aria-label`.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### With label

Pair every input with a [Label](/cdf/aura/primitives/label) so users know what to enter and assistive technologies can announce the field correctly.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--with-label" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--with-label&viewMode=story&globals=theme:light" title="Input with label story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Disabled

Use a disabled input when the value cannot be edited in the current context—for example, when a parent setting must be enabled first.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--disabled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--disabled&viewMode=story&globals=theme:light" title="Input disabled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Read only

Use read-only when the value should be visible and copyable but not editable, such as a generated ID or a field locked after submission.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--read-only" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--read-only&viewMode=story&globals=theme:light" title="Input read only story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With error

Show the error state with [Helper text](/cdf/aura/primitives/helper-text) after validation fails so users understand what to correct before resubmitting.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--with-error" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--with-error&viewMode=story&globals=theme:light" title="Input with error story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With default value

Pre-fill a default value when most users will accept the suggested input—for example, a country code or a sensible starting number.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--with-default-value" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--with-default-value&viewMode=story&globals=theme:light" title="Input with default value story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Input types

Choose the appropriate HTML input type so mobile keyboards, validation, and browser behavior match the expected data format.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--input-types" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--input-types&viewMode=story&globals=theme:light" title="Input input types story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All states

Review all states together when designing forms to ensure default, focus, disabled, read-only, and error treatments stay consistent.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-input--all-states" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-input--all-states&viewMode=story&globals=theme:light" title="Input all states story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>