Design System
Combobox
Select a single value from a list, with optional type-to-filter search. eShop platform — shares the floating-label field with Text Input and adds a caret and an options dropdown. Supports error and info messages, an optional left icon, disabled, and an on-dark surface variant.
Playground
States
Empty (label as placeholder), filled, error, info, and disabled. Click a field to open the list; type to filter.
Messages
Pass error for a critical message and red border, or info for neutral helper text. Error takes precedence over info.
On dark surface
Pass onDark when the field sits on a bold or dark surface — it uses the on-dark token variants for the right contrast.
When to Use
Best for
- Choosing one value from a long list — countries, currencies, categories
- Lists long enough that radio buttons would be unwieldy
- Cases where type-to-filter speeds up selection
Consider alternatives when
- There are only 2–5 options — use a Radio Button group
- Multiple values can be selected — use checkboxes or a multi-select
- Free-form text is needed — use Text Input
Props
| Prop | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Field label — doubles as the floating placeholder |
options | (string | { label, value })[] | Yes | Selectable options |
value | string | No | Selected value (controlled). Pair with onChange |
defaultValue | string | No | Initial selected value (uncontrolled) |
onChange | (value: string) => void | No | Fires when an option is selected |
searchable | boolean | No | Allow typing to filter options (default: true) |
leftIcon | FC<SVGProps> | No | SVGR icon component shown before the value |
error | string | boolean | No | Error message (string) or error border only (true) |
info | string | No | Helper message (hidden while an error is shown) |
isDisabled | boolean | No | Disable the field (default: false) |
onDark | boolean | No | Use on-dark token variants for dark surfaces (default: false) |
Import
import { Combobox } from '@/components/Combobox/eshop';
Wrap the combobox (or any ancestor) in <div data-platform="eshop"> so the eShop typography classes apply.
Design Tokens
Purpose Token Field fill var(--color-fill-element-field)Border (default / focused / error) var(--color-border-element-field[-focused|-error])Value text var(--color-content-primary)Placeholder / floated label var(--color-content-secondary) / -tertiaryCaret & left icon var(--color-content-secondary)Error message var(--color-content-critical)Options panel var(--color-fill-surface-modal) + var(--surface-shadow-modal)Focus ring var(--color-border-element-focus-ring)Radius var(--primitive-radius-12)Typography (value / label) .body-lg / .body-sm (scoped to [data-platform="eshop"])
Related Components