Skip to content

Latest commit

 

History

History
78 lines (63 loc) · 4.4 KB

field.md

File metadata and controls

78 lines (63 loc) · 4.4 KB

Field and Fieldset

Field gives one control its label, description and error, wired for screen readers. Fieldset groups checkboxes, radios or switches under one legend.

Example

import { Checkbox, Field, Fieldset, Input } from "@usememos/ui";

<Field.Root invalid={!!error}>
  <Field.Label>Email</Field.Label>
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  <Field.Description>We only use it to sign you in.</Field.Description>
  <Field.Error match>{error}</Field.Error>
</Field.Root>

<Fieldset.Root>
  <Fieldset.Legend>Notifications</Fieldset.Legend>
  <Field.Root>
    <Field.Label><Checkbox defaultChecked /> Mentions</Field.Label>
  </Field.Root>
  <Field.Root>
    <Field.Label><Checkbox /> Weekly digest</Field.Label>
  </Field.Root>
</Fieldset.Root>

Parts

Part Base UI part Renders
Field.Root Field.Root A <div> around one control. Takes size and passes it to the control, and orientation
Field.Label Field.Label A <label>: above a text control, or around a Checkbox, Switch or Radio
Field.Item Field.Item A <div> around one option of a radio or checkbox group in one field
Field.Description Field.Description A <p> of help under the control
Field.Error Field.Error A <div> with a CircleAlert icon and the message, while the field is invalid
Fieldset.Root Fieldset.Root A <fieldset>. Takes size
Fieldset.Legend Fieldset.Legend The group's name

Props

interface Field.RootProps extends BaseField.Root.Props {
  size?: "sm" | "md"; // passed to the control inside
  orientation?: "vertical" | "horizontal"; // default "vertical"; horizontal: label first, control at the end of the row
}
interface Fieldset.RootProps extends BaseFieldset.Root.Props {
  size?: "sm" | "md"; // passed to every control inside
}

Base UI's props pass through: name, invalid, disabled, validate, validationMode on Field.Root; match on Field.Error (true shows it whenever the field is invalid, or a ValidityState key such as "valueMissing").

Rules

  • Set invalid from the app when the server rejects a value; use validate for client checks.

  • Write the error as how to fix the problem.

  • Put a Checkbox, Switch or Radio inside its Field.Label, so clicking the text toggles it.

  • For a settings row (a name, an optional description, and a Switch or Select at the end), use orientation="horizontal" and put the control after Field.Label and Field.Description, not inside the label:

    <Field.Root orientation="horizontal">
      <Field.Label>Compact mode</Field.Label>
      <Field.Description>Show more notes on one screen.</Field.Description>
      <Switch checked={compact} onCheckedChange={setCompact} />
    </Field.Root>
    
  • A radio group is one field: Field.Root holds Fieldset.Root render={<RadioGroup />}, and each radio sits in a Field.Item. See RadioGroup.

  • Stack fields space-4 apart. Group them with a heading or a Fieldset. On a settings page, put horizontal Fields in a List, one per Item.

  • Never use a placeholder as the only label.

Style

  • Label: label style (14px, 500), text, space-1 above the control. It stays 500 when it wraps a Checkbox, Switch or Radio, and in horizontal rows. A control's name is distinct from the value someone enters or selects, which stays 400.
  • Horizontal: a two-column grid. The label and description fill the first column; the control sits at the end, centered on them, space-4 from the text. The error spans the row under them. In a Popover, the horizontal label uses text-secondary; in forms, settings pages and Dialogs it uses text. Vertical labels keep text in either context. See Settings.
  • Disabled labels use text-disabled, including inside a Popover, without changing weight. This applies when the Field is disabled or a directly wrapped Checkbox, Switch or Radio is individually disabled. Hover, focus, checked and invalid states do not change a label's contextual color; errors retain their separate danger text.
  • Description and error: caption (13px), space-1 below the control. The error hides the description and turns the control's edge danger.
  • Fieldset: its options stack space-3 apart. The legend (label) sits space-2 above the first one, closer than the options are to each other, so it reads as their name.