Skip to main content
  1. X-GOVUK projects
  2. GOV.UK Form Builder
  3. Labels, captions, hints and legends

Labels, captions, 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
<%= f.govuk_text_field :favourite_colour %>

Output

<div class="govuk-form-group">
  <label for="person-favourite-colour-field" class="govuk-label">
    Favourite_colour
  </label>
  <input id="person-favourite-colour-field" class="govuk-input" type="text" name="person[favourite_colour]" />
</div>

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' }
<%= f.govuk_text_field :favourite_shade_of_red, label: { text: 'What is your favourite shade of red?', tag: 'h3', size: 'm' } %>

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>

Setting label content with a proc

Label content can be customised further using a Ruby proc. Note that the content of the proc is rendered inside the label so the form builder can enforce consistency between the label’s for attribute and the associated form element.

Input

= f.govuk_text_field :favourite_shade_of_orange,
  label: -> do
    h2.orange-background.govuk-header-m
      | What's your favourite shade of orange?
<%= f.govuk_text_field :favourite_shade_of_orange, label: -> do %>
  <h2 class="orange-background govuk-header-m">
    What's your favourite shade of orange?
  </h2>
<% end %>

Output

<div class="govuk-form-group">
  <label for="person-favourite-shade-of-orange-field" class="govuk-label">
    <h2 class="orange-background govuk-header-m">
      What's your favourite shade of orange?
    </h2>
  </label>
  <input id="person-favourite-shade-of-orange-field" class="govuk-input" type="text" name="person[favourite_shade_of_orange]" />
</div>

Captions

Sometimes you may need to make it clear that a heading is part of a larger section or group. To do this, you can use a heading with a caption.

Captions are supported by all helpers that have labels or legends and can be configured with the following options:

text
The caption text
size
The caption size, either xl, l or m

If you want to place the caption outside of the label’s tag you can do this by setting the label content with a proc.

A label with a caption

Input

= f.govuk_text_field :favourite_shade_of_grey,
  label: { text: 'Favourite shade of grey', tag: 'h2', size: 'l' },
  caption: { text: 'Aesthetic preferences', size: 'm' }
<%= f.govuk_text_field :favourite_shade_of_grey, label: { text: 'Favourite shade of grey', tag: 'h2', size: 'l' }, caption: { text: 'Aesthetic preferences', size: 'm' } %>

Output

<div class="govuk-form-group">
  <h2 class="govuk-label-wrapper">
    <label for="person-favourite-shade-of-grey-field" class="govuk-label govuk-label--l">
      <span class="govuk-caption-m">
        Aesthetic preferences
      </span>
      Favourite shade of grey
    </label>
  </h2>
  <input id="person-favourite-shade-of-grey-field" class="govuk-input" type="text" name="person[favourite_shade_of_grey]" />
</div>

Hints

Hints are used to provide extra information that’s relevant to the majority of users, like how their information will be used, or where to find it.

Hints contents be customised further by passing in a proc instead of a string.

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' }
<%= 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' } %>

Output

The shade you reach for first when painting the sky
<div class="govuk-form-group">
  <label for="person-favourite-shade-of-blue-field" class="govuk-label">
    What is your favourite shade of blue?
  </label>
  <div class="govuk-hint" id="person-favourite-shade-of-blue-hint">
    The shade you reach for first when painting the sky
  </div>
  <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>

Setting hint content with a proc

Input

= f.govuk_text_field :favourite_shade_of_purple,
  label: { text: 'What is your favourite shade of purple?' },
  hint: -> do
    p
      ' If in doubt, choose
      span.purple-background Indigo
<%= f.govuk_text_field :favourite_shade_of_purple, label: { text: 'What is your favourite shade of purple?' }, hint: -> do %>
  <p>
    If in doubt, choose 
    <span class="purple-background">Indigo</span>
  </p>
<% end %>

Output

If in doubt, choose Indigo

