Skip to content

Form Components

[03] Form Components

Forms

Build a React form with VaneUI: Field and native validation, controlled and uncontrolled inputs, error messages, control values, submit, reset and button types.

Edit this page

A VaneUI form is a native <form> element with VaneUI controls inside it. Input, Textarea, Select, Checkbox, Radio and Switch each render a native form control, so name, required, FormData, submit and reset behave as they do in plain HTML. Field adds the label, help text and error message. Button and IconButton set no type, so inside a <form> each one submits the form unless it has type="button".

A form with Field and native validation

Wrap the fields in a <form> and give each control a name. The browser checks required, type="email", minLength and pattern before it fires onSubmit, and shows its own message at the first control that fails. required set on a Field reaches the control inside it. name and the other native attributes go on the control.

Used to sign in.

At least 12 characters.

const [message, setMessage] = useState('');
return (
<form
onSubmit={(event) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setMessage(`Account created for ${data.get('name')} (${data.get('email')}).`);
}}
>
<Col>
<Field label="Name" required>
<Input name="name" autoComplete="name"/>
</Field>
<Field label="Email" description="Used to sign in." required>
<Input type="email" name="email" autoComplete="email"/>
</Field>
<Field label="Password" description="At least 12 characters." required>
<Input
type="password"
name="password"
minLength={12}
autoComplete="new-password"
/>
</Field>
<Button type="submit" md filled>Create account</Button>
{message && <Alert success polite>{message}</Alert>}
</Col>
</form>
);

event.preventDefault() stops the browser from sending the form itself and reloading the page, and FormData reads the values of the named controls. Pressing Enter in a text field submits the form too. A Field that renders its own control (<Field type="email" label="Email"/>) takes native attributes such as name and required directly.

Controlled and uncontrolled inputs

The inputs above are uncontrolled: the DOM holds each value, defaultValue sets the starting text, and the submit handler reads the result. A controlled input takes value and onChange, and React state holds the value on every keystroke.

Address: example.com/your-workspace

const [name, setName] = useState('');
const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-');
return (
<Field
label="Workspace name"
description={`Address: example.com/${slug || 'your-workspace'}`}
>
<Input value={name} onChange={(event) => setName(event.target.value)}/>
</Field>
);

Use uncontrolled inputs when the values are needed only on submit. Use a controlled input when something on screen depends on the value while the user types, such as a preview or a character count, or when JavaScript validates the value.

Showing errors with the Field error prop

To show messages of your own, add noValidate to the form, validate in JavaScript, and pass the message to the error prop of the Field. Field renders the message, marks the control with aria-invalid="true", and links the message to the control with aria-describedby. Check a value when its field loses focus and again on submit.

const [email, setEmail] = useState('');
const [error, setError] = useState<string>();
const [failed, setFailed] = useState(0);
const [sent, setSent] = useState(false);
const emailRef = useRef<HTMLInputElement>(null);
const check = (value: string) =>
/^\S+@\S+\.\S+$/.test(value)
? undefined
: 'Enter an email address, such as you@company.com.';
useEffect(() => {
if (failed > 0) emailRef.current?.focus();
}, [failed]);
return (
<form
noValidate
onSubmit={(event) => {
event.preventDefault();
const problem = check(email);
setError(problem);
setSent(!problem);
if (problem) setFailed(failed + 1);
}}
>
<Col>
<Field label="Work email" error={error}>
<Input
ref={emailRef}
type="email"
name="email"
value={email}
onChange={(event) => setEmail(event.target.value)}
onBlur={() => setError(check(email))}
/>
</Field>
<Button type="submit" md filled>Send invite</Button>
{sent && <Alert success polite>Invite sent to {email}.</Alert>}
</Col>
</form>
);

Three details in this example carry over to any form:

  • error stays undefined while the field is valid. Field treats every other value except null and false as an error, an empty string included.
  • The input is controlled, so the value is in state when the check runs.
  • After a failed submit, the effect moves focus to the invalid control, so a keyboard or screen reader user lands on it and hears the message. With several fields, focus the first one that failed.

A server error goes into error the same way, from the response. When the message is shown somewhere else, such as an Alert above the form, invalid on the Field marks the control without rendering text. That prop needs @vaneui/ui 1.5.0 or later.

Values of Checkbox, RadioGroup, Switch and Select

Each control reports its value through the native element it renders.

ControlUncontrolledControlledEntry in FormData
Input, TextareadefaultValuevalue and onChange, read event.target.valueThe text, also when it is empty
SelectdefaultValuevalue and onChange, read event.target.valueThe value of the selected option
RadioGroupdefaultValuevalue and onChange, read event.target.valueThe value of the checked Radio, or no entry when none is checked
Checkbox, SwitchdefaultCheckedchecked and onChange, read event.target.checkedIts value when checked ("on" when no value is set), or no entry when unchecked

Give a RadioGroup a name in a form that is submitted. Without one it generates a name, which keeps the options mutually exclusive but is no use as a key in FormData.

const [entries, setEntries] = useState('');
return (
<form
onSubmit={(event) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setEntries(JSON.stringify(Object.fromEntries(data), null, 2));
}}
>
<Col>
<Field label="Plan">
<RadioGroup name="plan" defaultValue="pro">
<Label row itemsCenter><Radio value="free"/> Free</Label>
<Label row itemsCenter><Radio value="pro"/> Pro</Label>
</RadioGroup>
</Field>
<Field label="Region">
<Select name="region" placeholder="Select a region" required>
<option value="cy">Cyprus</option>
<option value="ee">Estonia</option>
<option value="pt">Portugal</option>
</Select>
</Field>
<Label row itemsCenter>
<Checkbox name="terms" value="accepted" required/>
I accept the terms
</Label>
<Label row itemsCenter>
<Checkbox name="updates"/>
Email me product updates
</Label>
<Button type="submit" md filled>Save</Button>
{entries && <Text tag="pre" sm fontMono>{entries}</Text>}
</Col>
</form>
);

