Forms and inputs

Last modified by Thiago Krieck on 2026/11/18 14:13

Warning
Draft

This page is a draft. The standards on it are proposals still under discussion, so they may change and should not be treated as final yet.

The standard

  • Layout: Forms should use the xform layout, with the label and its hint above the field (dl / dt / dd), and group related fields in a fieldset with a legend, so that every form in XWiki reads the same way.
  • Labels: Every field should have a visible <label for>, since a placeholder disappears as soon as the user types and isn't read reliably by screen readers.
  • Hints: Should go in an xHint right under the label and be linked to the field with aria-describedby, so that screen reader users hear them too. See Hints for when to use them and how to word them.
  • Required fields: Should show (Required) in the label (core.validation.required) and set the required attribute, so that users know before submitting which fields they must fill in.
  • Errors: Should appear right under the field, in the danger color, and say how to fix the problem, such as This field is required. The field should get aria-invalid="true" and the message should be announced (aria-live). Errors about the whole form, such as a failed login, should go in an alert above the form. See Alerts and notifications. 
  • Field types: Should use native inputs (form-control) wherever possible. Pages, users and groups should be picked with the standard suggest pickers, and dates with the date picker, so that the same kind of value is always entered the same way.
  • Buttons: The form's actions should come last, in a single row. See Buttons.

Reference example: the registration page (Register link in the top bar), also used by Administration → Users → Create user. Each field has a visible label, required fields say (Required) in the label, and each field is checked as it is filled in, with a message and an icon under the field that screen readers announce.

forms-reference-registration.png

Form: the registration page, with a field being checked as it is filled in

Hints

A hint is the short text under a label that helps users fill in a field correctly.

  • When to use: A hint should be added only when the label alone isn't enough: to explain what the value is used for, the expected format, or the consequence of a choice. A hint that only repeats the label, such as The new page title under Title, should be left out, since it adds reading time without adding information.
  • Placement: The hint should sit between the label and the field (xHint). For a checkbox, it should sit under the checkbox label. It should be linked to the field with aria-describedby.
  • Wording: One or two short sentences, in sentence case, ending with a period. The first sentence should say what the field does; a second one can say when to choose it. Examples and formats should be introduced with for example.
  • Not a replacement: A hint should never hold information the user needs to avoid an error, such as a required format, unless the field also validates it and explains the error, since many users don't read hints. A placeholder should never be used as a hint.
  • Length: When a field needs more than two sentences, the hint should link to the documentation instead.

Reference examples:

  • Rename page → Create an automatic redirect: Redirect the user to the new page when accessing the old page. Select this option if you don't want to break external links to the old page. The first sentence says what the option does, the second says when to choose it.
  • Administration → Editing: each setting has a one-sentence hint that explains its effect, such as Select the type of editor to use by default for editing the page content. under Default Editor.
forms-checkbox-rename-redirect.png

Checkbox with a hint: Rename page → Create an automatic redirect

forms-hints-select-admin-editing.png

Selects with hints: Administration → Editing

Form elements

  • Text field: Should be used for short free text (<input class="form-control">), with the matching type (email, url, number) so that browsers offer the right keyboard and validation. Reference example: the registration page.
  • Text area: Should be used for text that can span several lines, such as the message in More actions → Share by email.
  • Checkbox: Should be used for a single choice that is either on or off and applies when the form is submitted. The label should sit to the right of the box, be clickable, and describe the "on" state as an action or a statement, such as Create an automatic redirect (Rename page) or Send me a copy (Share by email).
  • Radio buttons: Should be used when the user picks exactly one of a few options (up to about five) that are worth seeing side by side. The group should be a fieldset whose legend asks the question, one option should be selected by default, and each label should sit to the right of its button. Reference example: Share by email → Include the current page with Only as a link (selected by default) and Inline in the message.
  • Select: Should be used when there are more options than radio buttons can comfortably show, or when space is short, such as Default Language and Timezone in Administration → Localization. A setting that can also inherit its value, as in Administration → Editing (Yes, No or the inherited default), should be a select rather than a checkbox, since a checkbox can't express "inherit".
  • Visual choice list: When each option needs an icon or a description to be understood, the options should be shown as a list of tiles that can be filtered, as in More actions → Export (formats) and Create page (page types).
  • Pickers: Pages, users and groups should be chosen with the standard suggest pickers rather than typed by hand, such as Share by email → Send to (users) and Copy page → Copy Location (pages), so that only valid values can be entered.
forms-radio-share.png

Radio buttons: Share by email → Include the current page

forms-choice-list-export.png

Visual choice list: More actions → Export

Notes

  • The automated accessibility check only warns about fields without a label, so a missing label won't fail a build. It should be checked by hand. See Accessibility.

More

Get Connected