Filter
A multi-level filter component optimized for small screen experiences.
Examples
Current state:
Usage
Do
- Use basic filter when space is at a premium
- Use basic filter within card, panel, master panel, and other containers
- Use filter bar for page-wide content
- Use filter bar when there is enough space available to display selections
Don’t
- Use basic filter for page-wide content
Anatomy
Basic filter: closed
- (1) Rest and off states
- (2) Hover and off
- (3) Rest and on
Basic filter: open
- (1) Menu open in overview, none selected
- (2) Menu open in overview, none selected, hovered section
Basic filter: selection
- (1) Menu open inside section, none selected
- (2) Menu open inside section, selected
- (3) Menu open in overview, selected
Basic filter: search
- (1) Menu open in overview, focus on search
- (2) Menu open, loading search results
- (3) Menu open, search results
- (4) Menu open in overview, selected
Related
APIs
IFilterProps<T = {}>
activeFilter
ObservableValue<IFilterItem<T> | null>
The currently selected filter. If omitted, the Filter will keep track of this internally.
bestHitItem
ObservableValue<IListBoxItem<T>>
Specify an item to be highlighted as a best hit when the user performs a top level search in the filter box.
className
string
Classname to pass to the Filter's Expandable Button.
filterByText: true
boolean
Set to false to not do any text filtering when the user types in the filter box. Do this if you want
to control filtering through userFilteredItems.
filterItemsrequired
Items that correspond to different keys within the filterStore. Items will render as rows in the inital callout view of the Filter,
and if selected will display their items or custom content to select the value for that filter key.
filterStorerequired
IFilter
The store object that holds the filter state.
hideBackButtonfalse
boolean
Set to true to hide the back button when a filter is active.
itemsrequired
The caller may supply the set of items to be shown through the ItemProvider or array.
The IItemProvider allows the caller to store their items in the form that
bests suits their needs but gives the underlying listbox a well defined interface for
requesting the items. This can include async fetching of items through
observables. Use an IItemProvider or something that implements it like ObservableArray
If the items will be changing.
onActiveFilterChanged
(activeFilter: IFilterItem | null) => void
A callback to notify when the active filter has changed.
onFilterTextChanged
(e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement> | null, newValue: string) => void
A callback to notify when the filter box text has changed. Do custom searching here and update the filterItem's items.
selection
A selection object used by the underlying Dropdown to maintain the selection state.
showActiveFilterResetButton
boolean
Set to true to show a reset button instead of a clear button in the active filter view.
showFilterOnText
boolean
Whether or not the filter button text should change to "Filter on" when there is an active filter
title
string
The title displayed at the top of the Filter's callout.
userFilteredItems
Provide if you want to show a custom set of filtered items.
width320
number
The width of the Filter's callout in px.
IFilterItem<T = {}>
actionsoptionalInherited From: IDropdownCalloutProps<T = {}>
Actions to render in the footer of the dropdown.
activatablefalseoptionalInherited From: ITextFieldProps
boolean
Whether or not the input can be activated. Text will not be selectable and a cursor: pointer
will be used.
anchorElementoptionalInherited From: ICalloutProps
HTMLElement
If the callout is being positioned relative to an existing element in the DOM
the relative element should be supplied as the anchorElement.
(anchorOrigin should be supplied with anchorElement)
anchorOffsetoptionalInherited From: ICalloutProps
IOffset
anchorOffset is used to shift the location of the callout from the defined
location by a fixed amount. An example might be the tooltip callout defaults
to an anchorOffset of { x: 8 y: 8 } from the mouse position.
anchorOriginoptionalInherited From: ICalloutProps
IOrigin
When an anchorElement is supplied the anchorOrigin is used to describe the
relative location of the callout with respect to the anchorElement. A common
example here is a dropdown button aligns the callout to the bottom-right of
the button.
anchorPointoptionalInherited From: ICalloutProps
IPoint
Instead of using an anchorElement to position the callout, if can be positioned
based on a fixed location. The anchorPoint defines the fixed position for the
anchor.
ariaActiveDescendantoptionalInherited From: ITextFieldProps
string
aria-activedescendant on the input/textfield.
ariaAutoCompleteoptionalInherited From: ITextFieldProps
"none" | "list" | "inline" | "both"
aria-autocomplete on the input/textfield.
ariaControlsoptionalInherited From: ITextFieldProps
string
aria-controls on the input/textfield.
ariaDescribedByoptionalInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-describedby to the Expandable element.
ariaExpandedoptionalInherited From: ITextFieldProps
boolean
aria-expanded on the input/textfield.
ariaHasPopupoptionalInherited From: ITextFieldProps
boolean | "menu" | "listbox" | "tree" | "grid" | "dialog"
aria-hasPopup on the input/textfield.
ariaInvalidoptionalInherited From: ITextFieldProps
boolean
aria-invalid on the input/textfield.
ariaLabeloptionalInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-label to the Expandable element.
ariaLabelledByoptionalInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-labelled-by to the Expandable element.
ariaRoleDescriptionoptionalInherited From: ITextFieldProps
string
aria-roledescription on the input/textfield.
autoAdjustHeightfalse.optionalInherited From: ITextFieldProps
boolean
Adjust the textfield height as the contents change.
autoCompletefalse.optionalInherited From: ITextFieldProps
boolean
Should the input tag have autocomplete enabled. Ignored if multiline is set to true.
autoFocusoptionalInherited From: ITextFieldProps
boolean
autoFocus on the input/textfield.
autoSelectoptionalInherited From: IDropdownExpandableProps<T = {}>
boolean
Supply autoSelect to select all the text in the input when the textfield gets
focus. This is useful if you want the user to copy the text, or replace the text
upon typing instead of changing the current value.
blurDismissfalseoptionalInherited From: ICalloutProps
boolean
This will dismiss the callout once it gets and then loses focus. Callouts should
dismiss when they lose focus unless they are intended to be modeless UI.
calloutContentClassNameoptionalInherited From: IDropdownCalloutProps<T = {}>
string
ClassName to pass to the callout content. Use this to override the width.
classNameoptionalInherited From: IDropdownExpandableProps<T = {}>
string
ClassName to pass to the Expandable.
columnsoptionalInherited From: IListBoxSharedProps<T = {}>
Optional tree columns if showTree is passed
containerClassNameoptionalInherited From: IListBoxSharedProps<T = {}>
string
className to pass to the listbox's container.
containerRefoptionalInherited From: IDropdownExpandableProps<T = {}>
React.RefObject<HTMLDivElement>
Ref to pass to the expandable's container element.
contentLocationoptionalInherited From: ICalloutProps
This needs to be supplied for a window relative layout. Otherwise the anchorElement
is used as the location basis.
disabledoptionalInherited From: IDropdownExpandableProps<T = {}>
boolean
Set to true to make the expandable disabled.
dropdownIdoptionalInherited From: IExpandableTextFieldProps
string
Optional Id that should be used on the dropdown to uniquely identify
this element.
dropdownOriginoptionalInherited From: IExpandableTextFieldProps
IOrigin
Location on the dropdown to make relative to the button location.
editableoptionalInherited From: IExpandableTextFieldProps
boolean
Whether or not textField is editable and should be treated like a combobox.
enforceSingleSelectoptional
boolean
A custom way to force single-select options in a multi-select selection.
excludeFocusZoneoptionalInherited From: ITextFieldProps
boolean
Set to true if you don't want focus managed by a FocusZone.
excludeTabStopoptionalInherited From: IDropdownExpandableProps<T = {}>
boolean
The element should not be tabable but still should be able to receieve focus.
expandKeyKeyCode.DownArrowoptionalInherited From: IExpandableSharedProps
KeyCode | KeyCode[]
The key used to expand the components callout.
expandableRefInherited From: IDropdownExpandableProps<T = {}>
React.RefObject<ExpandableButton | ExpandableTextField>
A ref to forward to the expandable.
filterByText: trueoptionalInherited From: IDropdownProps<T = {}>
boolean
Set to false to not do any text filtering when the user types in the filter box. Do this if you want
to control filtering through userFilteredItems.
filterItemKey
string
The key in the filterStore that selection within this item corresponds to.
filterPlaceholderTextoptionalInherited From: IDropdownCalloutProps<T = {}>
string
Text to show as a placeholder in the filter box.
filteredNoResultsTextoptionalInherited From: IDropdownCalloutProps<T = {}>
string | IObservableValue<string>
Text to display when there are no filter results. Will be formatted with the current filter string.
focusTreatmentTextFieldFocusTreatmentBehavior.alloptionalInherited From: ITextFieldProps
Indicates how we should apply the focus treatment to the
TextField. Default is to show the focus treatment when focused via keyboard or mouse.
TextFields that do not wish to have focus treatment (e.g. in the filter bar) should use "none"
getUnselectableRangesoptionalInherited From: IListBoxSharedProps<T = {}>
(items: IListBoxItem<T>[]) => ISelectionRange[]
This is called when updates are made to the listBox items to update the unselectbale items in the selection.
hideDropdownIconoptionalInherited From: IExpandableTextFieldProps
boolean
If hideDropdownIcon is supplied the button acts as a dropdown button
without showing the dropdown arrows.
idInherited From: IDropdownPivot<T = {}>
string
Unique id for this pivot.
inputClassNameoptionalInherited From: ITextFieldProps
string
Classname passed to the input/textarea element.
inputElementoptionalInherited From: ITextFieldProps
React.RefObject<HTMLTextAreaElement & HTMLInputElement>
ref to get passed to the input element.
inputIdoptionalInherited From: IDropdownExpandableProps<T = {}>
string
Id to be applied to the expandable's input element.
inputTypetextoptionalInherited From: ITextFieldProps
"password" | "text" | "button" | "number"
Type that is passed to the <input> element, e.g. password, number, etc.
See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types for a full list
itemsInherited From: IDropdownPivot<T = {}>
The items to show when this pivot is active.
labeloptionalInherited From: ITextFieldProps
React.ReactNode
Label to be rendered before the TextField. Will be wrapped in a
<label> element and wired up with the appropriate aria attributes.
lightDismissoptionalInherited From: ICalloutProps
boolean
The callout element will trap mouse events and dismiss the callout when a click
occurs. This will prevent the events from being handled by the underlying
elements outside the callout's contents.
loadingoptionalInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean>
Set to true or false to trigger screen reader loading announcements. To show a loading indicator, pass an item of type ListBoxItemType.Loading in items.
maxLengthoptionalInherited From: ITextFieldProps
number
MaxLength on the input/textarea.
maxWidthoptionalInherited From: ITextFieldProps
number
The maximum width in px that the textfield will grow to.
multilineoptionalInherited From: ITextFieldProps
boolean
If true, uses a textarea instead of an input element.
nameoptionalInherited From: IDropdownPivot<T = {}>
string
Text to show for this pivot. Defaults to id if not specified.
noItemsTextoptionalInherited From: IDropdownCalloutProps<T = {}>
string
Text to show when there are no items in the listbox.
onBluroptionalInherited From: ITextFieldProps
() => void
Called when blur event is fired by the input/textarea.
onChangeoptionalInherited From: ITextFieldProps
(event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>, value: string) => void
Called when the value of the input/textarea changes.
onClickoptionalInherited From: ITextFieldProps
(event: React.MouseEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the element is clicked.
onCollapseoptionalInherited From: IDropdownExpandableProps<T = {}>
() => void
Optional callback to call when the dropdown is collapsed.
onDismissoptionalInherited From: ICalloutProps
() => void
Method that is called when the callout is dismissed.
onExpandoptionalInherited From: IDropdownExpandableProps<T = {}>
() => void
Optional callback to call when the dropdown is expanded.
onFilterTextChangedoptionalInherited From: IDropdownCalloutProps<T = {}>
(e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement> | null, newValue: string) => void
A callback to notify when the filter text has changed. Do custom searching here and update the items.
onFocusoptionalInherited From: ITextFieldProps
(event: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the focus event is fired by the input/textarea.
onKeyDownoptionalInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key down event is fired by the input/textarea.
onKeyPressoptionalInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onKeyUpoptionalInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onPasteoptionalInherited From: ITextFieldProps
(event: React.ClipboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the paste event is fired by the input/textarea.
onSelectoptionalInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onSelect is called when the row is selected. Selection occurs on the
Space keystroke or click.
@param event - This is the event that is causing the selection.
@param item - Details about the list row being selected.
onToggleoptionalInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onToggle is called when an item is either expanded or collapsed. This will only do anything if the list box is being displayed as a tree.
@param event - This is the event that is causing the toggle.
@param treeItem - Details about the list item being toggled.
placeholderoptionalInherited From: IDropdownExpandableProps<T = {}>
string
Text to show within the DropdownExpandable when there is no selected value.
portalPropsoptionalInherited From: ICalloutProps
The portalProps allow the caller to control how the Callout's portal are
configured. The default will create the portal as a full screen element
rooted in the body.
prefixIconPropsoptionalInherited From: ITextFieldProps
Props for the icon to be rendered before the input/textarea.
readOnlyfalseoptionalInherited From: ITextFieldProps
boolean
If the TextField should be read-only.
renderBeforeContentoptional
(onEditingComplete: () => void) => JSX.Element
A custom renderer for content rendered before the Listbox in the Dropdown.
@param onEditingComplete call this function when the user indicates they are done eidting and wish to return to the top level filter view.
renderCalloutInherited From: IDropdownExpandableProps<T = {}>
RenderCalloutFunction
A function which renders the dropdown's callout.
renderItemoptionalInherited From: IListBoxSharedProps<T = {}>
(rowIndex: number, columnIndex: number, tableColumn: ITableColumn<IListBoxItem<T>>, tableItem: IListBoxItem<T>) => JSX.Element
If provided, this will be called on each item to determine how it's rendered.
renderSelectedItemsoptional
(selectedItems: IListBoxItem<T>[]) => JSX.Element | null
A custom function for rendering the selected items within a filterItem. This may be required if the ListBoxItems have a custom render function.
This should not return table markup, but rather the contents of the table cell each item would normally be rendered in.
@param selectedItems A list of ListBoxItems that are selected within this filterItem's items
requiredfalse.optionalInherited From: IDropdownExpandableProps<T = {}>
boolean
Indicates whether dropdown is required or not.
resizabletrue if the TextField is multiline.optionalInherited From: ITextFieldProps
boolean
If the text area should be resizable. Only used if multiline is true.
roleoptionalInherited From: IDropdownExpandableProps<T = {}>
string
Optional aria role
rowsoptionalInherited From: ITextFieldProps
number
Number of rows the text area should have. Only used if multiline is set to true.
searchResultsLoadingTextoptionalInherited From: IListBoxSharedProps<T = {}>
string
String to show when a search is in progress.
searchingoptionalInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean | null>
Set to true to show a searching indicator in place of the list and make a screenreader announcement. Set to null to cancel a search without making
an announcement.
selectionoptionalInherited From: IListBoxSharedProps<T = {}>
The selection maintains the selected state and defines the selection behavior of the list box. Defaults to a ListSelection
with selectOnFocus set to false if not provided. Selection should be specified on mount and not updated to a new object
during the Listbox's lifecycle.
showCharacterCounteroptionalInherited From: ITextFieldProps
boolean
If the character counter against the limit in the lower right corner should be displayed.
Only used if maxLength is provided.
showItemsWhileSearchingfalseoptionalInherited From: IListBoxSharedProps<T = {}>
boolean
Set to true to show any current items while searching for more.
showPrefixtrueoptionalInherited From: IDropdownExpandableTextFieldProps
boolean
If the list item has an icon show the icon as the prefix icon in the text field.
showTreeoptionalInherited From: IListBoxSharedProps<T = {}>
boolean
Whether or not to display items as a tree rather than a list
ListBox will construct a tree using the parent field of ListBoxItems
spellCheckundefined which will default to the browser's default for the input and textarea tags.optionalInherited From: ITextFieldProps
boolean
When true or false, overrides the default spellCheck behavior of the browser.
styleTextFieldStyle.normaloptionalInherited From: ITextFieldProps
Changes visual appearance of TextField. Use TextFieldStyle.inline to style as an inline text field.
suffixIconPropsoptionalInherited From: ITextFieldProps
Props for the icon to be rendered after the input/textarea.
tabIndexoptionalInherited From: ITextFieldProps
number
Sets the tabindex on the input/textarea element.
titleoptional
string
A custom title to show in the Dropdown when this filterItem is active.
tooltipPropsoptionalInherited From: ITextFieldProps
Tooltip to show when the button is hovered.
userFilteredItemsoptionalInherited From: IDropdownCalloutProps<T = {}>
Provide if you want to show a custom set of filtered items. The items will still be filtered by text in the filterbox unless filterByText is false.
userFilteredItemsIndexMapoptionalInherited From: IDropdownCalloutProps<T = {}>
IReadonlyObservableValue<number[]>
Provides the original item index for each item in userFilteredItems.
Optional, if not provided then this will be computed by traversing items for match indices, which can be slow if there are a lot of items.
valueoptionalInherited From: ITextFieldProps
IReadonlyObservableValue<string | undefined> | string
Text value of the input/textarea. This prop is 100% controlled
by the consumer. onChange must also be implemented in order to
work properly. If this value is a raw string, the prop must be
updated to cause the TextField to re-render. If this value is an
ObservableValue, then changing its value will cause the TextField
to re-render.
width100%optionalInherited From: IListBoxSharedProps<T = {}>
number
The width of the listbox.
IFilterBarProps
className
string
Optional CSS class name to add to the filter bar container
componentRef
(component: IFilterBar) => void
Optional callback to access the IFilterBar interface. Use this instead of ref for accessing
the public methods and properties of the component.
filter
IFilter
The filter store that this filter bar updates. Apply mode handling within the filter bar is being deprecated.
If the filter uses apply mode, changes should be applied outside of the filter bar.
hideClearAction
boolean
Optional boolean to hide clear button.
onDismissClicked
() => void
Optional callback to handle clicking on the filter bar dismiss button.
onMounted
(filterBar: IFilterBar) => void
Callback that is called when the component is initially mounted. Passed an instance of the component,
so that methods like focus() can be called.
onRenderComplete
() => void
Optional callback that is invoked after the filter bar has been rendered.
searchRoleAriaLabel
string
Search role div aria label. ARIA role="search" is required to have an aria-label as it is a landmark role.
IFilterBar
focus
(): void
Focuses the first item in the filter bar
forceUpdate
(): void
Force the filter bar to re-render.
IFilterBarItemProps
componentRef
(component: IFilterBarItem) => void
filter
IFilter
The filter store that this filter bar updates (optional, the parent FilterBar's filter is used by default)
filterItemKeyrequired
string
The unique key for this filter item whose value is updated by changes to this filter item.
filterValueComparer
(a: any, b: any) => boolean
Comparer of filter values to determine when the filter needs to be updated.
isTextItem
boolean
placeholder
string
Text to show for the filter in the case that there is no current value
setKey
string
Key for FilterBarItem. If this is changed, will always update state with new props.
IFilterBarItem
focus
(): void
Focuses the item
forceUpdate
(): void
Re-render the FilterBarItem