{
"title": "Field",
"description": "Layout and accessibility envelope that wires a label, description, error, and a form control together without managing form state.",
"url": "/docs/components/field",
"since": "0.1.0",
"tags": [
"form",
"a11y",
"layout"
],
"platform": "both",
"source": "---\ntitle: Field\ndescription: Layout and accessibility envelope that wires a label, description, error, and a form control together without managing form state.\nsince: 0.1.0\ntags: [form, a11y, layout]\nplatform: both\ncategory: inputs\n---\n\nimport { BundleSize } from '@/components/bundle-size';\nimport { Preview } from '@/components/preview';\nimport { PropsTable } from '@/components/props-table';\n\n\n\n`` is a layout and accessibility envelope. It generates stable IDs, wires\n`aria-labelledby`, `aria-describedby`, `aria-invalid`, and `aria-required` onto\nthe wrapped control, and provides visual slots for a label, hint text, and an error\nmessage. It does not own form state — you bring your own state management and pass\n`error` down from wherever validation lives.\n\n`Field` has two API modes: **shorthand** (the common case) and **compound** (an\nescape hatch for custom layout). The shorthand API takes `label`, `description`,\nand `error` as props directly on ``, so the child is just the control.\nThe compound API uses explicit sub-components (``, ``,\n``, ``) for cases that need a non-standard slot layout.\n\n`Field` is form-framework agnostic. It works equally well with React Hook Form,\nZod + manual state, or no library at all. The RHF pattern using ``\nis shown in the [react-hook-form](#react-hook-form-recommended) section.\n\n## Basic usage\n\nPass `label` and place the control as the child.\n\n\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\n\nexport const Example = () => (\n \n \n \n);\n```\n\n`Field` injects `id`, `aria-labelledby`, and related ARIA attributes onto the\nchild control automatically. The child does not need to set them manually.\n\n## With description and error\n\nPass `description` and `error` as props:\n\n\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\nimport { useState } from 'react';\n\nexport default function UsernameField() {\n const [value, setValue] = useState('');\n const [error, setError] = useState(null);\n\n return (\n \n \n \n );\n}\n```\n\nWhen `error` is set, `Field` renders the error message below the control and\nsets `aria-invalid` on the child. When both `description` and `error` are\npresent, `aria-describedby` contains both IDs — assistive technology reads both.\n\n## Required\n\nPass `required`:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\n\nexport const Example = () => (\n \n \n \n);\n```\n\n`aria-required` is forwarded to the control. `Field` renders a visual indicator\n(a red asterisk by default) next to the label text, with a screen-reader-only\naccessible label. Both strings are configurable via the `NoriProvider` dictionary:\n\n| Key | Default | Purpose |\n|--------------------------|---------|----------------------------------------------|\n| `field.requiredIndicator` | `*` | Visual character appended to the label |\n| `field.requiredLabel` | `required` | Accessible label on the indicator span |\n\n```tsx\nimport { NoriProvider } from '@nori-ui/core/client';\n\nexport const App = () => (\n \n {/* ... */}\n \n);\n```\n\n## Disabled\n\nPass `disabled`. The flag propagates to the child control and dims the label:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\n\nexport const Example = () => (\n \n \n \n);\n```\n\nThe child component's own `disabled` prop is OR-ed with the field-level value,\nso you can also disable the control directly without going through the field.\n\n## Horizontal orientation\n\n`orientation=\"horizontal\"` renders the label and control side-by-side:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\n\nexport const Example = () => (\n \n \n \n);\n```\n\nThe default is `\"vertical\"`.\n\n## Validating state\n\nWhile an async validation is in flight, pass `validating` to show a spinner and\nset `aria-busy`:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\n\nexport const Example = () => (\n \n \n \n);\n```\n\n`validating` and `error` can coexist — the spinner renders alongside the error\nmessage until the new result arrives.\n\n## Field.Group\n\n`Field.Group` is a fieldset-style envelope for grouped controls such as radio\nsets, checkbox groups, or multi-switch rows. It renders a `role=\"group\"` container\nlabelled by its own label — equivalent to `\n )}\n />\n \n \n );\n}\n```\n\nTo inject a server-side error after submission, call `setError`:\n\n```tsx\nimport { useForm } from 'react-hook-form';\n\nconst { setError } = useForm();\n\n// After a failed API call:\nsetError('email', { message: 'That email is already registered.' });\n```\n\n`react-hook-form` is not a peer dependency of `@nori-ui/core`. Install it\nseparately:\n\n```bash\nyarn add react-hook-form\n```\n\n## Manual / framework-agnostic\n\nField works without any form library. Use `useState` for local state and pass\na derived error string:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\nimport { useState } from 'react';\n\nexport default function EmailField() {\n const [value, setValue] = useState('');\n const [touched, setTouched] = useState(false);\n\n const error =\n touched && value.length === 0\n ? 'Email is required.'\n : touched && !value.includes('@')\n ? 'Not a valid email address.'\n : null;\n\n return (\n \n { setValue(v); setTouched(true); }}\n placeholder=\"you@example.com\"\n />\n \n );\n}\n```\n\n## Custom layout (compound API)\n\nWhen you need full control over slot placement — a control + button row, animated\nerror transitions, or a field with multiple controls — use the compound sub-components\ndirectly:\n\n```tsx\nimport { Field, TextInput } from '@nori-ui/core';\nimport { View } from 'react-native';\n\nexport const Example = () => (\n \n Invite code\n Check your welcome email for your code.\n \n \n \n \n \n \n \n \n);\n```\n\nWhen to reach for the compound API:\n\n- The control sits inside a row alongside other elements (e.g., a button).\n- You need to animate the error message in/out independently.\n- You have multiple controls sharing one label (e.g., first + last name in a\n single row) and need to manage the `id` wiring yourself.\n\n`Field.Control` clones its single child and injects `id`, `aria-labelledby`,\nand related ARIA attributes. Pass the `error` prop on `` even in compound\nmode — `Field.Control` reads it to set `aria-invalid`, and `Field.Error` reads\nit to render the message.\n\n## Standalone Label\n\nFor cases where `` is too much — standalone toggle rows or settings\nentries — use [`