# Field

A wrapper component for form inputs with labels and validation.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import { Field, FieldDescription, FieldLabel, Input } from "coss-svelte";
</script>

<Field>
	<FieldLabel>Name</FieldLabel>
	<Input placeholder="Enter your name" type="text" />
	<FieldDescription>Visible on your profile</FieldDescription>
</Field>

```

## Anatomy

- `Field`
- `FieldDescription`
- `FieldError`
- `FieldLabel`
- `FieldValidity`

## API Reference

### Field

A wrapper component for form inputs with labels and validation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | - | ID forwarded to the form control. |
| `label` | `string` | `""` | Accessible label or fallback visible label for the control. |
| `description` | `string` | `""` | Supporting text rendered by the component's built-in fallback layout. |
| `error` | `string` | `""` | Validation message rendered by the field fallback layout. |
| `required` | `boolean` | `false` | Marks the field or label as required. |
| `disabled` | `boolean` | `false` | Disables interaction with the control. |
| `invalid` | `boolean` | `false` | Marks the component invalid independently of parse validity. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <div> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### FieldDescription

Provides supporting copy for the parent component.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte component attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### FieldError

Renders validation or error feedback for the parent field.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <p> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### FieldLabel

Labels the parent component or a grouped section.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `required` | `boolean` | `false` | Marks the field or label as required. |
| `for` | `string` | - | Configures the for behavior for this component. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte <label> attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### FieldValidity

Renders validation state for the parent field.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte component attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | compound |
| Category | Forms & Validation |
| Particles | 18 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/field.json` for the complete local file and dependency closure.
- Field is stable in the current source catalog.