---
title: "Field"
description: "A form unit that groups label, control, description and error. Field does not draw the control: it wraps it so state, help text and accessible validation are inherited."
kind: component
id: C-006
registry: "field"
docs: "https://koten.codehive.com.co/components/field"
markdown: "https://koten.codehive.com.co/md/components/field.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/field.json"
language: en
---

# Field · 欄

> Component C-006 in the Koten UI catalog.

A form unit that groups label, control, description and error. Field does not draw the control: it wraps it so state, help text and accessible validation are inherited.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/field.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/field.json
```

## Files

- `@/components/ui/field.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Reference

- Upstream primitive: https://base-ui.com/react/components/field

## Examples

### States

Default, required, error and disabled share the same structure; only what the field announces changes.

```tsx
<Field label="Correo" description="Solo para avisos del pedido.">
  <Input type="email" placeholder="nombre@ejemplo.com" autoComplete="email" />
</Field>

<Field label="Teléfono" description="Con código de país." required>
  <Input type="tel" placeholder="+81 90 1234 5678" autoComplete="tel" />
</Field>

<Field
  label="Correo"
  description="Solo para avisos del pedido."
  error="El correo no es válido."
>
  <Input type="email" defaultValue="correo@" autoComplete="email" />
</Field>

<Field label="Cliente" description="Asignado desde KURA." disabled>
  <Input defaultValue="KURA-0142" readOnly />
</Field>
```

### Horizontal orientation

orientation="horizontal" moves the label into a 140 px column at sm and up. FormRow is the shortcut for this same pattern.

```tsx
<Field
  className="max-w-xl"
  label="Teléfono"
  description="Incluye el código de país."
  orientation="horizontal"
>
  <Input type="tel" placeholder="+81 90 1234 5678" autoComplete="tel" />
</Field>
```

### Use inside a form

Label, help text, required state and submission in a minimal, complete form.

```tsx
<form className="grid max-w-md gap-[var(--koten-gap)]">
  <Field
    label="Correo de contacto"
    description="Solo lo usamos para avisos del pedido."
    required
  >
    <Input
      type="email"
      name="email"
      autoComplete="email"
      placeholder="nombre@ejemplo.com"
    />
  </Field>

  <Field label="Teléfono" description="Con código de país.">
    <Input type="tel" name="phone" autoComplete="tel" placeholder="+81 90 1234 5678" />
  </Field>

  <div className="flex flex-wrap items-center gap-[var(--koten-gap)]">
    <Button type="submit" variant="primary">Guardar cliente</Button>
    <Button type="reset" variant="ghost">Limpiar</Button>
  </div>
</form>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `—` | Required. Field associates it with the control and adds the asterisk when required is set. |
| `description` | `ReactNode` | `—` | Linked to the control with aria-describedby, together with the error when one exists. |
| `error` | `ReactNode` | `—` | Activates aria-invalid, paints the border in danger and announces the message with aria-live polite. |
| `required` | `boolean` | `false` | Adds the visual mark and the required attribute to the control; it does not validate on its own. |
| `orientation` | `vertical \| horizontal` | `vertical` | horizontal uses a 140 px label at sm and up, and returns to vertical on mobile. |
| `disabled` | `boolean` | `false` | Disables the control and fades label and help text; the state is inherited. |

## Accessibility

- Field associates the label with the control; do not add a second <label> or use the placeholder as the name.
- description and error are linked with aria-describedby; the error also activates aria-invalid.
- required adds the attribute to the control and an aria-hidden asterisk; the label text must still read clearly without it.
- disabled propagates to the control; when the value must remain readable and copyable, use readOnly instead.

## Sources

- Catalog page: https://koten.codehive.com.co/components/field
- Markdown: https://koten.codehive.com.co/md/components/field.md
- Repository: https://github.com/codehive-colombia/koten