---
title: "Field"
description: "Labels a custom control and renders its helper or error message."
category: "Form & Input"
slug: field
url: /components/field
since: "0.2.0"
status: "stable"
---

# Field

Labels a custom control and renders its helper or error message.

## Import

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

## Preview

A label, a native control, and helper text.

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

<div class="field-row">
	<Field label="Project name" htmlFor="field-basic" helper="Shown in the project switcher.">
		<input id="field-basic" class="native" placeholder="Orbital" />
	</Field>
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 320px;
	}

	.native {
		width: 100%;
		box-sizing: border-box;
		padding: var(--iv_control-pad-y) var(--iv_control-pad-x);
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground);
		font-family: var(--iv_font-ui);
		font-size: var(--iv_text-body);
	}

	.native:focus-visible {
		outline: var(--iv_outline-width) solid var(--iv_foreground);
		outline-offset: 1px;
	}
</style>
```

## Usage

- Wrap one control; `htmlFor` must match the control id to associate the label.
- `error` replaces `helper` and reuses the message id from `messageId` or `htmlFor`.
- Built-in controls such as `Input` already render a label; use `Field` for custom form elements.

## Examples

### Validation

The error message takes the place of the helper.

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

	let slug = $state('');
	const error = $derived(slug.length === 0 ? 'A slug is required.' : '');
</script>

<div class="field-row">
	<Field
		label="Slug"
		htmlFor="field-validation"
		required
		{error}
		helper="Lowercase letters, numbers, and dashes."
	>
		<input id="field-validation" class="native" bind:value={slug} placeholder="orbital" />
	</Field>
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 320px;
	}

	.native {
		width: 100%;
		box-sizing: border-box;
		padding: var(--iv_control-pad-y) var(--iv_control-pad-x);
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground);
		font-family: var(--iv_font-ui);
		font-size: var(--iv_text-body);
	}

	.native:focus-visible {
		outline: var(--iv_outline-width) solid var(--iv_foreground);
		outline-offset: 1px;
	}
</style>
```

### Custom control

The label is associated through `htmlFor`.

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

	let color = $state('#b08d57');
</script>

<div class="field-row">
	<Field label="Cursor accent" htmlFor="field-color" helper="Used for carets and active markers.">
		<input id="field-color" class="native color" type="color" bind:value={color} />
	</Field>
	<code class="readout">{color}</code>
</div>

<style>
	.field-row {
		display: flex;
		align-items: end;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 360px;
	}

	.native {
		width: 100%;
		box-sizing: border-box;
		padding: var(--iv_control-pad-y) var(--iv_control-pad-x);
		border: 1px solid var(--iv_border);
		border-radius: var(--iv_radius-sm);
		background: var(--iv_surface-raised);
		color: var(--iv_foreground);
		font-family: var(--iv_font-ui);
		font-size: var(--iv_text-body);
	}

	.color {
		height: var(--iv_control-md);
		padding: var(--iv_spacing-2xs);
	}

	.readout {
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Label text associated with the control. |
| `htmlFor` | `string` | `''` | Id of the control to label. Generated when omitted. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `error` | `string` | `''` | Error message; replaces the helper text. |
| `helper` | `string` | `''` | Helper text shown below the control. |
| `messageId` | `string` | `''` | Id used for the message element referenced by `aria-describedby`. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |

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

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | The control being labelled. |

### Tokens used

`--iv_error` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_spacing-2xs` · `--iv_spacing-sm` · `--iv_spacing-xs` · `--iv_text-label` · `--iv_text-sm` · `--iv_weight-medium`

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

### CSS hooks

`.iv-field` · `.iv-field-control` · `.iv-field-error` · `.iv-field-helper` · `.iv-field-label` · `.iv-field-message` · `.iv-required-mark`

## Accessibility

- The label is a real `<label>` when `htmlFor` is set.
- The message element gets an id so controls can reference it with `aria-describedby`.
- Required fields show a visual asterisk that is hidden from assistive technology; set `required` on the control as well.

## Related

- [Input](/components/input.md)
- [Textarea](/components/textarea.md)
- [Select](/components/select.md)
- [Checkbox](/components/checkbox.md)