Form

Forms

Open in Storybook: Form (opens in a new tab)

Overview

A form is native controls, each with a visible label and one message above it. Focus goes where the problem is, and what arrives without focus is said with ariaNotify() on the field: no live region, no toast.

The rule. Pick the control that makes the mistake impossible, then validate what is left. Every control has a visible label, “(required)” or “(optional)” in its text, and one message above it. Judging never moves focus; only a submit does: one error → the field, two or more → the error list heading. Results that arrive without focus are said by one ariaNotify() call on the field; the same words are already in its visible message.

Anatomy

Usage

Use cases

Fields with their hint and an error that gives the fix. Label, format and limits are in the hint before the mistake. Each is the real form and works: answer, pause or submit.

• Email

  Suggest the domain.

  Email (required)

  For your receipt. Example: ana@example.com Error: Email domain looks wrong. Did you mean ana@gmail.com?

  Send my receipt

  type="email" · autocomplete="email" · a hint, then the error

  The error says what is wrong and the fix: “Did you mean ana@gmail.com?”

• Phone

  Format with the country code.

  Phone (required)

  With country code. Example: +39 333 123 4567 Error: Phone has no country code. Add it, as in +39 333 123 4567.

  Save my phone

  type="tel" · the format in the hint

  Never type="number": a phone has a + and spaces.

• Date

  Range in the hint, nearest valid in the error.

  Date (required)

  Monday to Saturday, 1 to 30 November. Error: That day is a Sunday. Try Monday, 23 November.

  Book this day

  type="date" · min and max

  Typing must work. The error offers the next valid day.

• Password

  Rules in the hint.

  Password (required)

  12 characters or more, with a number. Error: Password has 9 characters. Add 3 more.

  Show passwordCreate my account

  autocomplete="new-password" · Show is a button with aria-pressed

  Paste is allowed. Repeat the password only for security.

• Textarea

  Count what is missing.

  Comment (required)

  20 to 500 characters. Error: You have 9, so add 11 more.

  Too shortSend my comment

  textarea · the limit in the hint

  “You have 9, so add 11 more.” says how far, not only that it is short.

• File

  Name, limit, fix.

  Receipt (required)

  PDF or JPG, up to 5 MB.

  Upload my receipt

  type="file" · accept · the types and the size in the hint

  Choose a HEIC picture to see the error: it names the file and the fix.

• Colour

  Offer one that passes.

  Text colour (required)

  Needs 4.5:1 on white. Error: #9a9a9a is 2.8:1 on white. Try #777777 (4.5:1).

  #9a9a9aUse this colour

  type="color" · the value shown as text

  The error measures the contrast and offers the nearest colour that passes.

• Taken name

  Offer two free ones.

  Username (required)

  3 to 20 letters, numbers or dots. Error: “ana” is taken. Try ana.r or ana23.

  Take this name

  autocomplete="username" · spellcheck="false"

  Try “ana”, “admin” or “mica”: they are taken.

• One of 2 to 6

  Radios in a fieldset.

  Delivery (required)

  One message for the whole group.

  StandardExpressPick-up

  Choose delivery

  fieldset + legend · one shared message

  The options are label and input as siblings; each carries aria-invalid.

• One of about 7 or more

  A select, first option empty.

  Country (required)

  Choose a countryItalySpainArgentinaFrancePortugalGermanyIrelandChoose my country

  select · the first option has no value

  Never select multiple: one arrow key replaces the whole selection.

• Several

  A checkbox group.

  Sessions (required)

  Choose 1 or 2.

  MondayTuesdayWednesday

  Book my sessions

  fieldset + legend · limits in the hint and the error

  A group cannot be required: the legend says it.

• Booking

  A whole form: errors, review and result.

  Book a tasting

  All fields are required unless marked (optional).

  Full name

  As on your ID.

  Email

  For your receipt. Example: ana@example.com

  Phone (optional)

  With country code. Example: +39 333 123 4567

  Date

  Monday to Saturday, 1 to 30 November.

  Seats

  Up to 4 per booking.

  1234

  Country

  Choose a countryItalySpainArgentinaFrancePortugalGermanyIreland

  Why we ask for your country

  We show prices in your currency and check delivery.

  I accept the termsReview my booking

  form named by its heading · novalidate · the error list

  Submit it empty, then with one mistake, then right.

