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
- Row:
.kit-field, flex column, 6px gap,margin-block-end: 16px. - Label:
<label htmlFor>, 13px / 700--ink. - 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. - Hint (optional):
.kit-hint, 12px--ink-3. - Error (optional):
.kit-field-err, 12px / 600--bad.
Variants
| Child | Look | When to use |
|---|---|---|
<input> | 42px field | Text, numbers, dates. |
<select> | 42px with chevron (left in RTL) | Short option lists ("Who can join"). |
<textarea> | 96px min, resizable | Notes ("Notes for the team"). |
| checkbox / radio | 18px, --rasp accent | Single toggles (prefer Switch / ChoiceGroup). |
States
| State | Trigger |
|---|---|
| Default | — |
| Hover | border #CFD1DA. |
| Focus | border --rasp + --focus-ring-field. |
| Read-only | readOnly on the input: --soft background, --ink-2 text. |
| Disabled | disabled on the child (native). |
| Error | error set: message under the field, aria-invalid on the control, --bad border. |
| With hint | hint 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 inaria-describedbyso 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.
Related
CommissionInput: the % / EGP field built on the same look.ChoiceGroup(PR): radio cards as a fieldset.Switch,SelectBox: controls with their own labels.
See also: Muted · Pill · SaveBar · SearchBox · Segmented
Source
src/kit/patterns/FormField.tsx (line 34) on GitHub.