HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
ComboboxView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA text field that filters a list of options as you type.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/combobox'import'@fusion.dev/helix/option'// Optionimport'@fusion.dev/helix-headless/combobox'import'@fusion.dev/helix-headless/option'// OptionPreview
API ReferenceRoothelix-comboboxA text field that filters a list of options as you type.
PropTypeDescriptionallowsCustomValuebooleanDefaultfalseWhether text that names no option is taken as the value, as React Aria's
allowsCustomValue.autocompletestringDefault"off"What the browser may autofill, as a platform token such as country.collapseLabelstringDefault"Show fewer"The button's label, read by screen readers, once every token is showing.creatablebooleanDefaultfalseWhether the user can add a value that is not in the list.createLabelstringDefault"Add "{value}""The text of the create row. {value} is what was typed.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.emptyTextstringDefault"No matches"Text shown when the filter hides every option.expandablebooleanDefaultfalseWhether the count is a button that shows the hidden tokens.expandLabelstringDefault"Show all"The count button's label, read by screen readers. Its visible text, such
as +3, does not say what it does.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.filterDelaynumberDefault0How long typing rests before the list is narrowed and helix-filter is
sent, in milliseconds. The attribute also takes a CSS time, such as
300ms.formValue"key"|"text"What the form receives for each chosen option: key, its value, or
text, its words, as React Aria's ComboBox formValue offers.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.listLabelstringDefault"Options"The list's name, read by screen readers. The list has no visible name.loadErrorstring|nullDefault""What the list says when its options could not be loaded, such as after a
request to a server fails. Empty, null or no attribute is no error, so
removing the attribute clears it. Passed to the list, which shows it
under any options there are and tells screen readers.loadingbooleanDefaultfalseWhether the options are still loading.loadingTextstringDefault"Loading"Text the list shows while the options load.localestringDefault""The locale the words, plural forms, and numbers are in, as a BCP 47 tag
such as pl. Empty reads the nearest lang, then the browser's
language.maxTagsnumberDefault0How many tokens to show before the rest become a count.multiplebooleanDefaultfalseWhether more than one option can be chosen.namestringDefault""The name the control's value is submitted under.noResultsTextstringThe text shown when typing hides every one of the options, where there are
some. Absent, empty-text shows. See Listbox's no-results-text.openbooleanWhether the element is open.openOn"focus"|"input"|"manual"Default"input"What opens the list: input, typing or pressing Down; focus, also
arriving in the field, by Tab or a press; or manual, only Down, Alt+Down
or a press on the caret, so typing narrows a list the reader has asked
for. React Aria's menuTrigger.placeholderstringDefault""Text shown while nothing has been chosen.readOnlybooleanDefaultfalseWhether the choice is locked. A read-only combobox still submits its value.removeLabelstringDefault"Remove {name}"The name of the control that removes one chosen option, with {name}
filled in.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.restTextstringDefault"+{count}"The count of the tokens past max-tags, as it is shown, with {count}
for the number, written in the element's locale.resultLabelstringWhat a screen reader hears when typing leaves one option, where
results-label should not say it. {count} is the count.resultsLabelstringDefault"{count, plural, one {# result} other {# results}}"What a screen reader hears when typing narrows the list. {count} is how
many options are left, written in the locale, and each language writes
the forms it has: {count, plural, one {# wynik} few {# wyniki} many {# wyników} other {# wyniku}}.selectedIndexnumberWhich option is chosen, as an index, or -1 where none is.selectedLabelstringDefault"{name}, selected"What VoiceOver hears for a chosen option, as the highlight reaches it and
once it is chosen, on Apple devices. {name} is the option's words.suggestbooleanDefaultfalseWhether the field completes the word as the user types.valuestringThe control's current value, which its form submits.valueMissingMessagestringDefault"Choose one to continue."The message shown when the field is required and empty.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.typestringThe control type, select-one or select-multiple, as on a native
<select>.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The options.emptyWhat the list shows when typing hides every option, for content richer than empty-text.endAfter the text, for a unit or a clear button.errorWhat the list shows while load-error is set, for content richer than its text.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintThe hint, for content richer than plain text.indicatorReplaces the caret that shows the field opens a list.labelThe label, for content richer than plain text.loadingWhat the list shows while the options load, for content richer than loading-text.no-resultsWhat the list shows when typing hides every option, for content richer than no-results-text.startBefore the text, for an icon.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the chosen option changes. Cancelable: cancel it to keep the current option.helix-before-closeHelixBeforeCloseEventFired before the panel closes. Cancelable: cancel it to keep the panel open.helix-before-openHelixBeforeOpenEventFired before the panel opens. Cancelable: cancel it to keep the panel closed.helix-createHelixCreateEventFired when the user adds a value that is not in the list. Cancelable.helix-filterHelixFilterEventFired as the user types, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and do the filtering yourself.helix-load-moreHelixLoadMoreEventFired once the list is scrolled within a screen of its end, once for each number of options, and not while loading is set. Add the next page and set loading while you fetch it.inputEventFired after the value changes.toggleToggleEventFired when the panel opens or closes, with newState and oldState.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptioncontrolThe text field itself.createThe row offering to add what was typed.create-activeThe create row while the keyboard is on it. Set alongside create.feedbackThe message that explains what is wrong with the value.fieldThe box around the text and its marks.hintHelp text under the field, shown while there is no error.indicatorThe caret.labelThe label above the field.listboxThe list inside the panel.listbox-emptyShown when a filter has hidden everything.listbox-errorShown while load-error is set.listbox-feedbackThe inner list's error message.listbox-filter-iconThe icon beside the list's filter field.listbox-filter-markThe glyph beside the filter field, where none is slotted.listbox-hintHelp under the list.listbox-itemsThe element that holds the options.listbox-labelThe label above the list.listbox-liveThe inner list's live part, the region screen readers announce its empty and loading messages, and how many options typing left, from.listbox-loadingShown while the options are loading.listbox-searchThe region holding the field that narrows the list.listbox-search-fieldThe filter field inside that region.liveThe region VoiceOver hears the highlight, the count and a choice from on Apple devices, drawn once there is one to say. Visually hidden in the styled tier.restThe count of choices held beyond max-tags. A <button> with expandable, a <span> without it.surfaceThe floating panel.tagOne chosen option.tag-cellThe tag's grid cell, which a tag draws only inside a tag group.tag-dismissThe remove button, when dismissible.tag-dismiss-markThe glyph on the dismiss control, where none is slotted.tag-labelThe label, trimmed to its capitals and baseline.tag-linkThe tag's link around its label, which a tag draws only with href.tag-startThe category before the label.tagsThe row of chosen options, when multiple is set.
CSS PropertyDescription--combobox-background-colorFill behind the field.--combobox-border-colorColor of the panel's edge.--combobox-border-widthWidth of the panel's edge. Follows --helix-border-floating, which is 0 unless your theme sets it, so the panel's shadow sets it apart.--combobox-control-sizeSmallest the text field shrinks to once tags share its line.--combobox-panel-sizeWidth of the panel. Follows the field by default.--combobox-shadowShadow under the panel. Follows --helix-shadow-floating. A floating panel can sit over any content, so it has a shadow by default.
Custom stateDescriptionblankWhile nothing is chosen.errorWhile load-error is set.invalidThe control has an error to show, from the browser's validation or from your feedback.loadingWhile loading is set.no-resultsWhat was typed hid every option of a list that has some.openWhile the list is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-comboboxA text field that filters a list of options as you type.
PropTypeDescriptionallowsCustomValuebooleanDefaultfalseWhether text that names no option is taken as the value, as React Aria's
allowsCustomValue.autocompletestringDefault"off"What the browser may autofill, as a platform token such as country.collapseLabelstringDefault"Show fewer"The button's label, read by screen readers, once every token is showing.creatablebooleanDefaultfalseWhether the user can add a value that is not in the list.createLabelstringDefault"Add "{value}""The text of the create row. {value} is what was typed.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.emptyTextstringDefault"No matches"Text shown when the filter hides every option.expandablebooleanDefaultfalseWhether the count is a button that shows the hidden tokens.expandLabelstringDefault"Show all"The count button's label, read by screen readers. Its visible text, such
as +3, does not say what it does.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.filterDelaynumberDefault0How long typing rests before the list is narrowed and helix-filter is
sent, in milliseconds. The attribute also takes a CSS time, such as
300ms.formValue"key"|"text"What the form receives for each chosen option: key, its value, or
text, its words, as React Aria's ComboBox formValue offers.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.listLabelstringDefault"Options"The list's name, read by screen readers. The list has no visible name.loadErrorstring|nullDefault""What the list says when its options could not be loaded, such as after a
request to a server fails. Empty, null or no attribute is no error, so
removing the attribute clears it. Passed to the list, which shows it
under any options there are and tells screen readers.loadingbooleanDefaultfalseWhether the options are still loading.loadingTextstringDefault"Loading"Text the list shows while the options load.localestringDefault""The locale the words, plural forms, and numbers are in, as a BCP 47 tag
such as pl. Empty reads the nearest lang, then the browser's
language.maxTagsnumberDefault0How many tokens to show before the rest become a count.multiplebooleanDefaultfalseWhether more than one option can be chosen.namestringDefault""The name the control's value is submitted under.noResultsTextstringThe text shown when typing hides every one of the options, where there are
some. Absent, empty-text shows. See Listbox's no-results-text.openbooleanWhether the element is open.openOn"focus"|"input"|"manual"Default"input"What opens the list: input, typing or pressing Down; focus, also
arriving in the field, by Tab or a press; or manual, only Down, Alt+Down
or a press on the caret, so typing narrows a list the reader has asked
for. React Aria's menuTrigger.placeholderstringDefault""Text shown while nothing has been chosen.readOnlybooleanDefaultfalseWhether the choice is locked. A read-only combobox still submits its value.removeLabelstringDefault"Remove {name}"The name of the control that removes one chosen option, with {name}
filled in.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.restTextstringDefault"+{count}"The count of the tokens past max-tags, as it is shown, with {count}
for the number, written in the element's locale.resultLabelstringWhat a screen reader hears when typing leaves one option, where
results-label should not say it. {count} is the count.resultsLabelstringDefault"{count, plural, one {# result} other {# results}}"What a screen reader hears when typing narrows the list. {count} is how
many options are left, written in the locale, and each language writes
the forms it has: {count, plural, one {# wynik} few {# wyniki} many {# wyników} other {# wyniku}}.selectedIndexnumberWhich option is chosen, as an index, or -1 where none is.selectedLabelstringDefault"{name}, selected"What VoiceOver hears for a chosen option, as the highlight reaches it and
once it is chosen, on Apple devices. {name} is the option's words.suggestbooleanDefaultfalseWhether the field completes the word as the user types.valuestringThe control's current value, which its form submits.valueMissingMessagestringDefault"Choose one to continue."The message reported when the field is required and nothing is chosen.
Absent, or empty, is this sentence, or the words registered for the page's
locale.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.typestringThe control type, select-one or select-multiple, as on a native
<select>.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The options.emptyWhat the list shows when typing hides every option, for content richer than empty-text.endAfter the text, for a unit or a clear button.errorWhat the list shows while load-error is set, for content richer than its text.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintThe hint, for content richer than plain text.indicatorReplaces the caret that shows the field opens a list.labelThe label, for content richer than plain text.loadingWhat the list shows while the options load, for content richer than loading-text.no-resultsWhat the list shows when typing hides every option, for content richer than no-results-text.startBefore the text, for an icon.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the chosen option changes. Cancelable: cancel it to keep the current option.helix-before-closeHelixBeforeCloseEventFired before the panel closes. Cancelable: cancel it to keep the panel open.helix-before-openHelixBeforeOpenEventFired before the panel opens. Cancelable: cancel it to keep the panel closed.helix-createHelixCreateEventFired when the user adds a value that is not in the list. Cancelable.helix-filterHelixFilterEventFired as the user types, with the text the list is filtered by. Cancelable: cancel it to leave the list unfiltered and do the filtering yourself.helix-load-moreHelixLoadMoreEventFired once the list is scrolled within a screen of its end, once for each number of options, and not while loading is set. Add the next page and set loading while you fetch it.inputEventFired after the value changes.toggleToggleEventFired when the panel opens or closes, with newState and oldState.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestOpen(next: boolean) => booleanRequests the list open or closed. While readOnly is set, it does not open.requestValue(next: string) => booleanRequests a new value. While readOnly is set, nothing changes.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptioncontrolThe text field itself.createThe row offering to add what was typed.create-activeThe create row while the keyboard is on it. Set alongside create.feedbackThe message that explains what is wrong with the value.fieldThe box around the text and its marks.hintHelp text under the field, shown while there is no error.indicatorThe caret.labelThe label above the field.listboxThe list inside the panel.listbox-emptyShown when a filter has hidden everything.listbox-errorShown while load-error is set.listbox-feedbackThe inner list's error message.listbox-filter-iconThe icon beside the list's filter field.listbox-filter-markThe glyph beside the filter field, where none is slotted.listbox-hintHelp under the list.listbox-itemsThe element that holds the options.listbox-labelThe label above the list.listbox-liveThe inner list's live part, the region screen readers announce its empty and loading messages, and how many options typing left, from.listbox-loadingShown while the options are loading.listbox-searchThe region holding the field that narrows the list.listbox-search-fieldThe filter field inside that region.liveThe region VoiceOver hears the highlight, the count and a choice from on Apple devices, drawn once there is one to say. Visually hidden in the styled tier.restThe count of choices held beyond max-tags. A <button> with expandable, a <span> without it.surfaceThe floating panel.tagOne chosen option.tag-cellThe tag's grid cell, which a tag draws only inside a tag group.tag-dismissThe remove button, when dismissible.tag-dismiss-markThe glyph on the dismiss control, where none is slotted.tag-labelThe label, trimmed to its capitals and baseline.tag-linkThe tag's link around its label, which a tag draws only with href.tag-startThe category before the label.tagsThe row of chosen options, when multiple is set.
Custom stateDescriptionblankWhile nothing is chosen.errorWhile load-error is set.invalidThe control has an error to show, from the browser's validation or from your feedback.loadingWhile loading is set.no-resultsWhat was typed hid every option of a list that has some.openWhile the list is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionChosenA combobox that opens with a value already chosen, as in an edit form.CreatableAdding a typed value that is not in the list.DisabledDisabled with a value, so the value is still readable.EmptyA list with no options, which shows a message in its panel.EventsThe seven events fired for one choice, each reporting a different change.InvalidAn invalid choice, with a message that explains why.Max TagsA limit on how many tags are shown, with a count of the rest that you can expand.MultipleSeveral choices at once, each shown as a tag.PreviewType to narrow a list, and choose from what is left.PreviewType to narrow a list, and choose from what is left.RequiredA required choice that must be made before the form submits.SuggestThe rest of the matching option filled in after the cursor as you type.