Skip to main content

This is a guide on using the GOV.UK Design System Form Builder

  1. Index
  2. Labels, hints and legends

Labels, hints and legends

Labels

All form helpers that generate a single input element automatically associate it with a corresponding label.

By default, the label text is set to the capitalised name of the attribute. If the attribute contains underscores they will be left in. This is intentional behaviour to prompt the developer to add some more suitable text.

An unconfigured label

Input

= f.govuk_text_field :favourite_colour

Rendered output

Labels are customised by passing in a hash of options with the following keys:

text
The actual text that forms the label
tag
The HTML tag that the label will be wrapped in. This is useful on pages where the label is also the main header where the tag should be h1
size
The label size which follows the usual GOV.UK pattern of xl, l, m and s
hidden
Labels can be visually hidden when their presence would complicate the form. This is a common pattern when asking for multiple lines of address where a single label or legend will suffice. The hidden value defaults to false and can be overridden with true

A fully-configured label

Input

= f.govuk_text_field :favourite_shade_of_red,
  label: { text: 'What is your favourite shade of red?', tag: 'h3', size: 'm' }

Rendered output

HTML output

<div class="govuk-form-group">
  <h3 class="govuk-label-wrapper">
    <label for="person-favourite-shade-of-red-field" class="govuk-label govuk-label--m">
      What is your favourite shade of red?
    </label>
  </h3>
  <input id="person-favourite-shade-of-red-field" class="govuk-input" type="text" name="person[favourite_shade_of_red]" />
</div>

Hints

Unlike labels, hints cannot be styled and their surrounding tags cannot be customised. They are set by providing a hint_text string parameter.

To accomodate screenreaders and users of other assistive technology, hints must be associated with inputs via the aria-describedby attribute. The form builder does this automatically.

A text field with hint

Input

= f.govuk_text_field :favourite_shade_of_blue,
  label: { text: 'What is your favourite shade of blue?' },
  hint_text: 'The shade you reach for first when painting the sky'

Rendered output

The shade you reach for first when painting the sky

HTML output

<div class="govuk-form-group">
  <label for="person-favourite-shade-of-blue-field" class="govuk-label">
    What is your favourite shade of blue?
  </label>
  <span class="govuk-hint" id="person-favourite-shade-of-blue-hint">
    The shade you reach for first when painting the sky
  </span>
  <input id="person-favourite-shade-of-blue-field" class="govuk-input" aria-describedby="person-favourite-shade-of-blue-hint" type="text" name="person[favourite_shade_of_blue]" />
</div>

Legends

Legends look, act and work in a similar fashion to labels but they describe a group of inputs.

The GOV.UK Design System uses legends to describe radio button, check box and date fields but any group of related fields can be wrapped in a fieldset.

Legends are customised by passing in a hash of options with the following keys:

text
The actual text that forms the legend
tag
The HTML tag that the legend will be wrapped in. This is useful on pages where the label is also the main header. In cases like this, it should be set to h1
size
The legend size which follows the usual GOV.UK pattern of xl, l, m and s

Radio buttons with a fully-customised legend

Input

= f.govuk_collection_radio_buttons :new_department_id,
  primary_colours,
  :id,
  :name,
  legend: { text: "What's your favourite primary colour?", size: 'l', tag: 'h4' }

Rendered output

What's your favourite primary colour?