Combo Box

An enhanced select input that allows users to filter a list by typing. Follows USWDS combo box patterns.

Props

Prop	Default	Description
`id`		Unique ID for the combo box element
`name`		Form field name submitted with the form
`options`		List of option dicts with `value` and `label` keys
`default_value`		Value of the option that should be selected on initial render
`disabled`		Set to `"true"` to disable the combo box
`assistive_hint`		Screen reader hint text describing the filtering behavior
`class`		Additional CSS classes to apply to the combo box wrapper

Example Usage

Basic Combo Box

<c-combo-box
    id="fruit-select"
    name="fruit"
    :options="[
        {'value': 'apple', 'label': 'Apple'},
        {'value': 'banana', 'label': 'Banana'},
        {'value': 'cherry', 'label': 'Cherry'},
    ]"
/>

Combo Box with Default Value

<c-combo-box
    id="fruit-default"
    name="fruit"
    default_value="banana"
    :options="[
        {'value': 'apple', 'label': 'Apple'},
        {'value': 'banana', 'label': 'Banana'},
        {'value': 'cherry', 'label': 'Cherry'},
    ]"
/>

Disabled Combo Box

<c-combo-box
    id="fruit-disabled"
    name="fruit"
    disabled="true"
    :options="[
        {'value': 'apple', 'label': 'Apple'},
        {'value': 'banana', 'label': 'Banana'},
        {'value': 'cherry', 'label': 'Cherry'},
    ]"
/>

Usage Notes

Options are passed as a list of dicts, each with value and label keys
Use default_value to pre-select an option matching one of the option value fields
USWDS JavaScript is required to activate the combo box filtering behavior
For simple dropdowns without filtering, use the c-select component instead

{% load cotton %}
{% load cotton_aliases %}

<div class="component-variants">
    <h1>Combo Box Component</h1>
    
    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.name }}</h2>
        
        {% cotton combo_box :options="{{ variant.options|safe }}" id="{{ variant.id }}" name="{{ variant.name_attr }}" default_value="{{ variant.default_value }}" disabled="{{ variant.disabled }}" assistive_hint="{{ variant.assistive_hint }}" class="{{ variant.class }}" %}
        {% endcotton %}
    </div>
    {% endfor %}
</div>

name: Combo Box
context:
  variants:
    - name: Basic Combo Box
      id: "fruit-select"
      name_attr: "fruit"
      options:
        - value: "apple"
          label: "Apple"
        - value: "banana"
          label: "Banana"
        - value: "cherry"
          label: "Cherry"
      default_value: ""
      disabled: "false"
      assistive_hint: "Start typing to filter fruits"
      class: ""
    - name: Combo Box with Default Value
      id: "fruit-default"
      name_attr: "fruit_default"
      options:
        - value: "apple"
          label: "Apple"
        - value: "banana"
          label: "Banana"
        - value: "cherry"
          label: "Cherry"
      default_value: "banana"
      disabled: "false"
      assistive_hint: "Start typing to filter fruits"
      class: ""
    - name: Disabled Combo Box
      id: "fruit-disabled"
      name_attr: "fruit_disabled"
      options:
        - value: "apple"
          label: "Apple"
        - value: "banana"
          label: "Banana"
        - value: "cherry"
          label: "Cherry"
      default_value: ""
      disabled: "true"
      assistive_hint: "Start typing to filter fruits"
      class: ""