Component

Select with search

A dropdown select with search

NOTE: this component currently fails WCAG compliance for keyboard navigation, as the total number of options are not announced when using Voice Over

Use this component to create a JavaScript-enhanced dropdown select.

It’s powered by Choices.js, which is similar to Select2 but without the jQuery dependency. And it’s styled to look like Accessible Autocomplete, or any other GOV.UK Design System component.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "components/select_with_search", {
  id: "dropdown-default",
  label: "My Dropdown",
  options: [
    {
      text: "Option one",
      value: "option1"
    },
    {
      text: "Option two",
      value: "option2"
    },
    {
      text: "Option three",
      value: "option3"
    }
  ]
} %>

Accessibility acceptance criteria

• accept focus
• be focusable with a keyboard
• be usable with a keyboard
• indicate when it has focus

Other examples

With blank option (preview)

Include a blank option

<%= render "components/select_with_search", {
  id: "dropdown-with-blank",
  label: "With blank option",
  include_blank: true,
  options: [
    {
      text: "Option one",
      value: "option1"
    },
    {
      text: "Option two",
      value: "option2"
    },
    {
      text: "Option three",
      value: "option3"
    }
  ]
} %>

With grouped options (preview)

Options can be grouped

<%= render "components/select_with_search", {
  id: "dropdown-with-grouped-options",
  label: "Select a city",
  grouped_options: [
    [
      "England",
      [
        {
          text: "Bath",
          value: "bath"
        },
        {
          text: "Bristol",
          value: "bristol"
        },
        {
          text: "London",
          value: "london"
        },
        {
          text: "Manchester",
          value: "manchester"
        }
      ]
    ],
    [
      "Northern Ireland",
      [
        {
          text: "Bangor",
          value: "bangor"
        },
        {
          text: "Belfast",
          value: "belfast"
        }
      ]
    ],
    [
      "Scotland",
      [
        {
          text: "Dundee",
          value: "dundee"
        },
        {
          text: "Edinburgh",
          value: "edinburgh"
        },
        {
          text: "Glasgow",
          value: "glasgow"
        }
      ]
    ],
    [
      "Wales",
      [
        {
          text: "Cardiff",
          value: "cardiff"
        },
        {
          text: "Swansea",
          value: "swansea"
        }
      ]
    ]
  ]
} %>

With grouped options and blank option (preview)

Options can be grouped and include a blank option

<%= render "components/select_with_search", {
  id: "dropdown-with-grouped-options-and-blank",
  label: "Select a city",
  include_blank: true,
  grouped_options: [
    [
      "England",
      [
        {
          text: "Bath",
          value: "bath"
        },
        {
          text: "Bristol",
          value: "bristol"
        },
        {
          text: "London",
          value: "london"
        },
        {
          text: "Manchester",
          value: "manchester"
        }
      ]
    ],
    [
      "Northern Ireland",
      [
        {
          text: "Bangor",
          value: "bangor"
        },
        {
          text: "Belfast",
          value: "belfast"
        }
      ]
    ],
    [
      "Scotland",
      [
        {
          text: "Dundee",
          value: "dundee"
        },
        {
          text: "Edinburgh",
          value: "edinburgh"
        },
        {
          text: "Glasgow",
          value: "glasgow"
        }
      ]
    ],
    [
      "Wales",
      [
        {
          text: "Cardiff",
          value: "cardiff"
        },
        {
          text: "Swansea",
          value: "swansea"
        }
      ]
    ]
  ]
} %>

With different id and name (preview)

If no name is provided, name defaults to the (required) value of id.

<%= render "components/select_with_search", {
  id: "dropdown-with-different-id-and-name",
  label: "My Dropdown",
  name: "dropdown[1]",
  options: [
    {
      text: "Option one",
      value: "option1"
    },
    {
      text: "Option two",
      value: "option2"
    }
  ]
} %>

With data attributes (preview)

<%= render "components/select_with_search", {
  id: "dropdown-with-data-attributes",
  data_attributes: {
    module: "not-a-module",
    loose: "moose"
  },
  label: "Select your country",
  options: [
    {
      text: "France",
      value: "fr"
    },
    {
      text: "Germany",
      value: "de"
    },
    {
      text: "United Kingdom",
      value: "uk"
    }
  ]
} %>

With preselect (preview)

<%= render "components/select_with_search", {
  id: "dropdown-with-preselect",
  label: "Option 2 preselected",
  options: [
    {
      text: "Option one",
      value: "option1"
    },
    {
      text: "Option two",
      value: "option2",
      selected: true
    },
    {
      text: "Option three",
      value: "option3"
    }
  ]
} %>

With hint (preview)

When a hint is included the aria-describedby attribute of the select is included to point to the hint. When an error and a hint are present, that attribute includes the IDs of both the hint and the error.

You might need some more information here

<%= render "components/select_with_search", {
  id: "dropdown-with-hint",
  label: "Choose your preferred thing",
  hint: "You might need some more information here",
  hint_id: "optional-hint-id",
  options: [
    {
      text: "Something",
      value: "option1"
    },
    {
      text: "Something else",
      value: "option2"
    }
  ]
} %>

With error (preview)

An arbitrary number of separate error items can be passed to the component.

Please choose an option

<%= render "components/select_with_search", {
  id: "dropdown-with-error",
  label: "How will you be travelling to the conference?",
  error_items: [
    {
      text: "Please choose an option"
    }
  ],
  include_blank: true,
  options: [
    {
      text: "Public transport",
      value: "option1"
    },
    {
      text: "Will make own arrangements",
      value: "option2"
    }
  ]
} %>

With custom label size (preview)

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

<%= render "components/select_with_search", {
  id: "dropdown-with-custom-label-size",
  label: "Bigger!",
  heading_size: "xl",
  options: [
    {
      text: "Option one",
      value: "option1"
    },
    {
      text: "Option two",
      value: "option2"
    },
    {
      text: "Option three",
      value: "option3"
    }
  ]
} %>

With multiple select enabled (preview)

Allow multiple items to be selected and de-selected.

<%= render "components/select_with_search", {
  id: "dropdown-with-multiple",
  label: "Select your country",
  include_blank: true,
  select: {
    multiple: true
  },
  options: [
    {
      text: "France",
      value: "fr",
      selected: false
    },
    {
      text: "Germany",
      value: "de",
      selected: false
    },
    {
      text: "The United Kingdom of Great Britain and Northern Ireland",
      value: "uk"
    },
    {
      text: "Democratic Republic of the Congo",
      value: "cg"
    }
  ]
} %>