---
title: "Input"
description: "A single-line text field with an optional label, helper, and error state."
category: "Form & Input"
slug: input
url: /components/input
since: "0.1.0"
status: "stable"
---

# Input

A single-line text field with an optional label, helper, and error state.

## Import

```svelte
import { Input } from '@elluzion/iv-ui';
```

## Preview

Default, filled, error, disabled, and read-only.

```svelte
<script lang="ts">
	import { Input } from '@elluzion/iv-ui';

	let filled = $state('atlas-core');
</script>

<div class="fields">
	<Input label="Project name" placeholder="atlas-core" />
	<Input label="Slug" bind:value={filled} helper="Lowercase, dashes only." />
	<Input label="Repository" value="atlas/core" error="This repository is already linked." />
	<Input label="Owner" value="elluzion" disabled />
	<Input label="Region" value="eu-west-1" readonly />
</div>

<style>
	.fields {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 320px;
	}
</style>
```

## Usage

- Bind `value` for two-way state: `bind:value`.
- The label is rendered inside the field component — no external `<label>` needed.
- Pass `error` to switch to the error treatment; `helper` is replaced by the error message.

## Examples

### Sizes

The label and helper scale with the control.

```svelte
<script lang="ts">
	import { Input } from '@elluzion/iv-ui';
</script>

<div class="fields">
	<Input size="sm" label="Small" placeholder="sm" />
	<Input size="md" label="Medium" placeholder="md" />
	<Input size="lg" label="Large" placeholder="lg" />
</div>

<style>
	.fields {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 320px;
	}
</style>
```

### Validation

`error` pairs with `aria-invalid` and `aria-describedby`.

```svelte
<script lang="ts">
	import { Input } from '@elluzion/iv-ui';

	let email = $state('');

	const error = $derived(
		email.length === 0 ? '' : email.includes('@') ? '' : 'Enter a valid email address.'
	);
</script>

<div class="fields">
	<Input
		type="email"
		label="Email"
		placeholder="you@example.com"
		bind:value={email}
		{error}
		helper="Used for deploy notifications."
		required
	/>
</div>

<style>
	.fields {
		width: 100%;
		max-width: 320px;
	}
</style>
```

### Leading and trailing icons

Snippets sit inside the field frame; `clearable` adds a reset button.

```svelte
<script lang="ts">
	import { IconAt, IconSearch } from '@tabler/icons-svelte';
	import { Input } from '@elluzion/iv-ui';

	let query = $state('deployments');
	let email = $state('ada@atlas.dev');
</script>

<div class="fields">
	<Input label="Search" placeholder="Search projects…" bind:value={query}>
		{#snippet leadingIcon()}
			<IconSearch size={16} />
		{/snippet}
	</Input>
	<Input
		type="email"
		label="Email"
		bind:value={email}
		clearable
		helper="Clearable shows a reset button while filled."
	>
		{#snippet leadingIcon()}
			<IconAt size={16} />
		{/snippet}
	</Input>
</div>

<style>
	.fields {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 320px;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'text' \| 'password' \| 'email' \| 'number' \| 'search' \| 'url' \| 'tel'` | `'text'` | Native input type. |
| `value` **bindable** | `string` | `''` | Current value. Bind with `bind:value`. |
| `placeholder` | `string` | `''` | Placeholder shown while the field is empty. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `readonly` | `boolean` | `false` | Prevents editing while keeping the value focusable and readable. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `name` | `string` | `''` | Form field name submitted with the surrounding form. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `autocomplete` | `HTMLInputAttributes['autocomplete']` | — | Native autocomplete hint. |
| `minlength` | `number` | — | Minimum number of characters. |
| `maxlength` | `number` | — | Maximum number of characters. |
| `min` | `number \| string` | — | Minimum value for numeric and date types. |
| `max` | `number \| string` | — | Maximum value for numeric and date types. |
| `pattern` | `string` | — | Regular expression the value must match. |
| `label` | `string` | `''` | Visible label for the control. |
| `error` | `string` | `''` | Error message. Switches the control to the error treatment. |
| `helper` | `string` | `''` | Helper text shown below the control. |
| `clearable` | `boolean` | `false` | Shows a reset button while the field has a value. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control size. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `input` | `(e: Event) => void` | Called on every keystroke with the native event. |
| `change` | `(e: Event) => void` | Called when the value is committed. |
| `focus` | `(e: FocusEvent) => void` | Called when the control receives focus. |
| `blur` | `(e: FocusEvent) => void` | Called when the control loses focus. |
| `keydown` | `(e: KeyboardEvent) => void` | Called on keydown with the native keyboard event. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `leadingIcon` | `Snippet` | Snippet rendered inside the field, before the text. |
| `trailingIcon` | `Snippet` | Snippet rendered inside the field, after the text. |

### Tokens used

`--iv_border` · `--iv_border-error` · `--iv_border-focus` · `--iv_border-hover` · `--iv_control-md` · `--iv_control-pad-x` · `--iv_control-pad-x-lg` · `--iv_control-pad-x-sm` · `--iv_control-pad-y` · `--iv_control-pad-y-lg` · `--iv_control-pad-y-sm` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_error` · `--iv_error-surface` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-2xs` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-base` · `--iv_text-body-sm` · `--iv_text-label` · `--iv_text-lg` · `--iv_text-sm` · `--iv_transition-base`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-clear-btn` · `.iv-disabled` · `.iv-error-message` · `.iv-has-error` · `.iv-helper-message` · `.iv-icon` · `.iv-input-lg` · `.iv-input-sm` · `.iv-input-wrapper` · `.iv-label` · `.iv-leading` · `.iv-message` · `.iv-required-mark` · `.iv-trailing`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the field. |
| `Escape` | Clears the value when `clearable` is set. |

- The label is associated with the input through a generated id.
- Error text is announced through `aria-describedby`; the input also gets `aria-invalid`.

## Related

- [Field](/components/field.md)
- [Textarea](/components/textarea.md)
- [Select](/components/select.md)
- [InputGroup](/components/input-group.md)