<div class="govuk-form-group">
  <label for="person-favourite-shade-of-purple-field" class="govuk-label">
    What is your favourite shade of purple?
  </label>
  <div class="govuk-hint" id="person-favourite-shade-of-purple-hint">
    <p>
      If in doubt, choose <span class="purple-background">
        Indigo
      </span>
    </p>
  </div>
  <input id="person-favourite-shade-of-purple-field" class="govuk-input" aria-describedby="person-favourite-shade-of-purple-hint" type="text" name="person[favourite_shade_of_purple]" />
</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
hidden
Legends can be visually hidden when their presence would complicate the form. The hidden value defaults to false and can be overridden with true

Radio buttons with a fully-customised legend

Input

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

Output

What’s your favourite primary colour?

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h4 class="govuk-fieldset__heading">
        What's your favourite primary colour?
      </h4>
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[favourite_colour]" id="person_favourite_colour" />
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-favourite-colour-cyan-field" class="govuk-radios__input" type="radio" value="cyan" name="person[favourite_colour]" />
        <label for="person-favourite-colour-cyan-field" class="govuk-label govuk-radios__label">
          Cyan
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-favourite-colour-magenta-field" class="govuk-radios__input" type="radio" value="magenta" name="person[favourite_colour]" />
        <label for="person-favourite-colour-magenta-field" class="govuk-label govuk-radios__label">
          Magenta
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-favourite-colour-yellow-field" class="govuk-radios__input" type="radio" value="yellow" name="person[favourite_colour]" />
        <label for="person-favourite-colour-yellow-field" class="govuk-label govuk-radios__label">
          Yellow
        </label>
      </div>
    </div>
  </fieldset>
</div>

Fully customising legends with procs

To take even more control of legends the content can be passed in using a Ruby proc. In this example we’re using Slim but could just as easily call a helper method or render a partial, component or string of HTML.

Procs allow for complete control of the legend’s HTML, including the legend element itself. This means that the legend element needs to be added manually and it should wrap all of the fieldset’s heading text.

Input

= f.govuk_collection_radio_buttons :least_favourite_colour,
  primary_colours,
  :id,
  :name,
  legend: -> do
    legend.govuk-fieldset__legend.govuk-fieldset__legend--l
      h3.govuk-fieldset__heading
        ' Which

        span.gradient-background colour

        ' do you hate most?
<%= f.govuk_collection_radio_buttons :least_favourite_colour, primary_colours, :id, :name, legend: -> do %><legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
    <h3 class="govuk-fieldset__heading">
      Which
      <span class="gradient-background">colour
      </span>
      do you hate most? 
    </h3>
  </legend><% end %>

Output

Which colour do you hate most?

<div class="govuk-form-group">
  <fieldset class="govuk-fieldset">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
      <h3 class="govuk-fieldset__heading">
        Which <span class="gradient-background">
          colour
        </span>
        do you hate most? 
      </h3>
    </legend>
    <input value="" autocomplete="off" type="hidden" name="person[least_favourite_colour]" id="person_least_favourite_colour" />
    <div class="govuk-radios" data-module="govuk-radios">
      <div class="govuk-radios__item">
        <input id="person-least-favourite-colour-cyan-field" class="govuk-radios__input" type="radio" value="cyan" name="person[least_favourite_colour]" />
        <label for="person-least-favourite-colour-cyan-field" class="govuk-label govuk-radios__label">
          Cyan
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-least-favourite-colour-magenta-field" class="govuk-radios__input" type="radio" value="magenta" name="person[least_favourite_colour]" />
        <label for="person-least-favourite-colour-magenta-field" class="govuk-label govuk-radios__label">
          Magenta
        </label>
      </div>
      <div class="govuk-radios__item">
        <input id="person-least-favourite-colour-yellow-field" class="govuk-radios__input" type="radio" value="yellow" name="person[least_favourite_colour]" />
        <label for="person-least-favourite-colour-yellow-field" class="govuk-label govuk-radios__label">
          Yellow
        </label>
      </div>
    </div>
  </fieldset>
</div>