Component

Option select

A scrollable list of checkboxes to be displayed on a form where one might otherwise use a multi-select

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

Market sector

Market sector

How to call this component

<%= render "govuk_publishing_components/components/option_select", {
  key: "market_sector",
  title: "Market sector",
  options_container_id: "list_of_sectors",
  options: [
    {
      value: "aerospace",
      label: "Aerospace",
      id: "aerospace"
    },
    {
      value: "agriculture-environment-and-natural-resources",
      label: "Agriculture, environment and natural resources",
      id: "agriculture-environment-and-natural-resources"
    },
    {
      value: "building-and-construction",
      label: "Building and construction",
      id: "building-and-construction"
    },
    {
      value: "chemicals",
      label: "Chemicals",
      id: "chemicals"
    },
    {
      value: "clothing-footwear-and-fashion",
      label: "Clothing, footwear and fashion",
      id: "clothing-footwear-and-fashion"
    },
    {
      value: "defence",
      label: "Defence",
      id: "defence"
    },
    {
      value: "distribution-and-service-industries",
      label: "Distribution and Service Industries",
      id: "distribution-and-service-industries"
    },
    {
      value: "electronics-industry",
      label: "Electronics Industry",
      id: "electronics-industry"
    },
    {
      value: "energy",
      label: "Energy",
      id: "energy"
    },
    {
      value: "engineering",
      label: "Engineering",
      id: "engineering"
    },
    {
      value: "financial-services",
      label: "Financial services",
      id: "financial-services"
    },
    {
      value: "fire-police-and-security",
      label: "Fire, police, and security",
      id: "fire-police-and-security"
    },
    {
      value: "food-manufacturing",
      label: "Food manufacturing",
      id: "food-manufacturing"
    },
    {
      value: "giftware-jewellery-and-tableware",
      label: "Giftware, jewellery and tableware",
      id: "giftware-jewellery-and-tableware"
    }
  ]
} %>

Accessibility acceptance criteria

The option select must:

  • indicate that the option select is expandable/collapsible
  • indicate the initial state of expandable content
  • indicate where the state of expandable content has changed

The option select inputs must:

  • have a margin to the right when the box is scrollable so that users can interact with a scrollbar without accidentally clicking an option
  • only include an aria-controls attribute if an element with the ID specified exists on the page
  • be grouped with a label

The option select filter must:

  • be focusable with a keyboard
  • indicate when it has keyboard focus
  • inform the user that is it an editable field
  • inform the user when there are matches, or if there are no matches
  • inform the user as the number of matches changes

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-
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)

With option pre checked (preview)

List of options

List of options
<%= render "govuk_publishing_components/components/option_select", {
  key: "with_checked_value_set",
  title: "List of options",
  options_container_id: "list_of_vegetables",
  options: [
    {
      value: "potatoes",
      label: "Potatoes",
      checked: true
    },
    {
      value: "carrots",
      label: "Carrots",
      id: "carrots"
    },
    {
      value: "mash",
      label: "Mash",
      id: "mash"
    }
  ]
} %>

With aria controls (preview)

aria_controls_id adds an aria-controls attribute to each checkbox input. This makes it easier for users of assitive tech to jump from them to the part of the page they’re updating.

The aria_controls_id must be set to the ID of an element that’s on the page or it won’t be included.

List of options (with aria controls)

List of options (with aria controls)
<%= render "govuk_publishing_components/components/option_select", {
  key: "with_aria-control_set",
  title: "List of options (with aria controls)",
  aria_controls_id: "wrapper",
  options_container_id: "list_of_countries",
  options: [
    {
      value: "britain",
      label: "Britain",
      id: "britain"
    },
    {
      value: "france",
      label: "France",
      id: "france"
    },
    {
      value: "spain",
      label: "Spain",
      id: "spain"
    }
  ]
} %>

Closed on load (preview)

List of hats

List of hats
<%= render "govuk_publishing_components/components/option_select", {
  key: "closed_on_load",
  title: "List of hats",
  closed_on_load: true,
  options_container_id: "list_of_hats",
  options: [
    {
      value: "bobble_hat",
      label: "Bobble hat",
      id: "bobble_hat"
    },
    {
      value: "fez",
      label: "Fez",
      id: "fez"
    },
    {
      value: "sombrero",
      label: "Sombrero",
      id: "sombrero"
    }
  ]
} %>

