Overview

Use Input Field to ask for a short, single line of text or a number, such as a pupil's name, a UPN or an email address.

Anatomy

Input Field anatomy

#PartDescription
1LabelSays what to enter. Always visible, except in search, filter bars and table cells.
2Required indicatorAn asterisk, shown when validation.required is set.
3Prompt (optional)A link to a related action, at the right of the label.
4Description (optional)Format hints or context, between the label and the field.
5FieldWhere people type. Carries the appearance, theme, size and state.
6Error messageSays what is wrong and how to fix it. Shown below the field.

When to use

  • Short, free-text answers: names, email addresses, UPNs, class names.
  • Numbers with a wide range, such as marks out of 100: use type="number".

When not to use

Appearance and theme

Use the modern appearance (appearance="modern") on new screens. It has a filled background and no border.

Use the standard appearance (the default in code) only when the background doesn't give the field enough contrast to pass accessibility, and the field needs a border to stand out. Standard has a white background and a grey-700 border.

For the modern appearance, pick the theme that contrasts with the surface behind the field:

  • theme="grey": on white surfaces, such as the page and dialogs.
  • theme="white": on grey surfaces, such as grey panels and filter bars.

Set appearance and theme once on Form and every field inside follows them. Don't mix appearances in one form.

Standard, modern grey on a white surface, and modern white on a grey surface

Size

  • md (default, 40px): use it in forms.
  • sm (32px): use it in dense tables and filter bars.
  • lg (48px): use it on pupil-facing and sign-in screens.
  • xl (64px): use it only in the question container, when the pupil has chosen the large size in settings.

Give fields in the same row the same size.

The available sizes side by side

Label and help text

  • Label: always visible, short, and says what to enter ("Email address", not "Enter your email address here").
  • Required: a required field shows an asterisk after its label. Add a line above the form: "Fields marked * are required".
  • Description: put format hints and context people need before they type in description. It sits between the label and the field.
  • Prompt: use prompt only for a link to a related action, such as "Forgotten your password?". It sits at the right of the label.
  • Placeholder: use it only for an example value, such as "[email protected]". Never put instructions or the label in the placeholder: it disappears as soon as people type.

Only hide the label (hideLabel) in search and filter bars, and for inline edits inside table cells, where a heading or column header already says what the field is for. The label stays available to screen readers.

A field with its label, required indicator and help text

Validation and errors

Errors appear when people leave the field, and again when they submit the form. An error clears as soon as the value is fixed. This is how Form behaves by default (validationMode="onBlur").

In the error state:

  • Standard: the field border turns danger, and the error message below the field is danger.
  • Modern: the field background turns dangerLight and its text dangerDark. The error message is dangerDark.

Write error messages that say what's wrong and how to fix it, such as "Enter the pupil's UPN" or "Enter an email address in the correct format, like [email protected]". Don't write "Invalid input" or "Error".

The error state in the standard and modern appearances

Disabled and read-only

  • Disabled: people can't change the value and it isn't sent with the form. If the reason isn't obvious, explain it in the description.
  • Read-only (readOnly): people can't change the value, but can still focus it, select it and copy it, as in any browser. A lock icon shows at the end of the field. The value is sent with the form. Use it for values that are fixed by the system, such as a pupil's UPN once it's been imported.

A disabled field and a read-only field with a lock icon

Input type

Set type to match the data: email, tel, url, number or text (default). It brings up the right keyboard on phones and tablets. type="number" shows a numeric keyboard and only accepts digits.

Accessibility

  • Always give the field a label. The placeholder is never the label. With hideLabel, the label is still read by screen readers.
  • Never rely on colour alone. Errors always come with a text message below the field.
  • Mark required fields in text. Add "Fields marked * are required" above the form: the asterisk isn't read by screen readers.
  • Explain disabled fields in the description when the reason isn't obvious.

Do's and Don'ts

    Do

    Use a clear, visible label, and an example value as the placeholder.

    Don't

    Use the placeholder as the label. It disappears as soon as people start typing.

    Do

    Say what's wrong and how to fix it, next to the field.

    Don't

    Show a vague error, or only a red border, without saying what to do.

Options

OptionIn codeValuesDefault
Appearanceappearancestandard, modernstandard
Theme (modern only)themegrey, whitegrey
Sizesizesm, md, lg, xlmd
Typetypetext, email, number, tel, url, password, searchtext
LabellabelTextRequired
Hide labelhideLabeltrue, falsefalse
DescriptiondescriptionTextNone
Promptprompt{ label, link } or { label, onClick }None
Validationvalidationrequired, pattern, min, max and other rules, each with a messageNone
Disableddisabledtrue, falsefalse
Read-onlyreadOnlytrue, false. Can be focused and selected, not changed. Shows a lock icon.false

Related