Field
A field puts a label above a form control, a one-sentence hint below it and, when the backend refuses the value, the backend’s error message.
When to use
Section titled “When to use”- Wrap every form control that people fill in: Input, Textarea, Select, Combobox, Input OTP.
- Use
FieldSetwith aFieldLegendto group controls that answer one question, such as a Radio Group. - Use the
horizontalorientation only for a Switch or a Checkbox, with the control before its label. - Don’t write error messages in the client. The backend validates every field and returns the message; the client only disables the submit button until the required fields have a value.
Tulis sesuai sampul rilis.
Judul lagunya belum diisi.
Opsional, untuk tim rilis.
Tulis sesuai sampul rilis.
Judul lagunya belum diisi.
Opsional, untuk tim rilis.
Anatomy
Section titled “Anatomy”- 1Label
- 2Control, red border while invalid
- 3Hint
- 4The backend's error message
- Label (
FieldLabel): above the control, inforeground. It turnsdestructivewhen the field is invalid. - Control: the input, textarea or other control, with
aria-invalidwhile its value is refused. - Hint (
FieldDescription): one practical sentence inmuted-foreground. - Error (
FieldError): the backend’s message indestructive, withrole="alert".
Point the control at the hint and the error with aria-describedby, so screen readers read both. The field does not add the ids for you.
Variants
Section titled “Variants”| Orientation | Use it for |
|---|---|
vertical (default) |
Every text control: label above, hint and error below. |
horizontal |
A Switch or a Checkbox: the control on the left, the label and hint on the right. |
| React | Vue | Flutter | Type | Default | Use |
|---|---|---|---|---|---|
orientation on Field |
orientation on Field |
separate widgets (ShadSwitch has its own label) |
vertical / horizontal |
vertical |
Places the label above or beside the control. |
data-invalid on Field |
data-invalid="true" on Field (a bare data-invalid renders empty and does not match) |
forceErrorText |
boolean / text | none | Marks the field as refused. |
FieldLabel htmlFor |
FieldLabel for |
label |
text | none | Names the control. |
FieldDescription |
FieldDescription |
description |
text | none | The one-sentence hint. |
FieldError |
FieldError |
forceErrorText |
text | none | The backend’s error message. |
FieldSet, FieldLegend |
FieldSet, FieldLegend |
a Text heading over the group |
none | none | Groups controls that answer one question. |
import { useId } from "react"import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"import { Input } from "@/components/ui/input"import { Textarea } from "@/components/ui/textarea"
export default function FieldDemo() { const id = useId() return ( <FieldGroup className="w-full max-w-sm"> {/* The error comes from the backend; the client only shows it. */} <Field data-invalid> <FieldLabel htmlFor={`${id}-title`}>Judul lagu</FieldLabel> <Input id={`${id}-title`} aria-invalid aria-describedby={`${id}-title-hint ${id}-title-error`} /> <FieldDescription id={`${id}-title-hint`}>Tulis sesuai sampul rilis.</FieldDescription> <FieldError id={`${id}-title-error`}>Judul lagunya belum diisi.</FieldError> </Field> <Field> <FieldLabel htmlFor={`${id}-notes`}>Catatan</FieldLabel> <Textarea id={`${id}-notes`} aria-describedby={`${id}-notes-hint`} /> <FieldDescription id={`${id}-notes-hint`}>Opsional, untuk tim rilis.</FieldDescription> </Field> </FieldGroup> )}<script setup lang="ts">import { useId } from "vue"import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field"import { Input } from "@/components/ui/input"import { Textarea } from "@/components/ui/textarea"
const id = useId()</script>
<template> <FieldGroup class="w-full max-w-sm"> <!-- The error comes from the backend; the client only shows it. --> <Field data-invalid="true"> <FieldLabel :for="`${id}-title`">Judul lagu</FieldLabel> <Input :id="`${id}-title`" aria-invalid="true" :aria-describedby="`${id}-title-hint ${id}-title-error`" /> <FieldDescription :id="`${id}-title-hint`">Tulis sesuai sampul rilis.</FieldDescription> <FieldError :id="`${id}-title-error`">Judul lagunya belum diisi.</FieldError> </Field> <Field> <FieldLabel :for="`${id}-notes`">Catatan</FieldLabel> <Textarea :id="`${id}-notes`" :aria-describedby="`${id}-notes-hint`" /> <FieldDescription :id="`${id}-notes-hint`">Opsional, untuk tim rilis.</FieldDescription> </Field> </FieldGroup></template>import 'package:flutter/widgets.dart';import 'package:shadcn_ui/shadcn_ui.dart';
class FieldDemo extends StatelessWidget { const FieldDemo({super.key});
@override Widget build(BuildContext context) { return ConstrainedBox( constraints: const BoxConstraints(maxWidth: 384), child: Column( mainAxisSize: MainAxisSize.min, crossAxisAlignment: CrossAxisAlignment.stretch, spacing: 24, children: [ // The error comes from the backend; the field only shows it. ShadInputFormField( id: 'title', label: const Text('Judul lagu'), description: const Text('Tulis sesuai sampul rilis.'), forceErrorText: 'Judul lagunya belum diisi.', ), ShadTextareaFormField( id: 'notes', label: const Text('Catatan'), description: const Text('Opsional, untuk tim rilis.'), ), ], ), ); }}Install
Section titled “Install”npx shadcn@latest add https://design.sosialoka.tech/r/react/field.jsonnpx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/field.jsonAccessibility
Section titled “Accessibility”- Every control has a visible label tied to it with
htmlFor/for. - An invalid control has
aria-invalid="true"and anaria-describedbythat lists the hint id and the error id. - The error has
role="alert", so it is announced when it appears. - A
FieldSetnames its group with itsFieldLegend.
