Combobox
Introduction
An autocomplete input control that combines a text box with a dropdown listbox, allowing users to filter and select options from a list. Primarily used for long option feeds, platform filters, tags, and category selection.
Usage
These examples illustrate how content editors bind and structure interactive combobox components.
1. Standard Technology Filter (Interactive Select)
A standard searchable combobox preloaded with choices, allowing users to filter or directly select their target options.
{
"type": "combobox",
"label": "Preferred Tech Stack",
"placeholder": "Select a Framework",
"items": [
{ "label": "React", "value": "react" },
{ "label": "Solid", "value": "solid" },
{ "label": "Svelte", "value": "svelte" },
{ "label": "Vue", "value": "vue" },
{ "label": "Hono", "value": "hono" }
],
"interactive": true
}
2. Clearable Option Search (Custom Items)
Features a companion clear action, enabling users to purge selected choices with a single click. Ideal for platform searches, locations, or country selection lists.
{
"type": "combobox",
"label": "Country Selection",
"placeholder": "Search countries...",
"items": [
{ "label": "United States", "value": "us" },
{ "label": "Germany", "value": "de" },
{ "label": "France", "value": "fr" },
{ "label": "United Kingdom", "value": "uk" },
{ "label": "Canada", "value": "ca" }
],
"allowClear": true,
"interactive": true
}
3. Disabled Input Field
Demonstrates a temporarily locked autocomplete field. This preserves current labels and selections but prevents input typing, filtering, or dropdown activation.
{
"type": "combobox",
"label": "Select Database Engine",
"placeholder": "Temporarily unavailable",
"items": [],
"disabled": true,
"interactive": true
}
Props
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Label Text (label) | string | - | Companion visual text positioned above the autocomplete search box. |
Required (required) | boolean | false | Renders a required indicator next to the label and marks the component as required. |
Helper Text (helperText) | string | - | Helpful text or hints rendered below the combobox dropdown. |
Error Text (errorText) | string | - | Error message rendered below the combobox dropdown when the field is invalid. |
Placeholder (placeholder) | string | - | Shown inside the input box when no item is selected. |
Clear Button (allowClear) | boolean | false | When true, renders an end-aligned clear button inside the text input to easily reset selection. |
Disabled (disabled) | boolean | false | Freezes user search inputs, dropdown popups, and click activations. |
Items List (items) | list | [] | An ordered array of object entries representing list selections (see list sub-properties below). |
List Item Properties (items)
| Sub-Property | Type | Required | Description |
|---|---|---|---|
Label (label) | string | Yes | Display name rendered in the list popup options. |
Value (value) | string | Yes | Unique string identifier captured behind-the-scenes on option selection. |
Disabled Option (disabled) | boolean | No | Dim/lock a single selection choice within the dropdown feed. |
Developer Notes & Accessibility
- Smart Adaptive Hydration (Tier 2): To optimize initial page speeds, the Combobox compiles to static, zero-JS HTML/CSS markups on server loads, downloading interactive JS payloads only when custom signals are provided or when
"interactive": trueis explicitly passed. - Accessible Listboxes: The component operates in complete alignment with WAI-ARIA combobox accessibility roles. Focus jumps, arrow key options selections, and keyboard activations occur natively out-of-the-box.
- Unified Form Submissions: Selection values map directly to standard form POST requests, preventing the need for developers to programmatically link selection states to global custom submission logic.