HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
OptionView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorOne choice in a listbox.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/option'import'@fusion.dev/helix-headless/option'Preview
API ReferenceRoothelix-optionOne choice in a listbox.
PropTypeDescriptionactivebooleanDefaultfalseWhether this is the option the keyboard is on.alternatestringDefault""A second destination for the row, opened when you choose it with the
modifier key held.alternateLabelstringDefault""The name of the second destination, announced to screen reader users.defaultSelectedbooleanWhether the markup declares this option selected. A form reset returns to it.descriptionstringA second line under the label that describes the choice.disabledbooleanDefaultfalsePrevents the option from being chosen.downloadbooleanDefaultfalseWhether following the link downloads what it names. Only meaningful
beside an href.hrefstringDefault""The URL the option links to. Setting it makes the option a link: choosing
it, with a press, Enter or a click, follows the link and selects nothing,
as React Aria's items with href do. Command, Control and Shift open it
where they open a link, in a new tab or a new window.labelstringDefault""A shorter name for this choice, for where the row does not fit.opensstringDefault""The page of commands this option opens, by name, where choosing it would
otherwise run it.relstringDefault""The link's rel. Set it whenever you set target="_blank".selectedbooleanDefaultfalseWhether this choice is currently chosen.selectionFollowsActivebooleanDefaultfalseWhether the option says it is selected while the keyboard is on it.targetstringDefault""Where the link opens, such as _blank, for an option with an href.textValuestringDefault""The words a reader types to reach this choice, where the row's own words
are not them: typeahead, a filter and a combobox match against it, and a
select's trigger shows it.valuestringDefault""The value that identifies the option, and that a form submits.
ReadTypeDescriptiontextstringThe option's text, which a listbox matches typed text against.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The option's label.descriptionA second line under the label, for content richer than the description text.endContent after the label, such as a shortcut or a count.indicatorAn icon shown while the option is chosen, in place of the check the styled option draws.startContent before the label, such as an icon or an avatar.
EventTypeDescriptionhelix-selectHelixSelectEventThe option was chosen. Cancelable: canceling it leaves the selection as it was, and keeps the browser from following an option's href.
MethodTypeDescriptionselect(modifiers: LinkModifiers) => voidSends helix-select for this option. Does nothing when it is disabled.
PartDescriptiondescriptionThe description under the label, when there is one.itemThe row.item-activeThe row the keyboard is on. Set alongside item.item-selectedThe row of a selected option. Set alongside item.labelThe option's label.textThe label and the description under it, as one column.
CSS PropertyDescription--option-active-colorThe background of the option the keyboard is on.--option-block-paddingThe space above and below the option. Command increases it for its longer list of rows.--option-paddingThe space before the label, shared with a group heading.--option-radiusThe corner radius of the row. A listbox and a select remove it.
Custom stateDescriptionactiveWhile the keyboard is on the option, which is the option aria-activedescendant names.disabledWhile the option cannot be chosen.has-indicatorAn icon is slotted into indicator.hoveredWhile a mouse or a pen is over the option. A touch sets no hover, as React Aria's data-hovered does not.pressedWhile a pointer presses the option, from the press to the release.selectedWhile the option is chosen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-option-groupA labeled group of options inside a listbox.
PropTypeDescriptionlabelstringDefault""The heading above the group's options.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The options in the group.labelThe group's heading, for a heading that needs more than plain text.
PartDescriptionitemsThe element that holds the group's options.labelThe heading.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Separatorhelix-option-separatorA rule between options or groups inside a listbox.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
CSS PropertyDescription--option-separator-colorThe rule's color.--option-separator-spaceThe space above and below the rule.--option-separator-thicknessThe rule's thickness.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-optionOne choice in a listbox.
PropTypeDescriptionactivebooleanDefaultfalseWhether this is the option the keyboard is on.alternatestringDefault""A second destination for the row, opened when you choose it with the
modifier key held.alternateLabelstringDefault""The name of the second destination, announced to screen reader users.defaultSelectedbooleanWhether the markup declares this option selected. A form reset returns to it.descriptionstringA second line under the label that describes the choice.disabledbooleanDefaultfalsePrevents the option from being chosen.downloadbooleanDefaultfalseWhether following the link downloads what it names. Only meaningful
beside an href.hrefstringDefault""The URL the option links to. Setting it makes the option a link: choosing
it, with a press, Enter or a click, follows the link and selects nothing,
as React Aria's items with href do. Command, Control and Shift open it
where they open a link, in a new tab or a new window.labelstringDefault""A shorter name for this choice, for where the row does not fit.opensstringDefault""The page of commands this option opens, by name, where choosing it would
otherwise run it.relstringDefault""The link's rel. Set it whenever you set target="_blank".selectedbooleanDefaultfalseWhether this choice is currently chosen.selectionFollowsActivebooleanDefaultfalseWhether the option says it is selected while the keyboard is on it.targetstringDefault""Where the link opens, such as _blank, for an option with an href.textValuestringDefault""The words a reader types to reach this choice, where the row's own words
are not them: typeahead, a filter and a combobox match against it, and a
select's trigger shows it.valuestringDefault""The value that identifies the option, and that a form submits.
ReadTypeDescriptiontextstringThe option's text, which a listbox matches typed text against.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The option's label.descriptionA second line under the label, for content richer than the description text.endContent after the label, such as a shortcut or a count.indicatorAn icon shown while the option is chosen, in place of the check the styled option draws.startContent before the label, such as an icon or an avatar.
EventTypeDescriptionhelix-selectHelixSelectEventThe option was chosen. Cancelable: canceling it leaves the selection as it was, and keeps the browser from following an option's href.
MethodTypeDescriptionselect(modifiers: LinkModifiers) => voidSends helix-select for this option. Does nothing when it is disabled.
PartDescriptiondescriptionThe description under the label, when there is one.itemThe row.item-activeThe row the keyboard is on. Set alongside item.item-selectedThe row of a selected option. Set alongside item.labelThe option's label.textThe label and the description under it, as one column.
Custom stateDescriptionactiveWhile the keyboard is on the option, which is the option aria-activedescendant names.disabledWhile the option cannot be chosen.has-indicatorAn icon is slotted into indicator.hoveredWhile a mouse or a pen is over the option. A touch sets no hover, as React Aria's data-hovered does not.pressedWhile a pointer presses the option, from the press to the release.selectedWhile the option is chosen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-headless-option-groupA labeled group of options inside a listbox.
PropTypeDescriptionlabelstringDefault""The heading above the group's options.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The options in the group.labelThe group's heading, for a heading that needs more than plain text.
PartDescriptionitemsThe element that holds the group's options.labelThe heading.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Separatorhelix-headless-option-separatorA rule between options or groups inside a listbox.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionEventsChoosing an option sends helix-select, which bubbles to the listbox around it.GroupedOptions in groups under headings, for a long list.PreviewOptions in a listbox, with one selected and one disabled.PreviewOptions in a listbox, with one selected and one disabled.SeparatedA rule between runs of options, where a heading would say too much.