Skip to content
themes.dev
    Style: Wireframe

    Components · Forms

    Field

    A label, a control, a line of help and the error message, wired with aria-describedby and aria-invalid; a fieldset for a set of checkboxes.

    47% of the 2,189 real sites we studied have a form (1,019 sites).

    Lowercase letters, numbers and dashes.

    We send the receipt here.

    Enter an email address with an @, like ada@example.com.

    Your plan has no seats left.

    Email me about

    One email at most per week.

    Both previews render the same markup; the HTML tab below is that markup without a framework.

    Install

    React
    npx shadcn@latest add https://www.themes.dev/ui/r/field.json
    Astro
    npx shadcn@latest add https://www.themes.dev/ui/r/astro/field.json

    Or copy the files below into your project. They need clsx, tailwind-merge, and the themes.dev UI theme. The HTML needs only the compiled CSS.

    field.tsx
    import type { ReactNode } from 'react';
    import { cn } from '@/lib/utils';
    import { labelClasses } from '../label/label.variants';
    import { describedBy, field, fieldControl, type FieldTexts } from './field.variants';
    
    export interface FieldProps extends FieldTexts {
      label: string;
      /** Adds "(optional)" to the label. Mark the few optional fields, not the many required ones. */
      optional?: boolean;
      /** A fieldset with a legend, for a set of checkboxes or switches; `id` then only names the texts. */
      group?: boolean;
      /** The control: `<Input {...fieldControl({ id, description, error })} />`. */
      children: ReactNode;
      className?: string;
    }
    
    /** A label, a control, a line of help and the error, wired together. */
    export function Field({ id, label, description, error, optional, group, children, className }: FieldProps) {
      const invalid = error ? '' : undefined;
      if (group)
        return (
          <fieldset aria-describedby={describedBy({ id, description, error })} data-invalid={invalid} className={cn(field.group, className)}>
            <legend className={field.legend}>{label}{optional && <span className={field.optional}> (optional)</span>}</legend>
            <div className={field.options}>{children}</div>
            {description && <p id={`${id}-description`} className={field.description}>{description}</p>}
            {error && <p id={`${id}-error`} className={field.error}>{error}</p>}
          </fieldset>
        );
      return (
        <div data-invalid={invalid} className={cn(field.root, className)}>
          <label htmlFor={id} className={labelClasses}>{label}{optional && <span className={field.optional}>(optional)</span>}</label>
          {children}
          {description && <p id={`${id}-description`} className={field.description}>{description}</p>}
          {error && <p id={`${id}-error`} className={field.error}>{error}</p>}
        </div>
      );
    }
    export { field as fieldClasses, fieldControl };
    field.variants.ts
    /** A field: the label, the control, a line of help and the error, wired together. The control is yours (Input,
     *  Textarea, Select, a date field); spread `fieldControl()` on it so its id, aria-describedby and aria-invalid match
     *  the texts. `group` makes it a fieldset with a legend, for a set of checkboxes or switches. No JavaScript. */
    export const field = {
      root: 'grid min-w-0 gap-2',
      // "(optional)" is part of the label, so it is read with it; the minority is marked, in words.
      optional: 'font-normal text-muted-foreground',
      description: 'text-sm text-pretty text-muted-foreground',
      // The message is the error; the colour only repeats it.
      error: 'text-sm font-medium text-pretty text-destructive',
      group: 'm-0 grid min-w-0 gap-2 border-0 p-0',
      legend: 'mb-3 p-0 text-sm leading-none font-medium',
      options: 'grid gap-3',
    };
    
    export type FieldTexts = {
      /** The control's id; the texts get `<id>-description` and `<id>-error`. Unique on the page. */
      id: string;
      description?: string;
      /** The error message. With it the control is invalid. */
      error?: string;
    };
    
    /** The ids of the texts that describe the control: the error first, then the help. */
    export const describedBy = ({ id, description, error }: FieldTexts) =>
      [error && `${id}-error`, description && `${id}-description`].filter(Boolean).join(' ') || undefined;
    
    /** Props for the control inside a Field: `<Input {...fieldControl({ id, description, error })} />`. */
    export const fieldControl = (texts: FieldTexts) => ({
      id: texts.id,
      'aria-describedby': describedBy(texts),
      'aria-invalid': texts.error ? ('true' as const) : undefined,
    });