placeholder with required on a Select makes the user pick an option: the prompt has an empty value, so the browser rejects it. Several checkboxes can share one name, and data.getAll(name) returns every checked value.

A Switch reports its value the same way as a Checkbox. It is meant for a setting that applies at once, so it usually sits outside the submit flow as a controlled input, like the controls below. onChange on a RadioGroup receives the change event of the Radio that was picked.

plan: pro, region: ee, updates: false, compact: true

const [plan, setPlan] = useState('pro');
const [region, setRegion] = useState('ee');
const [updates, setUpdates] = useState(false);
const [compact, setCompact] = useState(true);
return (
<Col>
<Field label="Plan">
<RadioGroup value={plan} onChange={(event) => setPlan(event.target.value)}>
<Label row itemsCenter><Radio value="free"/> Free</Label>
<Label row itemsCenter><Radio value="pro"/> Pro</Label>
</RadioGroup>
</Field>
<Field label="Region">
<Select value={region} onChange={(event) => setRegion(event.target.value)}>
<option value="cy">Cyprus</option>
<option value="ee">Estonia</option>
<option value="pt">Portugal</option>
</Select>
</Field>
<Label row itemsCenter>
<Checkbox
checked={updates}
onChange={(event) => setUpdates(event.target.checked)}
/>
Email me product updates
</Label>
<Label row itemsCenter>
<Switch
checked={compact}
onChange={(event) => setCompact(event.target.checked)}
/>
Compact layout
</Label>
<Text sm secondary>
plan: {plan}, region: {region},
updates: {String(updates)}, compact: {String(compact)}
</Text>
</Col>
);

Disabled and read-only controls

disabled takes a control out of the form: it cannot be focused, its value is left out of FormData, and validation skips it. readOnly keeps the control in the form: it can be focused and its value is submitted, but the user cannot change it. Checkbox, Radio and Switch have no native read-only state, so VaneUI cancels the click, and Checkbox and Switch also carry aria-readonly. A read-only toggle does not call onChange (@vaneui/ui 1.6.0 or later; earlier versions called it with the flipped value). A Field passes disabled and readOnly to the control inside it, and a disabled Field also dims its label.

Submitted, but not editable.

Left out of the form data.

const [entries, setEntries] = useState('');
return (
<form
onSubmit={(event) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setEntries(JSON.stringify(Object.fromEntries(data), null, 2));
}}
>
<Col>
<Field label="Account ID" description="Submitted, but not editable." readOnly>
<Input name="accountId" defaultValue="acct_4821"/>
</Field>
<Field label="Legacy plan" description="Left out of the form data." disabled>
<Input name="legacyPlan" defaultValue="Starter 2019"/>
</Field>
<Label row itemsCenter>
<Checkbox name="auditLog" defaultChecked readOnly/>
Audit log, required by your plan
</Label>
<Button type="submit" md filled>Save</Button>
{entries && <Text tag="pre" sm fontMono>{entries}</Text>}
</Col>
</form>
);

Submit, reset and button types

Button and IconButton render a <button> with no type attribute, and a button with no type inside a form is a submit button. A Cancel button, a password toggle or any other button that only runs an onClick therefore submits the form too, unless it has type="button". Set type on every button in a form.

typeEffect inside a <form>Use it for
not setSubmits the formAvoid in a form: state the type
submitRuns native validation, then fires onSubmitThe action that sends the form
buttonNone, only onClick runsCancel, a password toggle, a menu trigger
resetRestores uncontrolled controls to their starting values and fires onResetA reset button

Nothing submitted yet.

const [status, setStatus] = useState('Nothing submitted yet.');
const [saving, setSaving] = useState(false);
const [visible, setVisible] = useState(false);
return (
<form
onSubmit={(event) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSaving(true);
// stands in for a request
setTimeout(() => {
setSaving(false);
setStatus(`Saved display name "${data.get('displayName')}".`);
}, 800);
}}
onReset={() => setStatus('Reset to the starting values.')}
>
<Col>
<Field label="Display name" required>
<Input name="displayName" defaultValue="Alex Rivera"/>
</Field>
<Row itemsEnd>
<Field label="Password" flex1>
<Input
type={visible ? 'text' : 'password'}
name="password"
defaultValue="correct horse"
/>
</Field>
<IconButton
md
type="button"
aria-label="Show password"
aria-pressed={visible}
onClick={() => setVisible(!visible)}
>
{visible ? <EyeOff/> : <Eye/>}
</IconButton>
</Row>
<Row>
<Button type="submit" md filled loading={saving}>Save</Button>
<Button type="reset" md>Reset</Button>
<Button
type="button"
md
secondary
onClick={() => setStatus('Cancelled. Nothing was submitted.')}
>
Cancel
</Button>
</Row>
<Text sm secondary>{status}</Text>
</Col>
</form>
);

loading on the submit Button disables it while the request runs, so a second click cannot submit the form again. type="reset" restores defaultValue and defaultChecked. Controlled values live in state, so set them back in an onReset handler.

Pressing Enter in a text field activates the first submit button in the form. A button with no type counts as one, so an untyped button placed before the real submit button receives that click.

NavLink without href and ModalCloseButton already render type="button". A Button with href renders an <a>, which never submits.