name: Select
description: A dropdown select
govuk_frontend_components:
  - select
accessibility_criteria: |
  - accept focus
  - be focusable with a keyboard
  - be usable with a keyboard
  - indicate when it has focus
examples:
  default:
    data:
      id: 'dropdown1'
      label: 'My Dropdown'
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'
      - text: 'Option three'
        value: 'option3'
  with_different_id_and_name:
    description: If no name is provided, name defaults to the (required) value of id.
    data:
      id: 'dropdown1-1'
      label: 'My Dropdown'
      name: 'dropdown[1]'
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'
  with_preselect:
    data:
      id: 'dropdown2'
      label: 'Option 2 preselected'
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'
        selected: true
      - text: 'Option three'
        value: 'option3'
  with_tracking:
    description: 'Tracking can be enabled on the select component by passing a minimum of data_track_category and data_track_action. Other tracking attributes are optional. Note: tracking events do not currently fire within the component guide.'
    data:
      id: 'dropdown3'
      label: 'With tracking enabled'
      options:
      - text: 'Option one'
        value: 'option1'
        data_attributes:
          track_category: 'relatedLinkClicked'
          track_action: 1.1
          track_label: '/link-1'
          track_options:
            dimension28: 1
            dimension29: 'Link 1'
      - text: 'Option two'
        value: 'option2'
        data_attributes:
          track_category: 'relatedLinkClicked'
          track_action: 1.2
          track_label: '/link-2'
          track_options:
            dimension28: 2
            dimension29: 'Link 2'
      - text: 'Option three'
        value: 'option3'
        data_attributes:
          track_category: 'relatedLinkClicked'
          track_action: 1.3
          track_label: '/link-3'
          track_options:
            dimension28: 3
            dimension29: 'Link 3'
  with_data_attributes:
    description: Other data attributes can be passed to the component if needed.
    data:
      id: 'dropdown4'
      label: 'With data attributes'
      options:
      - text: 'Option one'
        value: 'option1'
        data_attributes:
          another_attribute: "attribute 1"
          something_else: "attribute 2"
      - text: 'Option two'
        value: 'option2'
      - text: 'Option three'
        value: 'option3'
  with_error:
    description: If the user has to select an option, it is recommended that a radio button is used instead of a select, but this is not always possible. Note that error_id is optional, if it is not passed one will be generated automatically.
    data:
      id: 'dropdown4-1'
      label: 'How will you be travelling to the conference?'
      error_message: 'Please choose an option'
      error_id: 'error_id'
      options:
      - text: ""
        value: ""
      - text: 'Public transport'
        value: 'option1'
      - text: 'Will make own arrangements'
        value: 'option2'
  with_error_id_but_no_message:
    description: For some selects the error message should be rendered separately but an error state is still required (currently required in smart answers). In this scenario an error_id can be passed without an error_message to highlight the component and set aria-describedby correctly.
    data:
      id: 'dropdown4-2'
      label: 'What lunch option would you like?'
      error_id: 'error_id'
      options:
      - text: ""
        value: ""
      - text: 'Vegetarian'
        value: 'option1'
      - text: 'Meat'
        value: 'option2'
  full_width:
    description: Make the select width 100%. This is used for facets in finder-frontend's search.
    data:
      id: 'dropdown5'
      label: 'Really wide'
      full_width: true
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'
      - text: 'Option three'
        value: 'option3'
  with_custom_label_size:
    description: Make the label different sizes. Valid options are 's', 'm', 'l' and 'xl'.
    data:
      id: 'dropdown6'
      label: 'Bigger!'
      heading_size: 'xl'
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'
      - text: 'Option three'
        value: 'option3'
  with_page_heading:
    description: This adds a H1 element with a label element inside containing the text supplied.
    data:
      id: 'select-with-heading'
      label: 'This is a page heading'
      heading_size: 'xl'
      is_page_heading: true
      options:
      - text: 'Option one'
        value: 'option1'
      - text: 'Option two'
        value: 'option2'