With data attributes on checkboxes (preview)

List of shoes

List of shoes
<%= render "govuk_publishing_components/components/option_select", {
  key: "list_of_shoes",
  title: "List of shoes",
  options_container_id: "list_of_shoes",
  options: [
    {
      value: "trainers",
      label: "Trainers",
      id: "trainers",
      data_attributes: {
        an_attribute: "some_value1"
      }
    },
    {
      value: "plimsolls",
      label: "Plimsolls",
      id: "plimsolls",
      data_attributes: {
        an_attribute: "some_value2"
      }
    },
    {
      value: "high_heels",
      label: "High heels",
      id: "high_heels",
      data_attributes: {
        an_attribute: "some_value3"
      }
    }
  ]
} %>

With button data attributes (preview)

Allows data attributes to be passed to the component to be added to the expand/collapse button. The attributes are written to the parent element then read by the JavaScript and applied to the button. This is used for tracking purposes.

Market sector

Market sector
<%= render "govuk_publishing_components/components/option_select", {
  key: "market_sector",
  title: "Market sector",
  options_container_id: "list_of_sectors",
  button_data_attributes: {
    ga4_expandable: "",
    ga4_event: {
      event_name: "select_content",
      type: "finder"
    }
  },
  options: [
    {
      value: "aerospace",
      label: "Aerospace",
      id: "aerospace"
    },
    {
      value: "agriculture-environment-and-natural-resources",
      label: "Agriculture, environment and natural resources",
      id: "agriculture-environment-and-natural-resources"
    }
  ]
} %>

With filter (preview)

Adds a filter to allow users to narrow the checkboxes down. Checkboxes will only show if they match what the user has typed, or if they are already checked. The filter is case insensitive and strips out punctuation characters and duplicate whitespace, and sees ‘&’ and ‘and’ as the same, to make filtering easier.

Countries

Countries
<%= render "govuk_publishing_components/components/option_select", {
  key: "filter_demo",
  title: "Countries",
  options_container_id: "list_of_countries_to_filter",
  show_filter: true,
  options: [
    {
      value: "afghanistan",
      label: "Afghanistan",
      id: "afghanistan"
    },
    {
      value: "albania",
      label: "Albania",
      id: "albania"
    },
    {
      value: "algeria",
      label: "Algeria",
      id: "algeria",
      checked: true
    },
    {
      value: "american_samoa",
      label: "American Samoa",
      id: "american_samoa"
    },
    {
      value: "andorra",
      label: "Andorra",
      id: "andorra",
      checked: true
    },
    {
      value: "angola",
      label: "Angola",
      id: "angola"
    },
    {
      value: "anguilla",
      label: "Anguilla",
      id: "anguilla"
    },
    {
      value: "antigua_and_barbuda",
      label: "Antigua and Barbuda",
      id: "antigua_and_barbuda"
    },
    {
      value: "argentina",
      label: "Argentina",
      id: "argentina"
    },
    {
      value: "armenia",
      label: "Armenia",
      id: "armenia"
    },
    {
      value: "aruba",
      label: "Aruba",
      id: "aruba"
    },
    {
      value: "australia",
      label: "Australia",
      id: "australia"
    },
    {
      value: "austria",
      label: "Austria",
      id: "austria"
    },
    {
      value: "azerbaijan",
      label: "Azerbaijan",
      id: "azerbaijan"
    },
    {
      value: "bahamas",
      label: "Bahamas",
      id: "bahamas"
    },
    {
      value: "bahrain",
      label: "Bahrain",
      id: "bahrain"
    },
    {
      value: "bangladesh",
      label: "Bangladesh",
      id: "bangladesh"
    },
    {
      value: "barbados",
      label: "Barbados",
      id: "barbados"
    },
    {
      value: "belarus",
      label: "Belarus",
      id: "belarus"
    },
    {
      value: "belgium",
      label: "Belgium",
      id: "belgium"
    },
    {
      value: "belize",
      label: "Belize",
      id: "belize"
    },
    {
      value: "benin",
      label: "Benin",
      id: "benin"
    },
    {
      value: "bermuda",
      label: "Bermuda",
      id: "bermuda"
    },
    {
      value: "bhutan",
      label: "Bhutan",
      id: "bhutan"
    },
    {
      value: "bolivia",
      label: "Bolivia",
      id: "bolivia"
    },
    {
      value: "cote",
      label: "Cote d’Ivoire",
      id: "cote"
    },
    {
      value: "sthelena",
      label: "St Helena, Ascension and Tristan da Cunha",
      id: "sthelena"
    },
    {
      value: "trinidad",
      label: sanitize("Trinidad & Tobago"),
      id: "trinidad"
    }
  ]
} %>

