# Field (themes.dev UI component)

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. Black and white, dark mode, shadcn-compatible; React, Astro and plain HTML.

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

## 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`
- HTML: https://www.themes.dev/ui/r/html/field.html (with https://www.themes.dev/ui/r/html/caseroom.css)

Page: https://www.themes.dev/ui/components/field/ · Rules for agents: https://www.themes.dev/ui/AGENT.md

## Code

### field.astro

```astro
---
import { cn } from '@/lib/utils';
import { labelClasses } from '../label/label.variants';
import { describedBy, field, type FieldTexts } from './field.variants';

type Props = 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;
  class?: string;
};
const { id, label, description, error, optional, group, class: className } = Astro.props;
const invalid = error ? '' : undefined;
---

{
  group ? (
    <fieldset aria-describedby={describedBy({ id, description, error })} data-invalid={invalid} class={cn(field.group, className)}>
      <legend class={field.legend}>{label}{optional && <span class={field.optional}> (optional)</span>}</legend>
      <div class={field.options}><slot /></div>
      {description && <p id={`${id}-description`} class={field.description}>{description}</p>}
      {error && <p id={`${id}-error`} class={field.error}>{error}</p>}
    </fieldset>
  ) : (
    <div data-invalid={invalid} class={cn(field.root, className)}>
      <label for={id} class={labelClasses}>{label}{optional && <span class={field.optional}>(optional)</span>}</label>
      <slot />
      {description && <p id={`${id}-description`} class={field.description}>{description}</p>}
      {error && <p id={`${id}-error`} class={field.error}>{error}</p>}
    </div>
  )
}
```

### field.tsx

```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

```tsx
/** 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,
});
```
