Field

Anatomy

import {Field, TextField} from '@staffbase/design';

<Field.Root>
  <Field.Label />
  <Field.Description />
  {/* Form control goes here */}
  <Field.Error />
</Field.Root>

Examples

Required label

Invalid state

API reference

Root

Provides field context that links labels, descriptions, and error messages to form controls.

Label

Description

Error

Displays an error message and prepends an alert icon.

When to use

• For any form control that needs a visible, permanently associated label.
• When a control needs helper text that explains the expected value or format.
• When a control needs inline validation feedback shown next to the input itself.
• When label, description, control, and error message must be programmatically linked for assistive technology.

When not to use

• Don’t use a Field to present read-only content or plain text — use body text instead.
• Don’t use Field.Error for form-level or page-level messages — use Banner instead.
• Don’t use Field.Description for help that only appears on demand — use Tooltip instead.
• Don’t build a labelless search box out of a Field — use SearchInput instead.
• Don’t use a Field.Label as a section heading — use a heading element instead.

How to use

Structure

• Wrap exactly one form control in each Field.Root.
• Order the children as label, description, control, and error message.
• Set the field width on Field.Root and let the control fill the available width.
• Rely on the built-in spacing between the label, description, control, and error message instead of adding your own margins.

Labels

• Give every field a visible label rendered with Field.Label.
• Mark required fields with the requiredLabel prop, such as requiredLabel="Required".
• Use one marking convention per form: mark the required fields, or — when nearly all fields are required — mark only the optional ones with requiredLabel="Optional".
• Don’t use placeholder text in place of a label.

Descriptions & placeholders

• Add Field.Description when users need guidance that stays visible while they type.
• Keep the description between the label and the control so it is read before input starts.
• Add placeholder text only when it shows something the label and description don’t, such as an example value.
• Don’t put instructions in placeholder text — it disappears as soon as the user starts typing.
• Keep placeholder text short: it is truncated in narrow fields and scrolls out of view while typing.

Validation & errors

• Set invalid on Field.Root and render Field.Error to show validation feedback below the control.
• Show one error message per field at a time.
• Validate on blur or on submit rather than on every keystroke.
• Remove the error as soon as the value becomes valid.
• Replace the description with the error message when both would carry the same instruction, so users don’t read the same guidance twice.

Accessibility

• Let Field.Root link the label, description, and error to the control — don’t add your own htmlFor, id, or aria-describedby.
• Add required or aria-required to the control whenever you show a required marker, because the visible “(Required)” text doesn’t set the control’s required state.
• Rely on the alert icon that Field.Error renders with the message, so the error state is never signalled by colour alone.
• Move focus to the first invalid field when a form fails validation on submit.

Content & UX copy

• Write labels in Title Case as a noun or noun phrase, such as Full Name.
• Don’t end a label with a colon or any other punctuation.
• Write descriptions in sentence case, ending with a period.
• Keep the description to one short sentence that helps users complete the field correctly.
• Don’t repeat the label text in the description or in the placeholder.
• Write error messages in sentence case, ending with a period, and don’t use exclamation marks.
• Say what went wrong and how to fix it, such as “Enter an email address in the format name@company.com.”
• Reuse the terms users already see elsewhere in the product.