--- title: Field description: Combine labels, controls, and help text to compose accessible form fields and grouped inputs. component: true new: true --- ::component-preview --- name: FieldDemo class: '[&_.preview]:h-[800px] [&_.preview]:p-6 md:[&_.preview]:h-[850px]' --- :: ## Installation ```bash npx shadcn-vue@latest add field ``` ## Usage ```vue showLineNumbers ``` ## Anatomy The `Field` family is designed for composing accessible forms. A typical field is structured as follows: ```vue showLineNumbers ``` - `Field` is the core wrapper for a single field. - `FieldContent` is a flex column that groups label and description. Not required if you have no description. - Wrap related fields with `FieldGroup`, and use `FieldSet` with `FieldLegend` for semantic grouping. ## Examples ### Input ::component-preview --- name: FieldInputDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Textarea ::component-preview --- name: FieldTextareaDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Select ::component-preview --- name: FieldSelectDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Slider ::component-preview --- name: FieldSliderDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Fieldset ::component-preview --- name: FieldFieldsetDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Checkbox ::component-preview --- name: FieldCheckboxDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Radio ::component-preview --- name: FieldRadioDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Switch ::component-preview --- name: FieldSwitchDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Choice Card Wrap `Field` components inside `FieldLabel` to create selectable field groups. This works with `RadioItem`, `Checkbox` and `Switch` components. ::component-preview --- name: FieldChoiceCardDemo class: '!mb-4 [&_.preview]:p-6' --- :: ### Field Group Stack `Field` components with `FieldGroup`. Add `FieldSeparator` to divide them. ::component-preview --- name: FieldGroupDemo class: '!mb-4 [&_.preview]:p-6' --- :: ## Responsive Layout If you are in tailwindcss v3 you need to install [`@tailwindcss/container-queries`](https://github.com/tailwindlabs/tailwindcss-container-queries) - **Vertical fields:** Default orientation stacks label, control, and helper text—ideal for mobile-first layouts. - **Horizontal fields:** Set `orientation="horizontal"` on `Field` to align the label and control side-by-side. Pair with `FieldContent` to keep descriptions aligned. - **Responsive fields:** Set `orientation="responsive"` for automatic column layouts inside container-aware parents. Apply `@container/field-group` classes on `FieldGroup` to switch orientations at specific breakpoints. ::component-preview --- name: FieldResponsiveDemo class: '!mb-4 [&_.preview]:h-[650px] [&_.preview]:p-6 [&_.preview]:md:h-[500px] [&_.preview]:md:p-10' --- :: ## Validation and Errors - Add `data-invalid` to `Field` to switch the entire block into an error state. - Add `aria-invalid` on the input itself for assistive technologies. - Render `FieldError` immediately after the control or inside `FieldContent` to keep error messages aligned with the field. ```vue showLineNumbers /data-invalid/ /aria-invalid/ ``` ## Accessibility - `FieldSet` and `FieldLegend` keep related controls grouped for keyboard and assistive tech users. - `Field` outputs `role="group"` so nested controls inherit labeling from `FieldLabel` and `FieldLegend` when combined. - Apply `FieldSeparator` sparingly to ensure screen readers encounter clear section boundaries. ## API Reference ### FieldSet Container that renders a semantic `fieldset` with spacing presets. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue ``` ### FieldLegend Legend element for a `FieldSet`. Switch to the `label` variant to align with label sizing. | Prop | Type | Default | | ----------- | --------------------- | ---------- | | `variant` | `"legend" \| "label"` | `"legend"` | | `class` | `string` | | ```vue Notification Preferences ``` The `FieldLegend` has two variants: `legend` and `label`. The `label` variant applies label sizing and alignment. Handy if you have nested `FieldSet`. ### FieldGroup Layout wrapper that stacks `Field` components and enables container queries for responsive orientations. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue ``` ### Field The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing. | Prop | Type | Default | | -------------- | -------------------------------------------- | ------------ | | `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | | `class` | `string` | | | `data-invalid` | `boolean` | | ```vue Remember me ``` ### FieldContent Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue Notifications Email, SMS, and push options. ``` ### FieldLabel Label styled for both direct inputs and nested `Field` children. | Prop | Type | Default | | ----------- | --------- | ------- | | `class` | `string` | | | `asChild` | `boolean` | `false` | ```vue Email ``` ### FieldTitle Renders a title with label styling inside `FieldContent`. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue Enable Touch ID Unlock your device faster. ``` ### FieldDescription Helper text slot that automatically balances long lines in horizontal layouts. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue We never share your email with anyone. ``` ### FieldSeparator Visual divider to separate sections inside a `FieldGroup`. Accepts optional inline content. | Prop | Type | Default | | ----------- | -------- | ------- | | `class` | `string` | | ```vue Or continue with ``` ### FieldError Accessible error container that accepts children or an `errors` array (e.g., from `vee-validate`). | Prop | Type | Default | | ----------- | ------------------------------------------ | ------- | | `errors` | `Array<{ message?: string } \| undefined>` | | | `class` | `string` | | ```vue ``` When the `errors` array contains multiple messages, the component renders a list automatically. `FieldError` also accepts issues produced by any validator that implements [Standard Schema](https://standardschema.dev/), including Zod, Valibot, and ArkType. Pass the `issues` array from the schema result directly to render a unified error list across libraries.