Input types

The rule. Pick the type for the data, not for the look. The type sets the role, the keys and the mobile keyboard. When a type fights the user (number for a card number, date for a birth date), use type="text" with inputmode and autocomplete instead. Every type still needs a visible label. All of them follow the field rules: one message above the control, aria-describedby, novalidate with our own messages.

• type="text"

  Any short text: names, postcodes, card numbers.

  Full name

  Role: textbox

  Any text · default keyboard

• type="email"

  An email address.

  Email (required)

  Example: ana@example.com

  Role: textbox

  @ keyboard · autocomplete="email"

• type="password"

  A secret.

  Password

  Show password

  Role: textbox, protected

  autocomplete="current-password" · paste allowed

• type="tel"

  A phone number.

  Phone

  Include the country code

  Role: textbox

  Phone keypad · autocomplete="tel"

• type="url"

  A web address.

  Website

  Start with https://

  Role: textbox

  / and .com keys · autocomplete="url"

• type="search"

  A search query.

  Search coffees

  Search

  Role: searchbox

  Enter submits · Esc may clear · in search

• type="number"

  A count: quantity, guests.

  Quantity

  From 1 to 10

  Role: spinbutton

  ↑ ↓ step · min, max, step announced

• type="range"

  An approximate value.

  Volume

  Shown as a value next to the slider

  40 %

  Role: slider

  ← → ↑ ↓ · Home · End · Page Up/Down

• type="date"

  A calendar date.

  Delivery date

  Format follows the browser’s language

  Role: date (segments: day, month, year)

  Type each segment · ↑ ↓ change it · picker button

• type="time"

  A time of day.

  Pickup time

  Role: time (segments)

  Type or ↑ ↓ per segment · step for seconds

• type="datetime-local"

  Date and time, no zone.

  Tasting starts

  Time in Rome (CET)

  Role: date and time (segments)

  No time zone: say which one

• type="month"

  Month and year.

  Card expiry

  Format: MM/YYYY

  Role: month and year

  Not in Firefox or desktop Safari: falls back to text

• type="week"

  ISO week and year.

  Delivery week

  Role: week and year

  Rarely understood; not in Firefox or desktop Safari

• type="color"

  A colour value.

  Label colour

  Show the name, not only the hex

  Plum · #5e548e

  Role: button that opens a colour picker

  Enter/Space opens the OS picker · value read as hex

• type="checkbox"

  On/off, or many of a set.

  Email me when it is back (optional)

  Role: checkbox

  Space toggles · Tab to each one

• type="radio"

  One of a set.

  Delivery

  Standard · freeExpress · €5.00

  Role: radio, in a group

  One Tab stop · arrows move and select

• type="file"

  An upload.

  Menu (PDF, up to 5 MB)

  Role: button, named by label + chosen file

  Enter/Space opens the file dialog · accept, multiple

• type="hidden"

  Data the server needs.

  Sent with the form: bundle-id = b-2026-11

  Role: none

  Not rendered, not in the accessibility tree, not in the Tab order

• type="submit"

  Sends the form.

  Role: button

  Enter in a field submits · value is the name

• type="reset"

  Clears every field.

  Note (optional)

  Role: button

  Clears every field: avoid

• type="button"

  A scripted action.

  Role: button

  No default action: needs script

• type="image"

  A graphical submit.

  Role: button (submit)

  alt is the name: required

Props

Example

import { Field, FieldGroup, Form } from '@/components/Form'

<Form
  title="Book a tasting"
  convention="All fields are required unless marked (optional)."
  submit="Review my booking"
  onValid={(answers) => review(answers)}
>
  <Field
    name="email"
    label="Email"
    type="email"
    hint="For your receipt. Example: ana@example.com"
    autoComplete="email"
    check={(value) =>
      value.includes('@') ? '' : 'Email has no @. Add it, as in ana@gmail.com.'
    }
  />
  <Field name="phone" label="Phone" type="tel" required={false} />
  <FieldGroup
    name="seats"
    legend="Seats"
    kind="radio"
    inline
    hint="Up to 4 per booking."
    options={[
      { value: '1', label: '1' },
      { value: '2', label: '2', defaultChecked: true },
    ]}
  />