Large (preview)

When large is set to true, the option-select container has an increased max-height of 600px, allowing more checkbox items to be visible.

Countries

Countries
<%= render "govuk_publishing_components/components/option_select", {
  key: "large_demo",
  title: "Countries",
  options_container_id: "list_of_countries_to_filter_large",
  large: true,
  options: [
    {
      value: "afghanistan",
      label: "Afghanistan",
      id: "afghanistanLargeExample"
    },
    {
      value: "albania",
      label: "Albania",
      id: "albaniaLargeExample"
    },
    {
      value: "algeria",
      label: "Algeria",
      id: "algeriaLargeExample"
    },
    {
      value: "american_samoa",
      label: "American Samoa",
      id: "american_samoaLargeExample"
    },
    {
      value: "andorra",
      label: "Andorra",
      id: "andorraLargeExample"
    },
    {
      value: "angola",
      label: "Angola",
      id: "angolaLargeExample"
    },
    {
      value: "anguilla",
      label: "Anguilla",
      id: "anguillaLargeExample"
    },
    {
      value: "antigua_and_barbuda",
      label: "Antigua and Barbuda",
      id: "antigua_and_barbudaLargeExample"
    },
    {
      value: "argentina",
      label: "Argentina",
      id: "argentinaLargeExample"
    },
    {
      value: "armenia",
      label: "Armenia",
      id: "armeniaLargeExample"
    },
    {
      value: "aruba",
      label: "Aruba",
      id: "arubaLargeExample"
    },
    {
      value: "australia",
      label: "Australia",
      id: "australiaLargeExample"
    },
    {
      value: "austria",
      label: "Austria",
      id: "austriaLargeExample"
    },
    {
      value: "azerbaijan",
      label: "Azerbaijan",
      id: "azerbaijanLargeExample"
    },
    {
      value: "bahamas",
      label: "Bahamas",
      id: "bahamasLargeExample"
    },
    {
      value: "bahrain",
      label: "Bahrain",
      id: "bahrainLargeExample"
    },
    {
      value: "bangladesh",
      label: "Bangladesh",
      id: "bangladeshLargeExample"
    },
    {
      value: "barbados",
      label: "Barbados",
      id: "barbadosLargeExample"
    },
    {
      value: "belarus",
      label: "Belarus",
      id: "belarusLargeExample"
    },
    {
      value: "belgium",
      label: "Belgium",
      id: "belgiumLargeExample"
    },
    {
      value: "belize",
      label: "Belize",
      id: "belizeLargeExample"
    },
    {
      value: "benin",
      label: "Benin",
      id: "beninLargeExample"
    },
    {
      value: "bermuda",
      label: "Bermuda",
      id: "bermudaLargeExample"
    },
    {
      value: "bhutan",
      label: "Bhutan",
      id: "bhutanLargeExample"
    },
    {
      value: "bolivia",
      label: "Bolivia",
      id: "boliviaLargeExample"
    },
    {
      value: "cote",
      label: "Cote d'Ivoire",
      id: "coteLargeExample"
    },
    {
      value: "sthelena",
      label: "St Helena, Ascension and Tristan da Cunha",
      id: "sthelenaLargeExample"
    },
    {
      value: "trinidad",
      label: sanitize("Trinidad & Tobago"),
      id: "trinidadLargeExample"
    }
  ]
} %>