Select
Introduction
A custom dropdown selection control that allows users to pick one or more options from a predefined list. This component serves as a fully accessible, styleable, and responsive alternative to the browser's native <select> element.
The Select component is fully integrated as a select block in the Page Builder, enabling content authors and developers to easily configure visual options, placeholders, sizing, multiple selections, and color themes directly within the CMS.
Usage
These examples illustrate how content editors bind and structure interactive select dropdown.
1. Standard Single Option Selection
A standard single dropdown list allowing users to select their favorite framework. It features a custom label and placeholder text.
{
"type": "select",
"label": "Framework",
"placeholder": "Select a framework",
"interactive": true,
"items": [
{ "label": "React", "value": "react" },
{ "label": "Solid", "value": "solid" },
{ "label": "Svelte", "value": "svelte", "disabled": true },
{ "label": "Vue", "value": "vue" },
{ "label": "Hono", "value": "hono" }
]
}
2. Multi-Option Selection with Custom Style (Surface Variant)
Demonstrates how to enable multiple active selections, showing trigger tags separated by commas. It also showcases a distinct visual surface variant.
{
"type": "select",
"label": "CSS Frameworks",
"placeholder": "Choose frameworks",
"multiple": true,
"variant": "surface",
"size": "lg",
"defaultValue": ["panda"],
"interactive": true,
"items": [
{ "label": "Tailwind CSS", "value": "tailwind" },
{ "label": "Panda CSS", "value": "panda" },
{ "label": "Vanilla Extract", "value": "vanilla" }
]
}
3. Disabled Dropdown Selector
Shows a temporarily unavailable or read-only select element. This visual state disables all interactions, preventing the dropdown list from being opened or focused.
{
"type": "select",
"label": "Language Settings",
"placeholder": "Select Language",
"disabled": true,
"interactive": true,
"items": [
{ "label": "English", "value": "en" },
{ "label": "Deutsch", "value": "de" }
]
}
Props
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Label Text (label) | string | - | Descriptive text rendered above the select dropdown trigger. |
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 select dropdown. |
Error Text (errorText) | string | - | Error message rendered below the select dropdown when the field is invalid. |
Placeholder (placeholder) | string | - | Ghost text visible inside the trigger button when no options are selected. |
Items List (items) | list | - | List of options containing label, value, and optional disabled status. |
Multiple Selection (multiple) | boolean | false | When enabled, users can select several options; the dropdown stays open during selection. |
Default Value (defaultValue) | list | - | Initial selection array representing the option values to pre-check on load. |
Deselectable (deselectable) | boolean | false | Allows single-selection options to be cleared by clicking the active choice again. |
Form Name (name) | string | - | Standard HTML name attribute used to bundle native values during form submissions. |
Disabled (disabled) | boolean | false | Disables user interaction and applies a dimmed overlay to the dropdown. |
Invalid State (invalid) | boolean | false | Triggers error borders and displays an invalid visual state. |
Visual Variant (variant) | select | "outline" | Border and fill theme for the trigger. • Options: "outline", "surface". |
Size Scale (size) | select | "md" | Controls overall spacing, padding, and font-sizing. • Options: "xs", "sm", "md", "lg", "xl". |
Force Interactive (interactive) | boolean | true | Hydrates the dropdown trigger and menu overlay as an interactive client-side island. |
Developer Notes & Accessibility
- Hydration Island: Because Select requires client JavaScript to toggle menus, filter options, and bind custom key listeners, it is hydrated as an interactive Preact island (
"interactive": true) by default. - WAI-ARIA Compliance: The component acts as a high-fidelity semantic custom combobox. Focus remains safely on the trigger button (
role="combobox"), while options are managed dynamically via standardaria-activedescendant,aria-expanded, andaria-controlsbindings. Keyboard arrows,Home/End, andEscapeoperate smoothly out-of-the-box. - Form Integration: It outputs a visually hidden, native
<select>element populated with hidden<option>elements matching your selection. Standard HTTP POST form submissions function natively without any auxiliary JS state serialization.