</Form>

Specs

Structure

Per field, in order: label, hint or message, control, help. One column. Submit named for the action.

States

Layout

Markup

<form novalidate aria-labelledby="book-h">
  <h2 id="book-h" tabindex="-1">Book a tasting</h2>
  <label for="email">Email (required)</label>
  <p id="email-msg">For your receipt. Example: ana@example.com</p>
  <input id="email" type="email" required autocomplete="email"
         aria-invalid="false" aria-describedby="email-msg" />

  <fieldset>
    <legend>Sessions (choose 1 or 2, required)</legend>
    <p id="ses-msg">Error: You chose 3 sessions. Untick 1 session.</p>
    <input id="s1" type="checkbox" name="ses" aria-invalid="true" aria-describedby="ses-msg" />
    <label for="s1">Monday</label>
    …
  </fieldset>
</form>

Tokens

Component tokens

Guidelines

Controls by scenario and context

Pick the control that makes the mistake impossible, then validate what is left.

Message

What is wrong, then the fix. In the list: “Field: message”.

Debounce

Delay the judging, never the value in the field or the focus ring. No success criterion or numbered technique asks for it: it serves 3.3.1, 4.1.3 (ariaNotify(), with the words on the page) and 3.2.2.

Success and review

A valid submit goes to a review step. Confirm goes to a result. Both headings take focus and are described by a “Success: …” line that uses the person’s answers.

Feedback by scenario and context

Each row is one scenario from Focus and what is said. Each column shows what that moment gets at that size. The drawings are the real components, small: the field, the list of errors, the buttons, the Success line and the ariaNotify() call.

• Continue
  Solid: required in that context, never dropped

• email.ariaNotify() Email: not correct. Email has no @.

  Dashed: optional, or only if there is room
• ariaNotify()Said with field.ariaNotify(): no element, nothing added to the DOM; the words are in the visible message

Zoom 400% · 320 CSS px. At 200% text messages wrap above the control.

• Submit, one error

  Checkout · one field wrong

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Continue

  Field (focused) · message · Continue

  Focus moves to the field; its message is read with it. No list for one error, no ariaNotify().

  Smaller viewport · 400–639 pxNarrow column or card

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Continue

  Field · Continue

  Same. Message stays above the control.

  Zoom 400% · 320 CSS pxReflow

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Continue

  Field · Continue

  One column. The message wraps; nothing floats over the field.

• Submit, two or more

  Long form

  Live example

  Desktop · 640 px and upFull width, one column of fields

  There are 2 errors

  • Email: Email has no @. Add it, as in ana@gmail.com.
  • Date: Try Monday, 23 November.

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Error list (heading focused) · fields

  Errors rendered first, then focus to the list heading. Links focus the field. Items leave as they are fixed.

  Smaller viewport · 400–639 pxNarrow column or card

  There are 2 errors

  • Email: Email has no @. Add it, as in ana@gmail.com.
  • Date: Try Monday, 23 November.

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Error list · fields

  List at the top of the form, never sticky.

  Zoom 400% · 320 CSS pxReflow

  There are 2 errors

  • Email: Email has no @. Add it, as in ana@gmail.com.
  • Date: Try Monday, 23 November.

  Email (required)

  For your receipt. Example: ana@example.com Error: Email has no @. Add it, as in ana@gmail.com.

  Error list · fields

  List items wrap; heading still takes focus.

• Typing

  Email, then a pause

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Email (required)

  For your receipt. Example: ana@example.com Correct.

  email.ariaNotify() Email: correct.

  Field · message · ariaNotify()

  ariaNotify()

  Visible fix at once. Spoken 1 s after the last key (every key restarts the wait), or at once on blur.

  Smaller viewport · 400–639 pxNarrow column or card

  Email (required)

  For your receipt. Example: ana@example.com Correct.

  email.ariaNotify() Email: correct.

  Field · ariaNotify()

  ariaNotify()

  Same.

  Zoom 400% · 320 CSS pxReflow

  Email (required)

  For your receipt. Example: ana@example.com Correct.

  Field

  ariaNotify()

  Same; the call does not depend on the viewport.

