HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Filter InputView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA text field for filters, with the active filters shown in it as tokens.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/filter-input'import'@fusion.dev/helix/filter-input/menu'// Filter Menuimport'@fusion.dev/helix/option'// Optionimport'@fusion.dev/helix-headless/filter-input'import'@fusion.dev/helix-headless/filter-input/menu'// Filter Menuimport'@fusion.dev/helix-headless/option'// OptionPreview
API ReferenceChiphelix-filter-chipOne active filter: a field, a comparison, and the values it is compared to.
PropTypeDescriptiondismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Remove filter"The dismiss control's label, read by screen readers.dismissTabStopbooleanDefaulttrueWhether the remove button is a tab stop of its own.labelstringDefault""The name of the field the filter is on, as shown on the chip.namestringThe name of the field the filter is on, in your data model.operatorstringThe name of the active comparison in your data model.operatorLabelstringDefault""The comparison as shown on the chip. Leave it empty for the field's usual
comparison.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The values the field is compared to, usually as text. It takes any content you want shown there.fieldReplaces the field's name. Use it to put an icon beside the name or to shorten it.operatorReplaces the comparison. Put a control that changes the comparison here.
EventTypeDescriptionhelix-dismissHelixDismissEventFired when the user asks to remove the filter. Cancelable: call preventDefault() to keep the chip.
MethodTypeDescriptiondismiss() => booleanFires helix-dismiss, and returns false if a listener cancels it.
PartDescriptiondismissThe button that removes the filter.dismiss-markThe icon on the remove button, shown when no icon is slotted.fieldThe name of what is being filtered.operatorThe comparison, drawn only when there is one to show.valuesThe values the field is compared to.
CSS PropertyDescription--filter-input-chip-background-colorThe fill behind the chip.--filter-input-chip-border-colorThe color of the chip's border.--filter-input-chip-radiusThe corner radius of the chip.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Fieldhelix-filter-fieldA field that a filter can apply to, with its comparisons and values.
PropTypeDescriptionlabelstringDefault""The field's name as shown in the menu and on every chip built from the
field.namestringThe field's name in your data model.
ReadTypeDescriptiondefaultOperatorHelixHeadlessFilterOperator|nullThe comparison a chip does not show, or null when no operator is marked
default.operatorsHelixHeadlessFilterOperator[]The comparisons declared in the field, in source order.valuesHelixHeadlessOption[]The values declared in the field, in source order.vocabularyFilterGrammarFieldThe field as flat data, for the menu to render and the grammar to read.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The field's comparisons, as FilterOperators, and its values, as Options. The filter input reads them and does not render them.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-filter-inputA text field for filters, with the active filters shown in it as tokens.
PropTypeDescriptionchipsbooleanDefaultfalseWhether the field keeps a FilterChip for each filter in its tags slot,
from the helix-facet events it hears.clearablebooleanDefaultfalseShows a button that empties the field.clearLabelstringDefault"Clear"The name of the clear button, read by screen readers. The button shows only
an icon.collapseLabelstringDefault"Show fewer"The button's label, read by screen readers, once every token is showing.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.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 source is asked, in milliseconds. A delay
sends one request for a word in place of one for each letter. The arrow
keys and Enter ask at once. 0 asks on every keystroke. The attribute also
takes a CSS time, such as 300ms.filterSuggestionsbooleanDefaultfalseWhether the panel narrows itself to the suggestions that hold the term
being typed, as React Aria's Autocomplete filters. Off, the panel shows
what you slot and you narrow it.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.loadingbooleanDefaultfalseWhether the suggestions are still loading, such as while a request for the
values of a typed key is out.loadingTextstringDefault"Loading"Text the panel shows while the suggestions load.maxTagsnumberDefault0How many tokens to show before the rest become a count.namestringDefault""The name the control's value is submitted under.noResultsTextstringDefault""Text the panel shows when filter-suggestions hides every suggestion, such
as "No matching filters".openbooleanWhether the element is open.placeholderstringDefault""The text shown while the field is empty.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.sourceFilterSourceWhere the suggestions come from: a function given the term at the caret,
the field it is a value of, the whole text, and an AbortSignal, which
returns the suggestions or a promise of them. Each is a string, or a
value with a label and disabled. The field draws them as options in
the panel, beside any you slot. A property only, there being no way to
write a function in markup. See the class description.suggestionLabelstringWhat a reader hears for one suggestion, where suggestions-label should
not say it. {count} is the count.suggestionsLabelstringDefault"{count, plural, one {# suggestion} other {# suggestions}}"What a reader hears as the panel opens on its suggestions. {count} is
how many, written in the locale, and each language writes the forms it
has: {count, plural, one {# sugestia} few {# sugestie} many {# sugestii} other {# sugestii}}.valuestringThe control's current value, which its form submits.valueMissingMessagestringThe message shown when the field is required and empty.
ReadTypeDescriptionfieldsHelixHeadlessFilterField[]The fields the input can filter by, declared anywhere inside it.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.selectionDirection"backward"|"forward"|"none"The direction of the selection, named as on <input>.selectionEndnumberWhere the selection ends. With nothing selected, it is the caret position.selectionStartnumberWhere the selection starts. With nothing selected, it is the caret position.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.
SlotDescriptionclear-iconReplaces the cross on the clear button, under clearable.endContent after the text, such as a count or a control.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.labelThe label, for content richer than the label text.loadingWhat the panel shows while loading is set, for content richer than loading-text.no-resultsWhat the panel shows when filter-suggestions hides every suggestion, for content richer than no-results-text.startContent before the text, such as a search icon.suggestionsSuggestions for what to type next, as Options and Option.Groups.tagsThe active filters, as FilterChips or Tags.
EventTypeDescriptionchangeEventFired from the input when the user finishes editing the text.helix-before-changeHelixBeforeChangeEventFired as the text changes. Cancelable: call preventDefault() to keep the current text.helix-before-closeHelixBeforeCloseEventFired before the suggestions close. Cancelable: call preventDefault() to keep them open.helix-before-openHelixBeforeOpenEventFired before the suggestions open. Cancelable: call preventDefault() to keep them closed.helix-dismissHelixDismissEventFired when the user removes a token with its remove button or with Backspace in an empty field. A FilterChip that names a declared field sends helix-facet instead. Cancelable: call preventDefault() to keep the token.helix-facetHelixFacetEventFired when a filter changes, whether it was typed, picked, or removed. Cancelable: call preventDefault() to leave the text and the chip as they were.helix-selectHelixSelectEventFired by an option in suggestions when it is chosen, and bubbles out of the field. Cancelable: call preventDefault() to stop other listeners acting on it. The field takes no action on an option you slotted, and you decide what it does. A suggestion from source is written over the term at the caret unless you cancel it.inputEventFired when the text changes.toggleToggleEventFired when the suggestions 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.setSelectionRange(start: number, end: number, direction: "backward" | "forward" | "none") => voidMoves the caret, or selects a run of the text.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionclearThe button that empties the field.controlThe input itself.emptyShown in the panel when filter-suggestions hides every suggestion.feedbackThe error message under the field.fieldThe box that holds everything.hintThe help text under the field, shown while there is no error.labelThe label above the field.leadThe box before the text that holds the start slot.liveThe live region that says how many suggestions the open panel offers. It is rendered from the first time the panel opens with suggestions. Visually hidden in the styled tier.loadingShown in the panel while the suggestions load: while loading is set, or a request to source is out.restThe count of tokens that did not fit. It is a <button> with expandable and a <span> without it.surfaceThe floating panel the suggestions sit in.tagsThe row the tokens sit in.
CSS PropertyDescription--filter-input-action-padding-inlineThe space on either side of a slotted control's label. It follows --helix-space-xs, the space a token uses.--filter-input-action-sizeThe height of a control slotted at either end. It follows --helix-size-tag, so it matches the height of the tokens beside it.--filter-input-background-colorThe fill behind the field.--filter-input-border-colorThe color of the suggestion panel's border.--filter-input-border-widthThe width of the suggestion panel's border. It follows --helix-border-floating.--filter-input-clear-colorThe clear button's icon at rest.--filter-input-clear-color-hoverThe clear button's icon under the pointer.--filter-input-control-sizeThe smallest width the text keeps as tokens fill the line. Below it, the text wraps to its own line.--filter-input-field-border-colorThe field's edge at rest. Hover, focus, and an error still draw their own.--filter-input-lead-border-colorThe color of the line between the leading box and the text.--filter-input-padding-inlineSpace at each side of the field, inside its edge.--filter-input-panel-sizeThe width of the suggestion panel. It matches the field by default.--filter-input-radiusCorner radius of the field.--filter-input-shadowThe shadow under the panel. It follows --helix-shadow-floating. The panel can sit over any content, so it has a shadow by default.--filter-input-sizeThe height of the empty field. The field grows from this height.
Custom stateDescriptioninvalidThe field has an error to show, from the browser's validation or from your feedback.loadingWhile loading is set, or a request to source is out.no-resultsfilter-suggestions hid every suggestion, and no-results-text or the no-results slot says so.openThe suggestions are open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Menuhelix-filter-menuA menu for building a filter by picking a field and checking its values.
PropTypeDescriptionlabelstringDefault"Filter"The menu's name, read by screen readers.
ReadTypeDescriptionfieldsHelixHeadlessFilterField[]The fields declared inside the menu, in source order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The fields the menu can filter by, as FilterFields. The menu reads them and does not render them.triggerThe control that opens the menu, usually a Button.
EventTypeDescriptionhelix-facetHelixFacetEventFired when a field's values change. Cancelable: call preventDefault() to keep the previous values.
MethodTypeDescriptionapply(field: string, values: readonlystring[], operator: string) => booleanFilters a field by the given values and sends helix-facet, as checking a
value does.operatorFor(field: HelixHeadlessFilterField) => FilterGrammarOperator | nullThe comparison a field uses: the one the user chose, or the field's
default, or the first one the field supports, in that order.valuesFor(field: string) => readonlystring[]The values checked for one field.
PartDescriptiondividerThe line between a field's comparisons and its values.divider-contentThe content set into the line.divider-lineThe line itself.entryOne row: a field, its comparison, an operator, or a value.entry-endThe trailing column of a row, which holds its shortcut.entry-itemThe row itself.entry-markThe mark at the end of a row: a check mark on a chosen value, and a caret on a field.entry-shortcutThe key drawn for a row's shortcut. The filter menu sets none, so it renders only where a subclass does.entry-shortcut-kbdThe key inside it.entry-shortcut-keyOne key of the shortcut's chord.entry-shortcut-separatorThe + between two keys of the shortcut, where the platform writes one.entry-startThe leading column.entry-surfaceThe panel a row's submenu opens in beside it. The filter menu's rows have none.menuThe menu the fields are offered in.menu-backThe button that goes back from a field's page.menu-back-markThe icon on the back button.menu-emptyShown when there are no fields to offer.menu-headerThe bar above a field's page, with the back button and the field's name.menu-liveThe inner menu's live part: the region that screen readers announce the empty and loading messages from.menu-loadingShown while the fields are loading.menu-search-fieldThe inner menu's filter field, drawn with filterable.menu-surfaceThe floating panel the menu is drawn on.menu-titleThe name of the field whose page is showing.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Operatorhelix-filter-operatorOne way a filter can compare a field to its values.
PropTypeDescriptionarity"many"|"none"|"one"How many values the comparison takes.defaultbooleanDefaultfalseMarks the comparison as the field's usual one, used unless the user picks
another.labelstringDefault""The comparison's text, shown on the chip and in the menu that changes it.namestringThe comparison's name in your data model.
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.
Chiphelix-headless-filter-chipOne active filter: a field, a comparison, and the values it is compared to.
PropTypeDescriptiondismissiblebooleanDefaultfalseWhether the element shows a control that dismisses it.dismissLabelstringDefault"Remove filter"The remove button's name, read by screen readers. The chip's own words
follow it, so several chips are told apart.dismissTabStopbooleanDefaulttrueWhether the remove button is a tab stop of its own.labelstringDefault""The name of the field the filter is on, as shown on the chip.namestringThe name of the field the filter is on, in your data model.operatorstringThe name of the active comparison in your data model.operatorLabelstringDefault""The comparison as shown on the chip. Leave it empty for the field's usual
comparison.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The values the field is compared to, usually as text. It takes any content you want shown there.fieldReplaces the field's name. Use it to put an icon beside the name or to shorten it.operatorReplaces the comparison. Put a control that changes the comparison here.
EventTypeDescriptionhelix-dismissHelixDismissEventFired when the user asks to remove the filter. Cancelable: call preventDefault() to keep the chip.
MethodTypeDescriptiondismiss() => booleanFires helix-dismiss, and returns false if a listener cancels it.
PartDescriptiondismissThe button that removes the filter.dismiss-markThe icon on the remove button, shown when no icon is slotted.fieldThe name of what is being filtered.operatorThe comparison, drawn only when there is one to show.valuesThe values the field is compared to.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Fieldhelix-headless-filter-fieldA field that a filter can apply to, with its comparisons and values.
PropTypeDescriptionlabelstringDefault""The field's name as shown in the menu and on every chip built from the
field.namestringThe field's name in your data model.
ReadTypeDescriptiondefaultOperatorHelixHeadlessFilterOperator|nullThe comparison a chip does not show, or null when no operator is marked
default.operatorsHelixHeadlessFilterOperator[]The comparisons declared in the field, in source order.valuesHelixHeadlessOption[]The values declared in the field, in source order.vocabularyFilterGrammarFieldThe field as flat data, for the menu to render and the grammar to read.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The field's comparisons, as FilterOperators, and its values, as Options. The filter input reads them and does not render them.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-filter-inputA text field for filters, with the active filters shown in it as tokens.
PropTypeDescriptionchipsbooleanDefaultfalseWhether the field keeps a FilterChip for each filter in its tags slot,
from the helix-facet events it hears.clearablebooleanDefaultfalseShows a button that empties the field.clearLabelstringDefault"Clear"The name of the clear button, read by screen readers. The button shows only
an icon.collapseLabelstringDefault"Show fewer"The button's label, read by screen readers, once every token is showing.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.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 source is asked, in milliseconds. A delay
sends one request for a word in place of one for each letter. The arrow
keys and Enter ask at once. 0 asks on every keystroke. The attribute also
takes a CSS time, such as 300ms.filterSuggestionsbooleanDefaultfalseWhether the panel narrows itself to the suggestions that hold the term
being typed, as React Aria's Autocomplete filters. Off, the panel shows
what you slot and you narrow it.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.loadingbooleanDefaultfalseWhether the suggestions are still loading, such as while a request for the
values of a typed key is out.loadingTextstringDefault"Loading"Text the panel shows while the suggestions load.maxTagsnumberDefault0How many tokens to show before the rest become a count.namestringDefault""The name the control's value is submitted under.noResultsTextstringDefault""Text the panel shows when filter-suggestions hides every suggestion, such
as "No matching filters".openbooleanWhether the element is open.placeholderstringDefault""The text shown while the field is empty.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.sourceFilterSourceWhere the suggestions come from: a function given the term at the caret,
the field it is a value of, the whole text, and an AbortSignal, which
returns the suggestions or a promise of them. Each is a string, or a
value with a label and disabled. The field draws them as options in
the panel, beside any you slot. A property only, there being no way to
write a function in markup. See the class description.suggestionLabelstringWhat a reader hears for one suggestion, where suggestions-label should
not say it. {count} is the count.suggestionsLabelstringDefault"{count, plural, one {# suggestion} other {# suggestions}}"What a reader hears as the panel opens on its suggestions. {count} is
how many, written in the locale, and each language writes the forms it
has: {count, plural, one {# sugestia} few {# sugestie} many {# sugestii} other {# sugestii}}.valuestringThe control's current value, which its form submits.valueMissingMessagestringThe message shown when the field is required and empty.
ReadTypeDescriptionfieldsHelixHeadlessFilterField[]The fields the input can filter by, declared anywhere inside it.formHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.selectionDirection"backward"|"forward"|"none"The direction of the selection, named as on <input>.selectionEndnumberWhere the selection ends. With nothing selected, it is the caret position.selectionStartnumberWhere the selection starts. With nothing selected, it is the caret position.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.
SlotDescriptionclear-iconReplaces the cross on the clear button, under clearable.endContent after the text, such as a count or a control.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.labelThe label, for content richer than the label text.loadingWhat the panel shows while loading is set, for content richer than loading-text.no-resultsWhat the panel shows when filter-suggestions hides every suggestion, for content richer than no-results-text.startContent before the text, such as a search icon.suggestionsSuggestions for what to type next, as Options and Option.Groups.tagsThe active filters, as FilterChips or Tags.
EventTypeDescriptionchangeEventFired from the input when the user finishes editing the text.helix-before-changeHelixBeforeChangeEventFired as the text changes. Cancelable: call preventDefault() to keep the current text.helix-before-closeHelixBeforeCloseEventFired before the suggestions close. Cancelable: call preventDefault() to keep them open.helix-before-openHelixBeforeOpenEventFired before the suggestions open. Cancelable: call preventDefault() to keep them closed.helix-dismissHelixDismissEventFired when the user removes a token with its remove button or with Backspace in an empty field. A FilterChip that names a declared field sends helix-facet instead. Cancelable: call preventDefault() to keep the token.helix-facetHelixFacetEventFired when a filter changes, whether it was typed, picked, or removed. Cancelable: call preventDefault() to leave the text and the chip as they were.helix-selectHelixSelectEventFired by an option in suggestions when it is chosen, and bubbles out of the field. Cancelable: call preventDefault() to stop other listeners acting on it. The field takes no action on an option you slotted, and you decide what it does. A suggestion from source is written over the term at the caret unless you cancel it.inputEventFired when the text changes.toggleToggleEventFired when the suggestions 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) => voidPuts the caret in the text field.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.setSelectionRange(start: number, end: number, direction: "backward" | "forward" | "none") => voidMoves the caret, or selects a run of the text.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionclearThe button that empties the field.controlThe input itself.emptyShown in the panel when filter-suggestions hides every suggestion.feedbackThe error message under the field.fieldThe box that holds everything.hintThe help text under the field, shown while there is no error.labelThe label above the field.leadThe box before the text that holds the start slot.liveThe live region that says how many suggestions the open panel offers. It is rendered from the first time the panel opens with suggestions. Visually hidden in the styled tier.loadingShown in the panel while the suggestions load: while loading is set, or a request to source is out.restThe count of tokens that did not fit. It is a <button> with expandable and a <span> without it.surfaceThe floating panel the suggestions sit in.tagsThe row the tokens sit in.
Custom stateDescriptioninvalidThe field has an error to show, from the browser's validation or from your feedback.loadingWhile loading is set, or a request to source is out.no-resultsfilter-suggestions hid every suggestion, and no-results-text or the no-results slot says so.openThe suggestions are open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Menuhelix-headless-filter-menuA menu for building a filter by picking a field and checking its values.
PropTypeDescriptionlabelstringDefault"Filter"The menu's name, read by screen readers.
ReadTypeDescriptionfieldsHelixHeadlessFilterField[]The fields declared inside the menu, in source order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The fields the menu can filter by, as FilterFields. The menu reads them and does not render them.triggerThe control that opens the menu, usually a Button.
EventTypeDescriptionhelix-facetHelixFacetEventFired when a field's values change. Cancelable: call preventDefault() to keep the previous values.
MethodTypeDescriptionapply(field: string, values: readonlystring[], operator: string) => booleanFilters a field by the given values and sends helix-facet, as checking a
value does.operatorFor(field: HelixHeadlessFilterField) => FilterGrammarOperator | nullThe comparison a field uses: the one the user chose, or the field's
default, or the first one the field supports, in that order.valuesFor(field: string) => readonlystring[]The values checked for one field.
PartDescriptiondividerThe line between a field's comparisons and its values.divider-contentThe content set into the line.divider-lineThe line itself.entryOne row: a field, its comparison, an operator, or a value.entry-endThe trailing column of a row, which holds its shortcut.entry-itemThe row itself.entry-markThe mark at the end of a row: a check mark on a chosen value, and a caret on a field.entry-shortcutThe key drawn for a row's shortcut. The filter menu sets none, so it renders only where a subclass does.entry-shortcut-kbdThe key inside it.entry-shortcut-keyOne key of the shortcut's chord.entry-shortcut-separatorThe + between two keys of the shortcut, where the platform writes one.entry-startThe leading column.entry-surfaceThe panel a row's submenu opens in beside it. The filter menu's rows have none.menuThe menu the fields are offered in.menu-backThe button that goes back from a field's page.menu-back-markThe icon on the back button.menu-emptyShown when there are no fields to offer.menu-headerThe bar above a field's page, with the back button and the field's name.menu-liveThe inner menu's live part: the region that screen readers announce the empty and loading messages from.menu-loadingShown while the fields are loading.menu-search-fieldThe inner menu's filter field, drawn with filterable.menu-surfaceThe floating panel the menu is drawn on.menu-titleThe name of the field whose page is showing.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Operatorhelix-headless-filter-operatorOne way a filter can compare a field to its values.
PropTypeDescriptionarity"many"|"none"|"one"How many values the comparison takes.defaultbooleanDefaultfalseMarks the comparison as the field's usual one, used unless the user picks
another.labelstringDefault""The comparison's text, shown on the chip and in the menu that changes it.namestringThe comparison's name in your data model.
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
NameDescriptionArityThe picker offers values based on how many a comparison takes.ChipsActive filters, with the comparison shown only when it is not the field's usual one.ClearableA button that empties the text and leaves the filters in place.ControlledControlling the text by preventing helix-before-change and writing the value yourself.DismissingBackspace in an empty field sends the same helix-dismiss as a tag's remove button.ExpandableA capped row that opens and closes when you press its count.Max TagsA cap on the tokens shown in a field in a row, with the rest shown as a count.PickingPicking values builds a chip, and the field's usual comparison is not shown.PreviewA filter field that grows to hold the active filters.PreviewA filter field that grows to hold the active filters.SuggestingSuggestions for keys before the colon and for values after it, in one panel.TypingTyping a filter and pressing Enter builds the same chip as the picker.