# Dropdown **Also known as:** Select, MultiSelect, ComboBox ## Description A dropdown is a list in which the selected item is always visible while other items are visible on demand by clicking a dropdown button. Dropdowns are typically used for forms. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AutoFocusSearchBox | `bool` | false | Enables auto-focusing of the SearchBox input when the callout is open. | | 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. | | 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. | | Classes | `BitDropdownClassStyles?` | null | Custom CSS classes for different parts of the BitDropdown. | | Color | `BitColor?` | null | The general color of the dropdown. | | 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. | | Combo | `bool` | false | Activates the ComboBox feature in BitDropDown component. | | 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<string?>?` | 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). | | 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. | | DynamicValueGenerator | `Func<TItem?, TValue>?` | null | The function for generating value in a custom item when a new item is on added Dynamic ComboBox mode. | | ExistsSelectedItemFunction | `Func<ICollection<TItem>, string, bool>` | | Custom search function to be used in place of the default search algorithm for checking existing an item in selected items in the ComboBox mode. | | FindItemFunction | `Func<ICollection<TItem>, string, TItem>` | | Custom search function to be used in place of the default search algorithm for checking existing an item in items in the ComboBox mode. | | 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. | | 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 immediately as the user types in the search box or combo box input (based on the 'oninput' HTML event). | | 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. | | 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. | | 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. | | NameSelectors | `BitDropdownNameSelectors<TItem, TValue>?` | null | Names and selectors of the custom input type properties. | | NoBorder | `bool` | false | Removes the border from the root element. | | OnClick | `EventCallback<MouseEventArgs>` | | The click callback for the dropdown. | | OnDynamicAdd | `EventCallback<string>` | | The callback that is called when a new item is on added Dynamic ComboBox mode. | | OnSearch | `EventCallback<string>` | | The callback that is called when the search value changes. | | OnSelectItem | `EventCallback<TItem>` | | The callback that called when an item gets selected. | | OnValuesChange | `EventCallback<IEnumerable<TValue?>>` | | The callback that called when selected items change. | | Options | `RenderFragment?` | null | Alias of ChildContent. | | 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. | | 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. | | 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. | | ShowClearButton | `bool` | false | Shows the clear button when an item is selected. | | ShowSearchBox | `bool` | false | Shows the SearchBox element in the callout. | | 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<<TItem, TValue>>?` | null | The custom template for the text of the dropdown. | | 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. | | Transparent | `bool` | false | Removes the default background color from the root element. | | 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. | | ComboInputElement | `ElementReference` | | The ElementReference to the combo input element. | | FocusComboInputAsync | `ValueTask` | | Gives focus to the combo input element. | | SearchInputElement | `ElementReference` | | The ElementReference to the search input element. | | FocusSearchInputAsync | `ValueTask` | | 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. | ### 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` | null | Determines if the dropdown item is enabled. | | IsHidden | `bool` | null | 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` | string.Empty | 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` | null | Determines if the dropdown option is enabled. | | IsHidden | `bool` | null | Determines if the dropdown option is hidden. | | IsSelected | `bool` | null | Determines if the dropdown option is selected. | | 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` | string.Empty | 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. | | 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. | | 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. | | 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. | | 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. | | ItemDivider | `string?` | null | Custom CSS classes/styles for the item divider of the BitDropdown. | ## Examples