# Dropdown **Also known as:** Select, MultiSelect, ComboBox ## Description BitDropdown (also known as Select, MultiSelect or ComboBox) lets users pick one or more options from a list that opens on demand. The callout is a real listbox that keeps its grouping, is searchable with typeahead, stays fully navigable with the keyboard and is announced to a screen reader, and it covers large datasets through virtualization and on-demand loading. The ComboBox mode adds free typing, chips, autocomplete and token separators, every part of the component is templatable, and in a form it offers EditForm validation alongside a hidden native select that carries the value into a plain HTML form post. Three sizes, boxed, borderless and underlined variants, a swipeable panel on small screens and RTL support round it out. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AriaDescription | `string?` | null | Detailed description of the dropdown for the benefit of screen readers. It is rendered into a visually hidden element that the dropdown references through its aria-describedby attribute, which is what lets a field carry an instruction too long to show next to it. It is read after Description, so the two can be used together. | | AutoClearSearch | `bool` | false | Clears the typed search text after each selection in the multi select ComboBox mode, so the next item is picked from the full list instead of from the previous filter. | | AutoFocus | `bool` | false | Gives the focus to the dropdown as soon as it is rendered. | | AutoFocusSearchBox | `bool` | false | Enables auto-focusing of the SearchBox input when the callout is open. | | AutoSelectFirstMatch | `bool` | false | Makes Enter in the ComboBox mode pick the first item the typed text matches when no item matches it exactly, which is what an autocomplete does: typing "app" and pressing Enter then selects "Apple" instead of doing nothing. It takes precedence over Dynamic, so a term that matches an existing item selects that item rather than creating a new one out of it. | | CalloutFooterTemplate | `RenderFragment?` | null | Custom template to render as a footer in the callout. | | CalloutHeaderTemplate | `RenderFragment?` | null | Custom template to render as a header in the callout. | | CaretDownIcon | `BitIconInfo?` | null | The icon of the chevron down element. Takes precedence over CaretDownIconName when both are set. Use for external icon libraries (e.g. BitIconInfo.Fa("solid chevron-down"), BitIconInfo.Bi("chevron-down"), BitIconInfo.Css("my-class")). | | CaretDownIconName | `string?` | null | The icon name of the chevron down element of the dropdown from the Fluent UI icon set. | | CaretDownTemplate | `RenderFragment?` | null | The custom template for the chevron down element of the dropdown. | | ChildContent | `RenderFragment?` | null | The content of the Dropdown, a list of BitDropdownOption components. | | Chips | `bool` | false | Shows the selected items like chips in the BitDropdown. | | ChipsRemoveButtonAriaLabel | `string?` | null | The composite format of the accessible name of the remove button of a chip, which receives the text of the item the chip stands for, for example "Remove {0}". Defaults to the English message. | | ChipsRemoveIcon | `BitIconInfo?` | null | The icon of the remove button in the chips display. Takes precedence over ChipsRemoveIconName when both are set. | | ChipsRemoveIconName | `string?` | null | The icon name of the remove button in the chips display from the Fluent UI icon set. | | ChipTemplate | `RenderFragment<TItem>?` | null | The custom template for the content of a chip in the chips display, which receives the item the chip stands for. It replaces the text of the chip only; the remove button is still rendered after it. | | Classes | `BitDropdownClassStyles?` | null | Custom CSS classes for different parts of the BitDropdown. | | ClearButtonAriaLabel | `string?` | null | The accessible name (and the tooltip) of the clear button of the dropdown. Defaults to the English message. | | ClearButtonIcon | `BitIconInfo?` | null | The icon of the clear button of the dropdown. Takes precedence over ClearButtonIconName when both are set. | | ClearButtonIconName | `string?` | null | The icon name of the clear button of the dropdown from the Fluent UI icon set. | | ClearOnEscape | `bool` | false | Makes the Escape key take back the whole selection once there is nothing left for it to dismiss: the first press closes the callout (and, in the ComboBox mode, drops the text that was typed into it), and only a press with the callout already closed and nothing typed clears what is selected. It reports itself through OnClear exactly as the clear button does, and it is refused in the same places that button is - a read-only dropdown, a one-way binding. | | CloseOnSelect | `bool?` | null | Determines whether picking an item in the callout closes it. It defaults to the behavior each mode expects: a single select dropdown closes, because the pick is the whole interaction, while a multi select one stays open so the next item can be picked right away. Set it explicitly to keep a single select callout open (a long list the user keeps trying options from) or to close a multi select one after every pick. | | Color | `BitColor?` | null | The general color of the dropdown. | | Combo | `bool` | false | Activates the ComboBox feature in BitDropDown component. | | ComboBoxAddButtonAriaLabel | `string?` | null | The accessible name (and the tooltip) of the add button in the responsive ComboBox mode. Defaults to the English message. | | ComboBoxAddButtonIcon | `BitIconInfo?` | null | The icon of the add button in the responsive ComboBox mode. Takes precedence over ComboBoxAddButtonIconName when both are set. | | ComboBoxAddButtonIconName | `string?` | null | The icon name of the add button in the responsive ComboBox mode from the Fluent UI icon set. | | DefaultValues | `IEnumerable<TValue?>?` | null | The default values that will be initially used to set selected items in multi select mode if the Values parameter is not set. | | DebounceTime | `int` | 0 | The debounce time in milliseconds for the search and combo box inputs (applied when Immediate is enabled). | | Description | `string?` | null | The description rendered below the dropdown, which is also tied to it as its accessible description through aria-describedby. | | DescriptionTemplate | `RenderFragment?` | null | The custom template for the description of the dropdown, which replaces Description and is tied to the dropdown in the same way. | | DropDirection | `BitDropDirection` | BitDropDirection.TopAndBottom | Determines the allowed drop directions of the callout. | | Dynamic | `bool` | false | It is allowed to add a new item in the ComboBox mode. While the typed text names no item the list offers to create one out of it. | | DynamicItemTemplate | `RenderFragment<string>?` | null | The custom template for the row the callout offers to create a new item with in the Dynamic ComboBox mode, which receives the text the item would be created from. | | DynamicItemTextFormat | `string?` | null | The composite format of the row the callout offers to create a new item with in the Dynamic ComboBox mode, which receives the text the item would be created from, for example "Add \"{0}\"". | | DynamicValueGenerator | `Func<TItem?, TValue>?` | null | The function for generating value in a custom item when a new item is on added Dynamic ComboBox mode. | | EmptyTemplate | `RenderFragment?` | null | The custom template to render in the callout when there is no item to show. | | EmptyText | `string?` | null | The text to render in the callout when there is no item to show. | | ErrorMessage | `string?` | null | The message shown under the dropdown when the selection was rejected, which is what turns a red frame into something the user can act on. Setting it marks the dropdown invalid on its own - the same look and the same aria-invalid attribute Invalid gives it - and the message is referenced by the dropdown through its aria-describedby attribute and announced by its live region, so it reaches a screen reader the moment it shows up rather than only on the next focus. A dropdown inside an EditForm already gets its messages from the cascading EditContext through the ValidationMessage component. | | ErrorMessageTemplate | `RenderFragment?` | null | The custom content of the error message, which replaces the plain ErrorMessage text and marks the dropdown invalid in the same way. Only the plain text is announced by the live region, since a template is free to render anything at all. | | ExistsSelectedItemFunction | `Func<ICollection<TItem>, string, bool>?` | null | Decides whether the text committed in the ComboBox mode already stands for one of the selected items, in place of the default comparison of that text with the item texts, ignoring case. It receives the selected items and the committed text, and returning true stops the commit, so the same item cannot be selected (or created) twice under a name your data considers equivalent. | | FindItemFunction | `Func<ICollection<TItem>, string, TItem?>?` | null | Finds the item the text committed in the ComboBox mode stands for, in place of the default comparison of that text with the item texts, ignoring case. It receives the items and the committed text; the item it returns gets selected, and only when it returns none does AutoSelectFirstMatch and then Dynamic get their turn. | | FitWidth | `bool` | false | Enables fit-content value for the width of the root element. | | HeaderTemplate | `RenderFragment<TItem>?` | null | The custom template for rendering the header items of the dropdown. | | HideSelectedItems | `bool` | false | Removes the already selected items from the callout, which suits a multi select dropdown whose selection is visible as chips and whose list is therefore only about what is left to pick. A group header left naming nothing, and a divider left without items on one of its sides, are removed along with them. It has no effect when the items come from an ItemsProvider, which hands over the window it was asked for and is the only place that can leave the selected items out of it. | | HighlightSearch | `bool` | false | Highlights the part of the item text that matched the current search text in the callout. Only applies to the default item rendering, not to a custom ItemTemplate. The highlighted part is found by the built-in algorithm (SearchMode and SearchIgnoreDiacritics), so a custom SearchFunction that matches by some other rule can produce items with nothing to highlight. | | InitialSelectedItems | `IEnumerable<TItem>?` | null | The initial items that will be used to set selected items when using an ItemProvider. | | Immediate | `bool` | false | Searches the items as the user types in the search box (based on the 'oninput' HTML event) instead of waiting for the search box to be committed. The ComboBox input always searches as it is typed, so there it only decides whether DebounceTime and ThrottleTime apply. | | Invalid | `bool` | false | Marks the dropdown as invalid without an EditContext having said so, which is what a rejection the app decided on its own (a server response, a rule spanning two fields) needs. It gives the dropdown the same look and the same aria-invalid attribute an invalid bound value does. Setting ErrorMessage implies it. | | IsLoading | `bool` | false | Shows a loading indicator in the callout (and in place of the caret down element) while the items are being fetched. The dropdown stays interactive, so the user can still open the callout and see the loading state. | | IsOpen | `bool` | false | Determines the opening state of the callout. (two-way bound) | | ItemCheckIcon | `BitIconInfo?` | null | The icon of the check mark in the multi-select items. Takes precedence over ItemCheckIconName when both are set. | | ItemCheckIconName | `string?` | null | The icon name of the check mark in the multi-select items from the Fluent UI icon set. | | Items | `ICollection<TItem>?` | null | The list of items to display in the callout. | | ItemSize | `int` | 35 | The height of each item in pixels for virtualization. | | ItemsProvider | `BitDropdownItemsProvider<TItem>?` | null | The function providing items to the list for virtualization. It loads the items on demand, in the windows the user actually scrolls to, and receives the current search text so the filtering happens at the source instead of over an already loaded list. It requires Virtualize to be enabled, which is what requests the windows. | | ItemsProviderDebounceTime | `int` | 100 | The delay in milliseconds before an ItemsProvider request is issued, which collapses the bursts of requests produced by fast scrolling and typing into a single one. | | ItemTemplate | `RenderFragment<TItem>?` | null | The custom template for rendering the items of the dropdown. | | Label | `string?` | null | The text of the label element of the dropdown. | | LabelTemplate | `RenderFragment?` | null | The custom template for the label of the dropdown. | | LoadingTemplate | `RenderFragment?` | null | The custom template to render in the callout in place of the items while IsLoading is enabled. | | LoadingText | `string?` | null | The text to render in the callout in place of the items while IsLoading is enabled. Defaults to "Loading...". | | MaxDisplayedItems | `int?` | null | The maximum number of selected items rendered in the dropdown itself. Beyond it, the chips display collapses the extra ones into an overflow indicator and the text display switches to a summary. Zero or null renders every selected item. | | MaxHeight | `int?` | null | The maximum height of the scrollable item list of the callout in pixels. It is applied on top of the space the viewport leaves, so it can only ever make the list shorter. A value that is not greater than zero (and null) leaves the viewport alone to decide. | | MaxSelectedItems | `int?` | null | The maximum number of items that can be selected in multi select mode. A value that is not greater than zero (and null) means no limit. | | MaxSelectedItemsText | `string?` | null | The composite format of the message announced to screen readers once MaxSelectedItems is reached, which receives that limit, for example "Maximum of {0} items selected". Defaults to the English message. | | MinSearchLength | `int` | 0 | The number of characters the search text must reach before the items get filtered. While the search text is shorter, the full list is shown and no search is performed. | | MinSearchLengthText | `string?` | null | The composite format of the hint the callout shows while the typed text is still shorter than MinSearchLength, which receives the number of characters that are still missing, for example "Type {0} more characters to search". It is what tells the user that the list they are looking at is the full one rather than the result of what they typed, and it is announced to screen readers as well. Defaults to the English message; the hint is not shown at all while nothing has been typed, where the full list needs no explaining. | | MultiSelect | `bool` | false | Enables the multi select mode. | | MultiSelectDelimiter | `string` | , | The delimiter for joining the values to create the text of the dropdown in multi select mode. | | Name | `string?` | null | The name of the hidden native select element that mirrors the selection, so the value takes part in a plain HTML form post. It is intended for use with forms and is not displayed in the UI. | | NameSelectors | `BitDropdownNameSelectors<TItem, TValue>?` | null | Names and selectors of the custom input type properties. | | NoBorder | `bool` | false | Removes the border from the root element. | | NoResultsTemplate | `RenderFragment?` | null | The custom template to render in the callout when the current search has no result. Falls back to the EmptyTemplate when not set. | | NoResultsText | `string?` | null | The text to render in the callout when the current search has no result. Falls back to the EmptyText when not set. | | NoWrapNavigation | `bool` | false | Stops the arrow keys at the ends of the item list instead of letting them wrap around from the last item to the first one and back, which suits a long list where the wrap is more likely to read as the focus having been lost than as a deliberate jump. The type-ahead still wraps, since it looks for the item that matches rather than for the one that comes next. It has no effect in virtualize mode, where the ends of the rendered window are not the ends of the list and the focus stops at them either way. | | OnClear | `EventCallback` | | The callback that is called when the selection gets cleared, either by the clear button or by the Escape key when ClearOnEscape is enabled. | | OnClick | `EventCallback<MouseEventArgs>` | | The click callback for the dropdown. | | OnClose | `EventCallback` | | The callback that is called when the callout gets closed. | | OnDeselectItem | `EventCallback<TItem>` | | The callback that is called when a selected item gets unselected in multi select mode, by picking it again in the callout, by removing its chip, or through the UnselectItem method. Clearing the whole selection reports itself through OnClear instead. | | OnDynamicAdd | `EventCallback<TItem>` | | The callback that is called when a new item is on added Dynamic ComboBox mode. | | OnFocusIn | `EventCallback<FocusEventArgs>` | | The callback that is called when the dropdown (or any element inside it, like the ComboBox input) receives the focus. | | OnFocusOut | `EventCallback<FocusEventArgs>` | | The callback that is called when the dropdown (or any element inside it, like the ComboBox input) loses the focus. The callout is rendered outside the dropdown so that it can escape any clipping ancestor, so moving the focus into it (with the arrow keys, or by clicking the search box) counts as leaving the dropdown here. | | OnOpen | `EventCallback` | | The callback that is called when the callout gets opened. | | OnSearch | `EventCallback<string?>` | | The callback that is called when the search text of the search box or combo box input changes, with the term the items are getting filtered by. | | OnSelectItem | `EventCallback<TItem>` | | The callback that is called when an item gets picked in the callout. In multi select mode it reports every pick, including the one that unselects an already selected item; use OnDeselectItem to be told only about those. | | OnValuesChange | `EventCallback<IEnumerable<TValue?>>` | | The callback that is called when the selected items change. | | OpenOnFocus | `bool` | false | Opens the callout as soon as the dropdown receives the focus, so tabbing into it (or clicking any part of it) already shows the items without a further click or key press. | | Options | `RenderFragment?` | null | Alias of ChildContent. | | OverflowTextFormat | `string?` | null | The composite format of the overflow indicator that stands for the selected items beyond MaxDisplayedItems in the chips display, for example "+{0}". | | OverscanCount | `int` | 3 | Determines how many additional items are rendered before and after the visible region. | | Placeholder | `string?` | null | The placeholder text of the dropdown. | | PlaceholderTemplate | `RenderFragment<BitDropdown<TItem, TValue>>?` | null | The custom template for the placeholder of the dropdown. | | Prefix | `string?` | null | Prefix displayed before the dropdown contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the prefix. | | PrefixTemplate | `RenderFragment?` | null | Shows the custom prefix for dropdown. | | PreserveCalloutWidth | `bool` | false | Disables automatic setting of the callout width and preserves its original width. | | Reselectable | `bool` | false | Enables calling the select events when the same item is selected in single select mode. | | Responsive | `bool` | false | Enables the responsive mode of the component for small screens. | | ResponsiveCloseButtonAriaLabel | `string?` | null | The accessible name (and the tooltip) of the close button in the responsive mode callout. Defaults to the English message. | | ResponsiveCloseIcon | `BitIconInfo?` | null | The icon of the close button in the responsive mode callout. Takes precedence over ResponsiveCloseIconName when both are set. | | ResponsiveCloseIconName | `string?` | null | The icon name of the close button in the responsive mode callout from the Fluent UI icon set. | | SearchBoxAriaLabel | `string?` | null | The accessible name of the SearchBox input. Defaults to the English message. | | SearchBoxClearButtonAriaLabel | `string?` | null | The accessible name (and the tooltip) of the clear button of the SearchBox. Defaults to the English message. | | SearchBoxClearIcon | `BitIconInfo?` | null | The icon of the clear icon in the SearchBox. Takes precedence over SearchBoxClearIconName when both are set. | | SearchBoxClearIconName | `string?` | null | The icon name of the clear icon in the SearchBox from the Fluent UI icon set. | | SearchBoxIcon | `BitIconInfo?` | null | The icon of the search icon in the SearchBox. Takes precedence over SearchBoxIconName when both are set. | | SearchBoxIconName | `string?` | null | The icon name of the search icon in the SearchBox from the Fluent UI icon set. | | SearchBoxPlaceholder | `string?` | null | The placeholder text of the SearchBox input. | | SearchFunction | `Func<ICollection<TItem>, string, ICollection<TItem>>?` | null | Custom search function to be used in place of the default search algorithm. Takes precedence over SearchMode, which only configures the default algorithm. | | SearchIgnoreDiacritics | `bool` | false | Matches the search text against the item texts with the diacritics of both removed, so that "Jose" finds "José" and "Muller" finds "Müller". The item text itself is left untouched, and so is the part of it that HighlightSearch emphasizes. Ignored when a SearchFunction is provided, which does its own matching. | | SearchMode | `BitDropdownSearchMode` | BitDropdownSearchMode.Contains | Determines how the text of an item is matched against the search text by the default (case-insensitive) search algorithm. Ignored when a SearchFunction is provided. | | SearchResultsText | `string?` | null | The composite format of the message announced to screen readers with the number of items the current search produced, for example "{0} results available". Defaults to the English message. | | SelectAllText | `string?` | null | The text of the select all item in multi select mode. | | SelectedItemsTextFormat | `string?` | null | The composite format that replaces the joined item texts in the dropdown once more than MaxDisplayedItems items are selected, for example "{0} items selected". | | SelectTextOnFocus | `bool` | false | Selects the text already in the ComboBox input whenever it takes the focus, so that typing replaces the term that is there instead of appending to it - which is what a field the user comes back to in order to search for something else needs. It has no effect outside of the ComboBox mode, and none while the input is empty, where there is nothing to select. | | ShowClearButton | `bool` | false | Shows the clear button when an item is selected. | | ShowSearchBox | `bool` | false | Shows the SearchBox element in the callout. | | ShowSelectAll | `bool` | false | Shows the select all item in the callout in multi select mode. It has no effect when the items are provided by an ItemsProvider, since the items that are not loaded yet cannot be selected. | | Size | `BitSize?` | null | The size of the dropdown. | | StickyHeaders | `bool` | false | Keeps the header of a group pinned to the top of the item list while its items are scrolled past, so a long grouped list never leaves the user looking at items whose group has scrolled out of view. | | Styles | `BitDropdownClassStyles?` | null | Custom CSS styles for different parts of the BitDropdown. | | Suffix | `string?` | null | Suffix displayed after the dropdown contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the suffix. | | SuffixTemplate | `RenderFragment?` | null | Shows the custom suffix for dropdown. | | TextTemplate | `RenderFragment<BitDropdown<TItem, TValue>>?` | null | The custom template for the text of the dropdown, which replaces the selection it shows once something is selected. It has no effect with Chips enabled, where the selection is drawn as one chip per item and ChipTemplate is what renders each of them. | | ThrottleTime | `int` | 0 | The throttle time in milliseconds for the search and combo box inputs (applied when Immediate is enabled). | | Title | `string?` | null | The title to show when the mouse hovers over the dropdown. | | TokenSeparators | `char[]?` | null | The characters that split the text typed (or pasted) into the multi select ComboBox input into separate terms, each committed as its own selection exactly as typing it and pressing Enter would: a term naming an existing item selects it, and with Dynamic enabled a term naming none adds a new item. | | Transparent | `bool` | false | Removes the default background color from the root element. | | Underlined | `bool` | false | Renders the dropdown with only a bottom border in place of the box around it. | | ValueComparer | `IEqualityComparer<TValue>?` | null | Decides whether two values stand for the same selection, in place of the default equality of TValue. It governs every value comparison the component makes: which item a value selects, which selected item a chip removes, and whether a typed term is already selected. | | Values | `IEnumerable<TValue?>?` | null | The values of the selected items in multi select mode. (two-way bound) | | Virtualize | `bool` | false | Enables virtualization to render only the visible items. | | VirtualizePlaceholder | `RenderFragment<PlaceholderContext>?` | null | The template for items that have not yet been rendered in virtualization mode. | | DefaultValue | `TValue?` | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. | | DisplayName | `string?` | null | Gets or sets the display name for this field. | | InputHtmlAttributes | `IReadOnlyDictionary<string, object>?` | null | Gets or sets a collection of additional attributes that will be applied to the created element. | | Name | `string?` | null | Gets or sets the name of the element. Allows access by name from the associated form. | | NoValidate | `bool` | false | Disables the validation of the input. | | OnChange | `EventCallback<TValue?>` | | Callback for when the input value changes. | | ReadOnly | `bool` | false | Makes the input read-only. | | Required | `bool` | false | Makes the input required. | | Value | `TValue?` | null | Gets or sets the value of the input. This should be used with two-way binding. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | SelectedItems | `IReadOnlyList<TItem>` | | A readonly list of the current selected items in multi-select mode. | | SelectedItem | `TItem?` | | The current selected item in single-select mode. | | SelectItem | `Task SelectItem(TItem? item)` | | Selects the given item exactly as picking it in the callout would, so the same events fire and the same close and focus behavior follows. An item that is already selected is left alone: in multi select mode picking it again would unselect it, which UnselectItem is for. | | UnselectItem | `Task UnselectItem(TItem? item)` | | Unselects the given item exactly as picking an already selected one in the callout would (or, in single select mode, as the clear button would), so the same events fire. An item that is not selected is left alone. | | ClearAsync | `Task ClearAsync()` | | Clears the whole selection exactly as the clear button does, so the same events fire: it reports itself through OnClear and empties the typed text of the ComboBox mode along with the selection. It is refused in the same places that button is - a read-only dropdown, a one-way binding. | | RefreshItemsAsync | `Task RefreshItemsAsync()` | | Discards the items loaded so far and asks the ItemsProvider for them again, which is what makes a change outside of the dropdown (a filter of the page, a record added elsewhere) reach a list the dropdown only ever loads on demand. It does nothing without an ItemsProvider, where the Items collection is the source of truth and is re-read on its own. | | AssignIsOpen | `Task<bool> AssignIsOpen(bool value)` | | Opens or closes the callout programmatically, without having to bind the IsOpen parameter. It returns false when the change was refused, which is what a one-way bound IsOpen does. | | InputElement | `ElementReference` | | The ElementReference to the combobox element of the dropdown, which is the element the user focuses and operates the component with. | | FocusAsync | `ValueTask FocusAsync(bool preventScroll = false)` | | Gives focus to the combobox element of the dropdown. | | ComboInputElement | `ElementReference?` | | The ElementReference to the combo input element. | | FocusComboInputAsync | `ValueTask FocusComboInputAsync()` | | Gives focus to the combo input element. | | SearchInputElement | `ElementReference?` | | The ElementReference to the search input element. | | FocusSearchInputAsync | `ValueTask FocusSearchInputAsync()` | | Gives focus to the search input element. | | InputElement | `ElementReference` | | The ElementReference of the input element. | | FocusAsync() | `() => ValueTask` | | Gives focus to the input element. | | FocusAsync(bool preventScroll) | `(bool preventScroll) => ValueTask` | | Gives focus to the input element. | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitDropdownItemType Enum | Name | Value | Description | | :--- | :--- | :---------- | | Normal | 0 | Dropdown items are being rendered as a normal item. | | Header | 1 | Dropdown items are being rendered as a header, they cannot be selected. | | Divider | 2 | Dropdown items are being rendered as a divider, just draw a line. | ### BitDropdownSearchMode Enum | Name | Value | Description | | :--- | :--- | :---------- | | Contains | 0 | An item matches when its text contains the search text. | | StartsWith | 1 | An item matches when its text starts with the search text. | | EndsWith | 2 | An item matches when its text ends with the search text. | | ExactMatch | 3 | An item matches when its text is equal to the search text. | ### BitSize Enum | Name | Value | Description | | :--- | :--- | :---------- | | Small | 0 | The small size. | | Medium | 1 | The medium size. | | Large | 2 | The large size. | ### BitColor Enum | Name | Value | Description | | :--- | :--- | :---------- | | Primary | 0 | Primary general color. | | Secondary | 1 | Secondary general color. | | Tertiary | 2 | Tertiary general color. | | Info | 3 | Info general color. | | Success | 4 | Success general color. | | Warning | 5 | Warning general color. | | SevereWarning | 6 | SevereWarning general color. | | Error | 7 | Error general color. | | PrimaryBackground | 8 | Primary background color. | | SecondaryBackground | 9 | Secondary background color. | | TertiaryBackground | 10 | Tertiary background color. | | PrimaryForeground | 11 | Primary foreground color. | | SecondaryForeground | 12 | Secondary foreground color. | | TertiaryForeground | 13 | Tertiary foreground color. | | PrimaryBorder | 14 | Primary border color. | | SecondaryBorder | 15 | Secondary border color. | | TertiaryBorder | 16 | Tertiary border color. | ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Sub Classes ### BitDropdownItem<TValue> Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AriaLabel | `string?` | null | The aria label attribute for the dropdown item. | | Class | `string?` | null | Custom CSS class for the dropdown item. | | Id | `string?` | null | The id for the dropdown item. | | Icon | `BitIconInfo?` | null | The icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. | | IconName | `string?` | null | The icon name from the Fluent UI icon set. For external icon libraries, use Icon instead. | | Data | `object?` | null | The custom data for the dropdown item to provide state for the item template. | | IsEnabled | `bool` | true | Determines if the dropdown item is enabled. | | IsHidden | `bool` | false | Determines if the dropdown item is hidden. | | ItemType | `BitDropdownItemType` | BitDropdownItemType.Normal | The type of the dropdown item. | | Style | `string?` | null | Custom CSS style for the dropdown item. | | Text | `string?` | null | The text to render for the dropdown item. | | Title | `string?` | null | The title attribute for the dropdown item. | | Value | `TValue?` | null | The value of the dropdown item. | | IsSelected | `bool` | false | Determines if the item is selected. This property's value is assigned by the component. | ### BitDropdownOption<TValue> Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AriaLabel | `string?` | null | The aria label attribute for the dropdown option. | | Class | `string?` | null | Custom CSS class for the dropdown option. | | Id | `string?` | null | The id for the dropdown option. | | Data | `object?` | null | The custom data for the dropdown option to provide extra state for the template. | | IsEnabled | `bool` | true | Determines if the dropdown option is enabled. | | IsHidden | `bool` | false | Determines if the dropdown option is hidden. | | Icon | `BitIconInfo?` | null | The icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. | | IconName | `string?` | null | The icon name from the Fluent UI icon set. For external icon libraries, use Icon instead. | | ItemType | `BitDropdownItemType` | BitDropdownItemType.Normal | The type of the dropdown option. | | Style | `string?` | null | Custom CSS style for the dropdown option. | | Text | `string?` | null | The text to render for the dropdown option. | | Title | `string?` | null | The title attribute for the dropdown option. | | Value | `TValue?` | null | The value of the dropdown option. | | IsSelected | `bool` | false | Determines if the option is selected. This property's value is assigned by the component. | ### BitDropdownNameSelectors<TItem, TValue> Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AriaLabel | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.AriaLabel)) | The AriaLabel field name and selector of the custom input class. | | Class | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.Class)) | The CSS Class field name and selector of the custom input class. | | Id | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.Id)) | The Id field name and selector of the custom input class. | | Data | `BitNameSelectorPair<TItem, object?>` | new(nameof(BitDropdownItem<TValue>.Data)) | The Data field name and selector of the custom input class. | | IsEnabled | `BitNameSelectorPair<TItem, bool>` | new(nameof(BitDropdownItem<TValue>.IsEnabled)) | The IsEnabled field name and selector of the custom input class. | | IsHidden | `BitNameSelectorPair<TItem, bool>` | new(nameof(BitDropdownItem<TValue>.IsHidden)) | The IsHidden field name and selector of the custom input class. | | ItemType | `BitNameSelectorPair<TItem, BitDropdownItemType>` | new(nameof(BitDropdownItem<TValue>.ItemType)) | The ItemType field name and selector of the custom input class. | | Icon | `BitNameSelectorPair<TItem, BitIconInfo?>` | new(nameof(BitDropdownItem<TValue>.Icon)) | The Icon field name and selector of the custom input class. | | IconName | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.IconName)) | The IconName field name and selector of the custom input class. | | Style | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.Style)) | The CSS Style field name and selector of the custom input class. | | Text | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.Text)) | The Text field name and selector of the custom input class. | | Title | `BitNameSelectorPair<TItem, string?>` | new(nameof(BitDropdownItem<TValue>.Title)) | The Title field name and selector of the custom input class. | | Value | `BitNameSelectorPair<TItem, TValue?>` | new(nameof(BitDropdownItem<TValue>.Value)) | The Value field name and selector of the custom input class. | | TextSetter | `Action<string, TItem>?` | | The setter function for updating Text property of custom item in Dynamic ComboBox mode upon new item addition. | | ValueSetter | `Action<TItem, TItem>?` | | The setter function for updating Value property of custom item in Dynamic ComboBox mode upon new item addition. | | IsSelected | `string` | | The IsSelected field name of the custom input class. This property's value is assigned by the component. | ### BitNameSelectorPair<TItem, TProp> Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Name | `string` | | Custom class property name. | | Selector | `Func<TItem, TProp?>?` | | Custom class property selector. | ### BitIconInfo Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Name | `string?` | null | Gets or sets the name of the icon. | | BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. | | Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. | ### BitDropdownClassStyles Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Root | `string?` | null | Custom CSS classes/styles for the root element of the BitDropdown. | | Label | `string?` | null | Custom CSS classes/styles for the label of the BitDropdown. | | ErrorMessageContainer | `string?` | null | Custom CSS classes/styles for the error message container of the BitDropdown. | | ErrorMessage | `string?` | null | Custom CSS classes/styles for the error message of the BitDropdown. | | DescriptionContainer | `string?` | null | Custom CSS classes/styles for the description container of the BitDropdown. | | Description | `string?` | null | Custom CSS classes/styles for the description of the BitDropdown. | | Container | `string?` | null | Custom CSS classes/styles for the main container of the BitDropdown. | | TextContainer | `string?` | null | Custom CSS classes/styles for the text container of the BitDropdown. | | ClearButton | `string?` | null | Custom CSS classes/styles for the clear button of the BitDropdown. | | CaretDownIcon | `string?` | null | Custom CSS classes/styles for the caret down icon of the BitDropdown. | | Overlay | `string?` | null | Custom CSS classes/styles for the overlay of the BitDropdown. | | Callout | `string?` | null | Custom CSS classes/styles for the callout of the BitDropdown. | | CalloutHeader | `string?` | null | Custom CSS classes/styles for the container of the callout header template of the BitDropdown. | | CalloutFooter | `string?` | null | Custom CSS classes/styles for the container of the callout footer template of the BitDropdown. | | ResponsiveLabelContainer | `string?` | null | Custom CSS classes/styles for the responsive panel's label container of the BitDropdown. | | ResponsiveLabel | `string?` | null | Custom CSS classes/styles for the responsive panel label of the BitDropdown. | | ResponsiveCloseButton | `string?` | null | Custom CSS classes/styles for the responsive panel's close button of the BitDropdown. | | ResponsiveCloseIcon | `string?` | null | Custom CSS classes/styles for the responsive panel's close icon of the BitDropdown. | | SearchBoxContainer | `string?` | null | Custom CSS classes/styles for the search box container of the BitDropdown. | | SearchBoxIconContainer | `string?` | null | Custom CSS classes/styles for the search box's icon container of the BitDropdown. | | SearchBoxIcon | `string?` | null | Custom CSS classes/styles for the search box icon of the BitDropdown. | | SearchBoxInput | `string?` | null | Custom CSS classes/styles for the search box input of the BitDropdown. | | ComboBoxInput | `string?` | null | Custom CSS classes/styles for the ComboBox input of the BitDropdown. | | Chips | `string?` | null | Custom CSS classes/styles for the chips container of the BitDropdown. | | OverflowChip | `string?` | null | Custom CSS classes/styles for the overflow chip of the BitDropdown. | | ChipsRemoveButton | `string?` | null | Custom CSS classes/styles for the chips's remove button of the BitDropdown. | | ChipsRemoveIcon | `string?` | null | Custom CSS classes/styles for the chips's remove icon of the BitDropdown. | | SearchBoxClearButtonContainer | `string?` | null | Custom CSS classes/styles for the search box's clear button container of the BitDropdown. | | SearchBoxClearButton | `string?` | null | Custom CSS classes/styles for the search box's clear button of the BitDropdown. | | SearchBoxClearIcon | `string?` | null | Custom CSS classes/styles for the search box's clear icon of the BitDropdown. | | SearchHint | `string?` | null | Custom CSS classes/styles for the hint the callout shows while the typed text is still shorter than the MinSearchLength of the BitDropdown. | | SelectAllContainer | `string?` | null | Custom CSS classes/styles for the select all item container of the multi-select BitDropdown. | | SelectAllButton | `string?` | null | Custom CSS classes/styles for the select all item button of the multi-select BitDropdown. | | SelectAllCheckBox | `string?` | null | Custom CSS classes/styles for the select all item check box of the multi-select BitDropdown. | | SelectAllCheckIcon | `string?` | null | Custom CSS classes/styles for the select all item check icon of the multi-select BitDropdown. | | SelectAllText | `string?` | null | Custom CSS classes/styles for the select all item text of the multi-select BitDropdown. | | ScrollContainer | `string?` | null | Custom CSS classes/styles for the scroll container of the BitDropdown. | | ItemHeader | `string?` | null | Custom CSS classes/styles for the item header of the BitDropdown. | | ItemWrapper | `string?` | null | Custom CSS classes/styles for the item wrapper of the multi-select BitDropdown. | | ItemButton | `string?` | null | Custom CSS classes/styles for the item button of the BitDropdown. | | ItemCheckBox | `string?` | null | Custom CSS classes/styles for the item check box of the multi-select BitDropdown. | | ItemCheckIcon | `string?` | null | Custom CSS classes/styles for the item check icon of the multi-select BitDropdown. | | ItemIcon | `string?` | null | Custom CSS classes/styles for the item icon of the BitDropdown. | | ItemText | `string?` | null | Custom CSS classes/styles for the item text of the BitDropdown. | | ItemHighlight | `string?` | null | Custom CSS classes/styles for the highlighted part of the item text of the BitDropdown. | | ItemDivider | `string?` | null | Custom CSS classes/styles for the item divider of the BitDropdown. | | DynamicItem | `string?` | null | Custom CSS classes/styles for the row that offers to create a new item out of the typed text in the Dynamic ComboBox mode of the BitDropdown. | | EmptyContent | `string?` | null | Custom CSS classes/styles for the empty state content of the BitDropdown. | | LoadingContainer | `string?` | null | Custom CSS classes/styles for the loading state container of the BitDropdown. | | LoadingText | `string?` | null | Custom CSS classes/styles for the loading state text of the BitDropdown. | | Spinner | `string?` | null | Custom CSS classes/styles for the loading spinner of the BitDropdown. | | PrefixContainer | `string?` | null | Custom CSS classes/styles for the dropdown's prefix container. | | Prefix | `string?` | null | Custom CSS classes/styles for the dropdown's prefix. | | SuffixContainer | `string?` | null | Custom CSS classes/styles for the dropdown's suffix container. | | Suffix | `string?` | null | Custom CSS classes/styles for the dropdown's suffix. | | ResponsiveComboInputContainer | `string?` | null | Custom CSS classes/styles for the ComboBox input container in responsive mode of the BitDropdown. | | ResponsiveComboAddButton | `string?` | null | Custom CSS classes/styles for the add new item combo box button in responsive mode of the BitDropdown. | ## CSS Variables Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance. | Name | Default Value | Description | | :--- | :------------ | :---------- | | `--bit-Dropdown-background` | --bit-clr-bg-pri | Background of the field. Transparent turns the default into transparent; a value set here still wins over it. | | `--bit-Dropdown-color` | --bit-clr-fg-pri | Text of the field once something is selected, and of the text typed into the ComboBox input or the search box. | | `--bit-Dropdown-placeholder-color` | --bit-clr-fg-sec | Text of the field while nothing is selected, which is what the Placeholder is drawn in. | | `--bit-Dropdown-border-color` | --bit-clr-brd-pri | Border of the field at rest. Underlined draws it as the bottom rule alone, NoBorder drops it. | | `--bit-Dropdown-hover-border-color` | --bit-clr-brd-pri-hover | Border of the field while hovered (pointer devices only). | | `--bit-Dropdown-focus-color` | The Color role's focus color | Color of the focus indicator: the ring around the field, the underline of the Underlined and NoBorder variants, and the outline drawn inside the row the arrow keys have reached. | | `--bit-Dropdown-invalid-color` | --bit-clr-err, and --bit-clr-err-focus for the ring | Border and focus indicator while the value is rejected - by the EditContext, by Invalid or by an ErrorMessage - and the text of that message. | | `--bit-Dropdown-disabled-color` | --bit-clr-fg-dis | Text, label and glyphs when IsEnabled is false. | | `--bit-Dropdown-disabled-background` | --bit-clr-bg-dis | Background of the field when IsEnabled is false. | | `--bit-Dropdown-disabled-border-color` | --bit-clr-brd-dis | Border of the field when IsEnabled is false. | | `--bit-Dropdown-radius` | --bit-shp-radius-control | Corner radius of the field, which its background and its focus ring follow. | | `--bit-Dropdown-min-height` | Per Size: --bit-siz-ctrl-sm / -md / -lg | Smallest height of the field, which the search box, the clear button and the ComboBox add button follow. It is a floor, not a height: a Chips field still grows with the rows of chips in it. | | `--bit-Dropdown-font-size` | Per Size: --bit-tpg-fs-xs / -sm / -md | Text size of the field and of the search box. | | `--bit-Dropdown-icon-color` | --bit-clr-fg-sec | The caret, the clear button glyph and the add button glyph of the responsive ComboBox panel. The search glyph and the check mark take the accent instead, and the Prefix and Suffix addons their own colors. | | `--bit-Dropdown-icon-size` | Per Size: --bit-siz-icon-sm / -md / -lg | Size of every glyph of the component, including the ones in the search box and in the responsive panel. | | `--bit-Dropdown-prefix-color` | --bit-clr-fg-pri | Text of the Prefix addon. | | `--bit-Dropdown-prefix-background` | --bit-clr-bg-sec | Background of the Prefix addon. | | `--bit-Dropdown-suffix-color` | --bit-clr-fg-pri | Text of the Suffix addon. | | `--bit-Dropdown-suffix-background` | --bit-clr-bg-sec | Background of the Suffix addon. | | `--bit-Dropdown-accent-color` | The Color role's main color | The accent: group headers, the search glyph, the filled checkbox, the highlighted part of a matched item, the overflow chip, the spinner arc and the bar marking the item Enter would commit. | | `--bit-Dropdown-accent-hover-color` | --bit-Dropdown-accent-color, then the Color role's hover color | The accent while the part carrying it is hovered. | | `--bit-Dropdown-accent-text-color` | The Color role's on-color | Text and glyphs drawn ON the accent - the check mark, the highlighted text, the overflow chip. Set it along with the accent, or a custom accent keeps the contrast of the role it replaced. | | `--bit-Dropdown-label-color` | --bit-clr-fg-pri | Label text. | | `--bit-Dropdown-label-font-size` | --bit-Dropdown-font-size | Label text size. | | `--bit-Dropdown-label-font-weight` | --bit-tpg-fw-semibold | Label weight. | | `--bit-Dropdown-required-color` | --bit-clr-req | The asterisk a Required dropdown adds after its label. | | `--bit-Dropdown-description-color` | --bit-clr-fg-pri | Description text. It reaches the default rendering only, not a DescriptionTemplate. The ErrorMessage above it takes the invalid color instead. | | `--bit-Dropdown-description-font-size` | --bit-tpg-fs-2xs | Text size of the description and of the ErrorMessage. | | `--bit-Dropdown-chip-background` | --bit-clr-bg-sec | Background of a chip in the Chips display. The overflow chip takes the accent instead. | | `--bit-Dropdown-chip-color` | inherit | Text of a chip, which follows the field's own text color unless it is set. | | `--bit-Dropdown-chip-border-color` | --bit-clr-brd-sec | Border of a chip. | | `--bit-Dropdown-chip-radius` | --bit-shp-radius-chip | Corner radius of a chip and of its remove button. | | `--bit-Dropdown-callout-background` | --bit-clr-bg-pri | Background of the list surface, which the sticky group headers and the search box follow. | | `--bit-Dropdown-callout-radius` | --bit-shp-radius-popup | Corner radius of the list surface. | | `--bit-Dropdown-callout-shadow` | --bit-shd-popup | Elevation of the list surface. | | `--bit-Dropdown-responsive-width` | 272px | Width of the side panel a Responsive dropdown opens on a small screen. Capped at the width of the viewport. | | `--bit-Dropdown-overlay-background` | transparent | The layer between the page and an open callout. Give it a color for a modal-style scrim. | | `--bit-Dropdown-item-height` | Per Size: --bit-siz-item-sm / -md / -lg | Height of one row, which the group headers, the empty state and the loading row follow. Set ItemSize to the same number when Virtualize is on, since virtualization measures in pixels. | | `--bit-Dropdown-item-font-size` | Per Size: --bit-tpg-fs-xs / -sm / -md | Text size of one row, of a group header, and of the empty and loading states. | | `--bit-Dropdown-item-color` | --bit-clr-fg-pri | Text of one row. | | `--bit-Dropdown-item-hover-background` | --bit-clr-bg-pri-hover | Background of the hovered row, which is also what marks the item Enter would commit in the ComboBox mode. | | `--bit-Dropdown-item-selected-background` | --bit-clr-bg-sec | Background of a selected row. | | `--bit-Dropdown-item-selected-color` | --bit-Dropdown-item-color | Text of a selected row. Set it along with the background above whenever that one is repainted with something the row text was not chosen against. | | `--bit-Dropdown-item-disabled-color` | --bit-clr-fg-dis | Text of a row that cannot be picked - a disabled item, and every unselected item once MaxSelectedItems is reached. | | `--bit-Dropdown-header-color` | --bit-Dropdown-accent-color | Text of a group header, for a list whose headers should read quieter than the accent. | | `--bit-Dropdown-divider-color` | --bit-clr-bg-sec | The rule a Divider item draws between two groups, and the one under the select all row. The two differ in their defaults only (--bit-clr-bg-sec for the filled rule, --bit-clr-brd-sec for the border). | ## Examples