Skip to content
Mizen UI
Docs

IntroductionInstallationCLIStylingFoundationsThemingCompositionIntegrationsAccessibilityFor agents

useCopyToClipboard

AccordionAspect RatioCardCollapsibleFrameGridGroupInlineScroll AreaSectionSeparatorSpacerStack

BlockquoteCitationCodeHeadingKbdLabelLinkTextVisually Hidden

ButtonButton GroupToggleToggle groupToolbar

CalendarCheckboxCheckbox groupComboboxDate pickerDate range pickerDate-Time InputFieldFieldsetFile UploadFormInputInput groupNumber fieldOTP FieldRadio groupSelectSliderSwitchTextareaTime Input

BreadcrumbMenubarNavigation MenuPaginationSegmented ControlStepperTabs

Alert dialogCommandContext MenuDialogDrawerMenuPopoverPreview CardSheetTooltip

AlertBadgeEmptyError StateMeterProgressSkeletonSpinnerStatus dotToast

Activity FeedAvatarAvatar GroupData TableListMetricOverflow ListProperty ListTableTokenTree

Area ChartBar ListCalendar HeatmapCategory ComparisonChart FrameChart LegendChart TooltipDistributionFunnelHeatmapMetric TrendPart-to-WholeProgress RingsRadar ChartRadial BarsSankey ChartScatter ChartScore GaugeTime Series

Diagram

AttachmentCarouselCode BlockLightboxMarkdownThumbnailTimestamp

Agent ThinkingApproval CardComposerConversationInline CitationMessageMessage ScrollerQuestion CardSourcesStreaming TextSuggestionTask ListTerminalTool Call

On this page

  • Preview
  • Usage
  • Anatomy
  • Installation
  • Single Selection
  • Multiple Selection
  • Examples
  • Disabled
  • Small Size
  • Large Size
  • With Label
  • Auto Highlight
  • With Clear Button
  • With Groups
  • With Multiple Selection
  • With Start Addon
  • With Start Addon - Multiple
  • With Input Inside Popup
  • With Select-like Button
  • Form Integration
  • Form Integration - Multiple
  • Primitive Values from Objects
  • Keyboard-accessible actions
  • Read-only framework
  • Required framework
  • Recommendations
  • Usage boundaries
  • API reference
  • Combobox
  • createComboboxItems
  • ComboboxInput
  • ComboboxPopup
  • ComboboxList
  • ComboboxItem
  • ComboboxEmpty
  • ComboboxGroup
  • ComboboxGroupLabel
  • ComboboxCollection
  • ComboboxChips
  • ComboboxChipsInput
  • ComboboxChip
  • ComboboxValue
  • ComboboxTrigger
  • ComboboxClear
  • ComboboxChipRemove
  • ComboboxSeparator
  • ComboboxRow
  • ComboboxStatus
  • useComboboxFilter
  • ComboboxPrimitive
  • ComboboxContext
  • SelectButton

Forms

Combobox

Combines a text input with an anchored popup list for filtering and selecting values.

idle

Usage

import {
	Combobox,
	ComboboxEmpty,
	ComboboxInput,
	ComboboxItem,
	ComboboxList,
	ComboboxPopup,
} from "@mizen-labs/ui";

Anatomy

The parts and how they nest, taken from the preview above.

<Combobox>
	<ComboboxInput />
	<ComboboxPopup>
		<ComboboxEmpty />
		<ComboboxList>
			<ComboboxItem />
		</ComboboxList>
	</ComboboxPopup>
</Combobox>

Installation

Install the Mizen package and import the required parts. These examples use Mizen surfaces and Tabler icons.

import {
  Combobox, ComboboxInput, ComboboxPopup, ComboboxList,
  ComboboxItem, ComboboxEmpty,
} from "@mizen-labs/ui/combobox";

Single Selection

Provide items and render each option through ComboboxList. The root supports controlled and uncontrolled selection.

const frameworks = ["React", "Vue", "Svelte"];

