Component

Form label

Use labels for all form fields.

For use with other form inputs e.g. Radio buttons

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/label", {
  text: "National Insurance number",
  html_for: "id-that-matches-input"
} %>

GOV.UK Design System

This component incorporates components from the GOV.UK Design System:

Accessibility acceptance criteria

All text must have a contrast ratio higher than 4.5:1 against the background colour to meet WCAG AA

Labels must:

  • have visible text

Hint text must:

  • be associated with an input. The hint_id must match the aria-describedby property on the input your label is associated with.

If hint text is within a label it will be announced in its entirety by screen readers. By putting the hint alongside labels and associating hints with inputs using aria-describedby, then screen readers will read the label, describe the type of input (eg radio) and then read additional text. It means users of screen readers can scan and skip options as easy as people making choices with sight. A discussion of this approach.

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

With hint (preview)

It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’. 
<%= render "govuk_publishing_components/components/label", {
  text: "National Insurance number",
  html_for: "id-that-matches-input-1",
  hint_id: "should-match-aria-describedby-input",
  hint_text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
} %>

With custom label size (preview)

Make the label different sizes. Valid options are ‘s’, ‘m’, ‘l’ and ‘xl’.

<%= render "govuk_publishing_components/components/label", {
  text: "Surname",
  html_for: "id-that-matches-input-2",
  heading_size: "xl"
} %>

Bold with hint (preview)

It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’. 
<%= render "govuk_publishing_components/components/label", {
  bold: true,
  text: "National Insurance number",
  html_for: "id-that-matches-input-3",
  hint_id: "should-match-aria-describedby-input-bold",
  hint_text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
} %>

As page heading (preview) 

<%= render "govuk_publishing_components/components/label", {
  is_page_heading: true,
  heading_size: "xl",
  text: "National Insurance number",
  html_for: "id-that-matches-input-4",
  hint_id: "should-match-aria-describedby-input-bold"
} %>

Inside a radio component (preview)

When the label is used inside the radio component additional classes are required on the radio, which are added by this option. This is already handled by the radio component and is a specific use case, but is worth documenting.

Note that this example will not render correctly - do not be alarmed. It only works properly when inside the radio component.

It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’. 
<%= render "govuk_publishing_components/components/label", {
  text: "National Insurance number",
  html_for: "id-radio",
  is_radio_label: true,
  hint_id: "id-radio",
  hint_text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
} %>

With (preview) 

<%= render "govuk_publishing_components/components/label", {
  text: "Label with an ID",
  id: "id-for-the-label",
  html_for: "id-that-matches-input-6"
} %>

With dir attribute (preview)

To allow the correct display of right to left languages.

When the right_to_left parameter is set to true any hint text displays in the same text direction as the label.

Hint text displayed right to left 
<%= render "govuk_publishing_components/components/label", {
  text: "العربيَّة",
  html_for: "id-that-matches-input-7",
  hint_id: "should-match-aria-describedby-input",
  hint_text: "Hint text displayed right to left",
  right_to_left: true
} %>