Component

Form input

A form input field and an associated label.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "What is your name?"
  },
  name: "name"
} %>

GOV.UK Design System

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

Accessibility acceptance criteria

Inputs in the component must:

  • accept focus
  • be focusable with a keyboard
  • be usable with a keyboard
  • be usable with touch
  • indicate when they have focus
  • be recognisable as form input elements
  • have correctly associated labels
  • be of the appropriate type for their use, e.g. password inputs should be of type ‘password’

Labels use the label component.

Avoid using autofocus and tabindex unless you have user research to support this behaviour.

Other examples

Specific input type (preview)

By default the input will be type="text". This parameter accepts an alternative, e.g. search or email. spellcheck="false" is the default this can be changed by passing a true value. Consider adding autocomplete. No validation is done on this input.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "What is your email address?"
  },
  name: "address",
  type: "email"
} %>

With autocomplete (preview) 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Automatically complete the field with a user's email address (in supporting browsers)"
  },
  name: "name",
  type: "email",
  autocomplete: "email"
} %>

Numeric input (preview)

If input is set to type="number" we set the component up as described in the GOV.UK Design System guidance adding inputmode and pattern. These values can be overridden if necessary.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Account number"
  },
  name: "account-number",
  type: "number"
} %>

With an identifier (preview)

Give the input a specific ID.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Has an id"
  },
  name: "hasid",
  id: "hasid"
} %>

With aria attributes (preview)

The component accepts two possible aria attributes: aria-describedby and aria-controls.

aria-describedby is used to indicate the ID of the element that describes the input. This will be overridden in the event of an error, where the error will be used for the describedby attribute value. This example uses the ID of the main container for demonstration purposes as there aren’t any useful elements with IDs in the component guide. In real use this would be passed the ID of an element that correctly described the input.

aria-controls allows the addition of an aria-controls attribute, for use in places like the finders where the page is updated dynamically after value changes to the input.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "This is an example only and may not work with a screen reader"
  },
  name: "labelledby",
  describedby: "wrapper",
  controls: "wrapper"
} %>

With hint (preview)

Please provide your first and last name 
<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "What is your name?"
  },
  name: "name",
  hint: "Please provide your first and last name"
} %>

With error (preview)

Error: Please could you provide your name 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "What is your name?"
  },
  name: "name",
  error_message: "Please could you provide your name"
} %>

With error items (preview)

Error: Descriptive link to the question with an error 1
Descriptive link to the question with an error 2 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "What is your name?"
  },
  name: "name",
  error_items: [
    {
      text: "Descriptive link to the question with an error 1"
    },
    {
      text: "Descriptive link to the question with an error 2"
    }
  ]
} %>

With value (preview) 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Search for"
  },
  name: "name",
  value: "moose"
} %>

Autofocused (preview) 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Username"
  },
  name: "username",
  autofocus: true,
  tabindex: 0
} %>

Readonly (preview) 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Readonly attribute"
  },
  name: "readonly",
  value: "You can't change me",
  readonly: true
} %>

With maxlength (preview) 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "An input that doesn't allow many characters"
  },
  name: "name",
  value: "You can't type more",
  maxlength: 10
} %>

With custom width (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/input", {
  label: {
    text: "National insurance number"
  },
  hint: "It’s on your National insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’.",
  name: "name",
  width: 10
} %>

With search icon (preview)

Adds a search icon, spellcheck can also be added to indicate that the element should be, if possible, checked for spelling errors.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Search the internet"
  },
  name: "search-box",
  type: "search",
  search_icon: true,
  spellcheck: true
} %>

With label as heading (preview)

Wraps the label in a heading tag. Valid options are 1 to 6. To adjust the size of the label/heading, use the heading_size option. Valid options are s, m, l and xl.

Based on the heading/label pattern in the GOV.UK Design System.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "This is a heading 1 and a label"
  },
  name: "name",
  heading_level: 1,
  heading_size: "l"
} %>

With prefix (preview)

To help users understand how the input should look like. Often used for units of measurement.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Cost, in pounds"
  },
  name: "cost",
  width: 10,
  prefix: "£"
} %>

With suffix (preview)

To help users understand how the input should look like. Often used for units of measurement.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Lead times in days"
  },
  name: "lead-times",
  width: 10,
  suffix: "days"
} %>

With prefix and suffix (preview)

To help users understand how the input should look like. Often used for units of measurement.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Cost per item, in pounds"
  },
  name: "cost-per-item",
  width: 10,
  prefix: "£",
  suffix: "per item"
} %>

With suffix and error (preview)

To help users understand how the input should look like. Often used for units of measurement.

Error: Enter the approximate lead time in days, do not include words or symbols. 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Lead times in days"
  },
  error_message: "Enter the approximate lead time in days, do not include words or symbols.",
  name: "lead-times",
  width: 10,
  suffix: "days"
} %>

With enterhintkey attribute (preview)

To help users with virtual keyboards this changes the “enter” key to be a word that’s more descriptive of the action.

Must be one of enter, done, go, next, previous, search, or send. See the list of values and descriptions on MDN.

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Given name"
  },
  name: "given-name",
  enterkeyhint: "next"
} %>

With dir attribute (preview)

Allows the correct display of right to left languages.

By default the input element and the label both display text in a left to right direction.

When the right_to_left parameter of the input component is set to true both the input and the label, hint and error message display their content in a right to left direction.

Some hint text that displays in the same text direction as the label

Error: An error message that displays in the same text direction as the label 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Some input text to be displayed right to left with a label that displays in the same direction"
  },
  hint: "Some hint text that displays in the same text direction as the label",
  error_message: "An error message that displays in the same text direction as the label",
  name: "rtl-input-text",
  value: "العربيَّة",
  right_to_left: true
} %>

With separate dir attributes for field and help text (preview)

Allows the correct display of right to left languages.

By default the input element and the label both display text in a left to right direction.

If the input field and the help text (label, hint and error messages) are required to display in different directions the right_to_left_help attribute can be set as false to override the right_to_left attribute.

Some hint text that displays in the same text direction as the label

Error: An error message that displays in the same text direction as the label 

<%= render "govuk_publishing_components/components/input", {
  label: {
    text: "Some input text that displays right to left with a label that displays left to right"
  },
  hint: "Some hint text that displays in the same text direction as the label",
  name: "rtl-input-text",
  value: "العربيَّة",
  right_to_left: true,
  right_to_left_help: false,
  error_message: "An error message that displays in the same text direction as the label"
} %>