Skip to Content
BBRICKSv0.7.4
KitForms

FormField

The mock's .field: a bold label, the control, a hint and an error. The control gets the id, its description (hint + error) and aria-invalid, so the error is read with the field, not just shown. as="group" (or "fieldset") labels content that is not one input (a ChoiceGroup, a tag-only field) the same way; adornment puts a tag or a note after the label.

import { FormField } from '@ergasti/bricks';

Examples

Hint and error

The label is tied to the control, the hint and the error are read with it, and the error also turns the control's outline red. Pass one native control as the child.

Code
import { useState } from 'react';
import { FormField } from '@ergasti/bricks';

function Fields() {
  const [name, setName] = useState('');
  return (
    <div style={{ maxWidth: 360 }}>
      <FormField label="Group name" error={name.trim() === '' ? 'Give the group a name.' : undefined}>
        <input placeholder="Top sellers" value={name} onChange={(event) => setName(event.target.value)} />
      </FormField>
      <FormField label="Who can join"><select><option>Any group</option><option>Top sellers</option></select></FormField>
      <FormField label="Notes for the team" hint="Only your team sees this."><textarea /></FormField>
      <FormField label="Notify the creators"><input type="checkbox" defaultChecked /></FormField>
    </div>
  );
}

A field that is not one input

as="group" labels a set of choices or a tag-only field with a <span> (the field is a named group, described by its hint); as="fieldset" uses a fieldset and legend. adornment puts a tag or a note after the label.

Code
import { useState } from 'react';
import { FormField, Muted, Pill } from '@ergasti/bricks';

function Group() {
  const [earn, setEarn] = useState('pct');
  return (
    <div style={{ maxWidth: 360 }}>
      <FormField as="fieldset" label="How creators earn" hint="Applies to new orders.">
        <label><input type="radio" name="ex-earn" checked={earn === 'pct'} onChange={() => setEarn('pct')} /> % of sale</label>{' '}
        <label><input type="radio" name="ex-earn" checked={earn === 'egp'} onChange={() => setEarn('egp')} /> Fixed per item</label>
      </FormField>
      <FormField as="group" label="Tier bonus" hint="Elite creators may get more." adornment={<Muted>(not decided)</Muted>}>
        <div><Pill tone="warn">Open · R10</Pill></div>
      </FormField>
    </div>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses FormField. Written in docs/content/components/FormField.md; the props above are read from the code, which wins where the two disagree.

A labelled form row that wires one control to its label, hint and error; wrap every input, select or textarea in a form with it.

It is the mock's .field: a bold 13px label, the control, a muted hint and a red error, stacked 6px apart with 16px under the row. It clones its single child to add the id, aria-describedby (hint + error) and aria-invalid, so the error is announced with the field. It styles plain <input>, <select> and <textarea> children to the v3 field look (42px, radius 12). Used in every brand modal form (group, special commission, challenge request) and the PR Portal's dialogs.

Anatomy

  1. Row: .kit-field, flex column, 6px gap, margin-block-end: 16px.
  2. Label: <label htmlFor>, 13px / 700 --ink.
  3. Control: your child; inputs and selects 42px (--field-h), padding 10px 14px, 1px --line, radius --field-radius (12px); textarea min 96px, vertical resize; select with the kit chevron.
  4. Hint (optional): .kit-hint, 12px --ink-3.
  5. Error (optional): .kit-field-err, 12px / 600 --bad.

Variants

ChildLookWhen to use
<input>42px fieldText, numbers, dates.
<select>42px with chevron (left in RTL)Short option lists ("Who can join").
<textarea>96px min, resizableNotes ("Notes for the team").
checkbox / radio18px, --rasp accentSingle toggles (prefer Switch / ChoiceGroup).

States

StateTrigger
Default—
Hoverborder #CFD1DA.
Focusborder --rasp + --focus-ring-field.
Read-onlyreadOnly on the input: --soft background, --ink-2 text.
Disableddisabled on the child (native).
Errorerror set: message under the field, aria-invalid on the control, --bad border.
With hinthint set; hint and error are both in aria-describedby.

Usage

<FormField label="Challenge name" hint="Creators see this name">
  <input value={title} onChange={(e) => setTitle(e.target.value)} />
</FormField>
<FormField label="Gift quantity" error={qty > 32 ? 'Only 32 left in stock.' : undefined}>
  <input type="number" inputMode="numeric" value={qty} onChange={(e) => setQty(+e.target.value)} />
</FormField>
// New group modal: name, members, actions
const [name, setName] = useState('');
const [group, setGroup] = useState('Any group');

<Modal title="New group" open onClose={close} footer={<><Button onClick={close}>Cancel</Button><Button variant="rasp" onClick={save}>Create group</Button></>}>
  <FormField label="Group name" hint="Only your team sees this." error={errors.name}>
    <input value={name} onChange={(e) => setName(e.target.value)} />
  </FormField>
  <FormField label="Who can join">
    <select value={group} onChange={(e) => setGroup(e.target.value)}><option>Any group</option><option>Top sellers</option></select>
  </FormField>
</Modal>

Where it appears

  • In the v3 mocks: Brand › Creators › New / edit group modal (GroupForm) and special commission modal (SpecialCommissionForm); Brand › Motivation › Request a challenge modal (ChallengeRequestForm); PR Portal › Adjust wallet and TRNDR fee modals, program commission field.
  • Library only: PR Change owner modal, tier change, reason, record gifts and message field dialogs (PR inventory; not drawn in the v3 PR mock).

Guidelines

Do

  • Write errors as the fix: "Only 32 left in stock."
  • Keep hints to one line; drop them when the label is enough.
  • Show errors after submit or blur, not on every keystroke.

Don't

  • Don't pass a fragment or two controls; it clones exactly one element.
  • Don't put the label inside the placeholder.
  • Don't use it for a group of radios; use ChoiceGroup (a fieldset).

RTL and Arabic

  • Column layout is direction-neutral; select chevron moves to the left in RTL.
  • Arabic label example: "اسم المجموعة", hint "فريقك بس اللي بيشوفها."; numbers typed stay in Latin digits.

Tokens

--ink, --ink-2, --ink-3, --bad, --line, --card, --soft, --rasp, --field-h, --field-radius, --focus-ring-field, --kit-chevron, --min-touch-target.

Accessibility

  • <label for> names the control; hint and error ids go in aria-describedby so they are read with it.
  • aria-invalid="true" on error. Pair with a form-level error summary for long forms.
  • Focus ring is the field ring (--focus-ring-field), never removed.

Found in the source

  • Roles in the markup: group.
  • ARIA attributes set: aria-describedby, aria-invalid, aria-labelledby.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Muted · Pill · SaveBar · SearchBox · Segmented

Source

src/kit/patterns/FormField.tsx (line 34) on GitHub.

On this page