<Combobox items={frameworks}>
  <ComboboxInput aria-label="Framework" placeholder="Choose a framework…" />
  <ComboboxPopup>
    <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
    <ComboboxList>
      {(framework: string) => (
        <ComboboxItem key={framework} value={framework}>{framework}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Multiple Selection

Set multiple and render selected values as chips. Use ComboboxChipsInput for search and name each removal action.

<Combobox items={frameworks} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(values: string[]) => values.map(value => (
        <ComboboxChip key={value} removeProps={{ "aria-label": `Remove ${value}` }}>
          {value}
        </ComboboxChip>
      ))}
    </ComboboxValue>
    <ComboboxChipsInput aria-label="Frameworks" placeholder="Add framework…" />
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
    <ComboboxList>
      {(framework: string) => (
        <ComboboxItem key={framework} value={framework}>{framework}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Examples

Disabled

Prevents editing and opening the popup.

Small Size

Uses the compact input size.

Large Size

Uses the large input size.

With Label

Provide items and a visible field label; the empty state explains when filtering finds no option.

Auto Highlight

Highlights the first matching item for keyboard selection.

With Clear Button

Clears the selected value without opening the popup.

With Groups

Filters grouped options and preserves their headings.

With Multiple Selection

Choose the tags that describe this project.

With Start Addon

Places a search icon at the start of the input.

With Start Addon - Multiple

Places a search icon before removable selection chips.

With Input Inside Popup

Opens a searchable list from an outline button.

With Select-like Button

Uses SelectButton as the ComboboxTrigger render target.

Form Integration

Submits the selected value through native FormData with required validation.

Form Integration - Multiple

Submits repeated native form entries for multiple selections.

Primitive Values from Objects

Uses createComboboxItems to display names while storing stable identifiers.

Keyboard-accessible actions

The clear and trigger buttons participate in keyboard navigation.

Read-only framework

Read-only controls allow selection and copying without edits.

Required framework

Use an invalid state with a nearby explanation of the error.

Recommendations

GuidancePractice
Do

Use filtering when the option set is hard to scan. Keep option labels distinct and explain empty results.

Usage boundaries

GuidanceBoundary
Scope

Use Select for a short fixed list. Remote search, request cancellation, and result loading belong to the application.

API reference

Public props from @mizen-labs/ui. Use exported prop types for the complete TypeScript contract.

Combobox

Owns selection, search, popup state, and native form values.

PropTypeDefaultDescription
itemsreadonly Item[] | grouped items—Provides the searchable collection.
multiplebooleanfalseSelects several values and submits repeated form entries.
value / defaultValueValue | Value[] | null—Controls selection or supplies the initial uncontrolled selection.
onValueChange(value, eventDetails) => void—Receives selection changes.
open / defaultOpenbooleanfalseControls the popup or supplies its initial open state.
onOpenChange(open, eventDetails) => void—Receives popup state changes.
inputValue / defaultInputValuestring—Controls search text or supplies its initial value.
onInputValueChange(inputValue, eventDetails) => void—Receives search text changes.
autoHighlightbooleanfalseHighlights the first matching option.
filter(item, query, itemToString) => boolean | null—Overrides item filtering; null disables built-in filtering.
itemToStringLabel / itemToStringValue(value) => string—Converts selected objects into display labels and submitted form values.
isItemEqualToValue(item, value) => boolean—Compares objects when references differ.
name / required / disabled / readOnlystring / boolean—Configures native form submission, validation, and interaction.
...propsComboboxProps<Value, Multiple, Item>—Supports the complete Base UI root API.

createComboboxItems

Builds a typed collection from objects while selecting stable primitive identifiers.

PropTypeDefaultDescription
itemsreadonly Item[]—Source objects; keep static collections outside components.
options.getLabel / options.getValue(item) => string / (item) => Value—Derives search labels and stored values.

ComboboxInput

Single-selection input with optional leading content and trailing actions.

PropTypeDefaultDescription
size"sm" | "default" | "lg" | number"default"Named Mizen size or native input size.
startAddonReactNode—Leading icon or content.
showTrigger / showClearbooleantrue / falseShows the trigger or selected-value clear button.
triggerProps / clearPropsBase UI Trigger.Props / Clear.Props—Configures internal actions, including accessible labels and tabIndex.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxPopup

Anchored popup rendered through a portal; uses the chips container for multiple selection.

PropTypeDefaultDescription
side / alignPositioner side / align"bottom" / "start"Chooses placement.
sideOffset / alignOffsetnumber4 / Base UI defaultOffsets the popup from its anchor.
anchorPositioner.Props["anchor"]—Overrides the positioning anchor.
portalPropsPortal.Props—Configures container and keepMounted.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxList

Scrollable item collection. Children may be nodes or an item-rendering function.

PropTypeDefaultDescription
childrenReactNode | (item, index) => ReactNode—Renders filtered items from the root or current group.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxItem

Selectable option with a selected-state checkmark.

PropTypeDefaultDescription
valueValue—The selected value.
disabledbooleanfalseExcludes the option from selection.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxEmpty

Displays content when filtering leaves no matching items.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxGroup

Groups related items without adding another selection controller.

PropTypeDefaultDescription
itemsreadonly Item[]—Provides this group’s collection.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxGroupLabel

Visible heading for a group of options.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxCollection

Renders items from the current root or group collection.

PropTypeDefaultDescription
children(item, index) => ReactNode—Creates each item using the current filtered collection.

ComboboxChips

Container for selected values in multiple mode; also anchors the popup.

PropTypeDefaultDescription
startAddonReactNode—Leading content before the selected chips.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxChipsInput

Minimal input for multiple selection; does not add its own trigger or clear button.

PropTypeDefaultDescription
size"sm" | "default" | "lg" | number"default"Named Mizen size or native input size.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxChip

One selected value with an integrated removal action.

PropTypeDefaultDescription
removePropsChipRemove.Props—Configures the removal button; use a value-specific aria-label.
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxValue

Reads the current selection for custom display or chip rendering.

PropTypeDefaultDescription
childrenReactNode | (value) => ReactNode—Renders the current selection.
placeholderReactNode—Displays when no value is selected.

ComboboxTrigger

Opens the popup. Use render with Button or SelectButton for a standalone trigger.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxClear

Clears the selected value; renders only when a value exists.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxChipRemove

Removes the current chip through Base UI selection behavior.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxSeparator

Separates option groups.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxRow

Arranges options in a navigable row.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

ComboboxStatus

Announces collection updates to assistive technology.

PropTypeDefaultDescription
render / refReactElement | render callback / native ref—Changes the host element or receives its ref; internal slot names remain protected.
...propsBase UI part props—Forwards native attributes, events, and the corresponding Base UI props.

useComboboxFilter

Creates locale-aware matching helpers for custom item filtering.

PropTypeDefaultDescription
optionsIntl.CollatorOptions—Controls case, accent, and locale matching.
result{ contains, startsWith, endsWith }—Matching functions for custom filters.

ComboboxPrimitive

Exports the installed Base UI Combobox namespace for advanced composition.

PropTypeDefaultDescription
exportBase UI Combobox—Includes native parts, createItems, and useFilter.

ComboboxContext

Provides the wrapper’s chip anchor and selection mode.

PropTypeDefaultDescription
value{ chipsRef: RefObject<Element | null> | null; multiple: boolean }—Exposes the shared multiple-selection anchor.

SelectButton

Select-style button that works outside Select context. Import from @mizen-labs/ui/select.

PropTypeDefaultDescription
size"sm" | "default" | "lg""default"Reuses Mizen Select sizing.
renderReactElement | render callback—Changes the host element using Base UI useRender.
...propsuseRender.ComponentProps<"button">—Accepts native button props and ref.
PreviousCheckbox groupNextDate picker
Design
Engineering
React