• Fixing a listed error

  Two were listed

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Email (required)

  For your receipt. Example: ana@example.com Fixed. It is correct now.

  email.ariaNotify() Email: fixed. It is correct now. 1 error left.

  Field · “Fixed.” · count · ariaNotify()

  ariaNotify()

  Choosing speaks at once. The count is read from the list as drawn and shown on the field fixed last.

  Smaller viewport · 400–639 pxNarrow column or card

  Email (required)

  For your receipt. Example: ana@example.com Fixed. It is correct now.

  email.ariaNotify() Email: fixed. It is correct now. 1 error left.

  Field · ariaNotify()

  ariaNotify()

  Same.

  Zoom 400% · 320 CSS pxReflow

  Email (required)

  For your receipt. Example: ana@example.com Fixed. It is correct now.

  Field

  ariaNotify()

  Count in the message under the field, never a sticky counter.

• Sign-in failed

  No suggestion: it leaks

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Email (required)

  For your receipt. Example: ana@example.com Error: Email or password is not right.

  Sign in

  Field (focused) · message · Sign in

  One error, so focus goes to the email field. Paste and password managers allowed (3.3.8).

  Smaller viewport · 400–639 pxNarrow column or card

  Email (required)

  For your receipt. Example: ana@example.com Error: Email or password is not right.

  Sign in

  Field · Sign in

  Same.

  Zoom 400% · 320 CSS pxReflow

  Email (required)

  For your receipt. Example: ana@example.com Error: Email or password is not right.

  Field

  Same.

• Review step

  Valid submit

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Check your answers

  Success: Your answers are saved. Check them, then confirm.

  Seats

  2

  Change

  Date

  Monday, 23 November

  Change

  Total

  48 €

  ConfirmBack

  Review heading (focused) · answers · Change · Confirm · Back

  Heading described by “Success: Your answers are saved. Check them, then confirm.” Change → that field.

  Smaller viewport · 400–639 pxNarrow column or card

  Check your answers

  Success: Your answers are saved. Check them, then confirm.

  Seats

  2

  Change

  Date

  Monday, 23 November

  Change

  Total

  48 €

  ConfirmBack

  Heading · answers · Change · Confirm

  Answers stack under each question.

  Zoom 400% · 320 CSS pxReflow

  Check your answers

  Success: Your answers are saved. Check them, then confirm.

  Seats

  2

  Change

  Date

  Monday, 23 November

  Change

  Total

  48 €

  ConfirmBack

  Heading · answers · Change · Confirm

  Buttons full width, 44 px tall, in DOM order.

• Confirmed

  Result page

  Live example

  Desktop · 640 px and upFull width, one column of fields

  Booking confirmed

  Success: 2 seats on Monday, 23 November. Total 48 €. Tickets go to ana@gmail.com.

  Result heading (focused) · Success line

  “Success: what happened, what is next”, with the person’s answers. Same words every time.

  Smaller viewport · 400–639 pxNarrow column or card

  Booking confirmed

  Success: 2 seats on Monday, 23 November. Total 48 €. Tickets go to ana@gmail.com.

  Result heading · Success line

  Same.

  Zoom 400% · 320 CSS pxReflow

  Booking confirmed

  Success: 2 seats on Monday, 23 November. Total 48 €. Tickets go to ana@gmail.com.

  Result heading · Success line

  Same; no toast.

Input attributes

Accessibility

Focus and what is said

Where focus goes and what is said, for every moment of the form.

Announcements

Focus is the announcement for headings and for the field it lands on. Everything that arrives without focus is said with element.ariaNotify(): nothing enters the DOM, no live region. The same words are already in the field’s visible message.

Keyboard

Roles and properties

What the browser exposes, as the tests read it. Nothing here was heard in a screen reader yet.

Support

Yes is run in the browser tests of the component; No is not run here.

WCAG criteria

What each success criterion asks of a form, and what meets it.

Related

This section is still in progress.

References

This section is still in progress.