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

= f.govuk_text_field :favourite_colour

<%= f.govuk_text_field :favourite_colour %>

Output

Rendered
HTML

Favourite_colour

<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

Slim
ERB

= 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

Rendered
HTML

What is your favourite shade of red?

<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

Slim
ERB

= 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

Rendered
HTML

What’s your favourite shade of orange?

<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>

Separate labels

There are occasions where placing the label above an input won’t work. We can do this by suppressing the default label with label: nil and manually adding the label elsewhere by calling the govuk_label helper directly.

Input

Slim
ERB

.two-columns
  = f.govuk_label :crayons_or_felt_tips, text: "Do you prefer crayons or felt tip pens?"
  = f.govuk_text_field :crayons_or_felt_tips, label: nil

<div class="two-columns">
  <%= f.govuk_label :crayons_or_felt_tips, text: "Do you prefer crayons or felt tip pens?" %>
  <%= f.govuk_text_field :crayons_or_felt_tips, label: nil %>
</div>

Output

Rendered
HTML

Do you prefer crayons or felt tip pens?

<div class="two-columns">
  <label for="person-crayons-or-felt-tips-field" class="govuk-label">
    Do you prefer crayons or felt tip pens?
  </label>
  <div class="govuk-form-group">
    <input id="person-crayons-or-felt-tips-field" class="govuk-input" type="text" name="person[crayons_or_felt_tips]" />
  </div>
</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

Slim
ERB

= 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

Rendered
HTML

Aesthetic preferences Favourite shade of grey

<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

Slim
ERB

= 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

Rendered
HTML

What is your favourite shade of blue?

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

Slim
ERB

= 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

Rendered
HTML

What is your favourite shade of purple?

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

Slim
ERB

= 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

Rendered
HTML

What’s your favourite primary colour?

Cyan

Magenta

Yellow

<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

Slim
ERB

= 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

Rendered
HTML

Which colour do you hate most?

Cyan

Magenta

Yellow

<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>