Dropdown

BitDropdown in its simplest forms: single and multi select dropdowns, a required one (which marks its label and reports itself as required to assistive technologies), one preserving its original callout width instead of matching the width of the dropdown, and a custom delimiter for joining the selected values in multi select mode. A disabled dropdown cannot be focused or opened at all, while a read-only one stays focusable and its callout can still be browsed — only changing the selection is blocked, and every control that would change it (the clear button, the chip remove buttons) is hidden accordingly. The Title parameter adds the tooltip shown while the pointer rests on the dropdown. Clicking the Label moves the focus to the dropdown, and the Name parameter names the hidden native select that mirrors the selection, so the value also travels in a plain HTML form post.

The ItemType of an item decides what it is in the list: a Normal item is a selectable option, a Header item names the items that follow it, and a Divider item draws a line between them without ending the group. Headers and dividers are not options, so they are skipped by the keyboard navigation and the typeahead, they are never matched by a search, and the select all item ignores them. The grouping is not only visual: every option points at the header that names it, so a screen reader reads "Broccoli, option, 7 of 18, Vegetables" instead of leaving the user to infer the group from a heading they cannot see. Headers without an Id of their own are given a generated one for that purpose. The StickyHeaders parameter pins the header of a group to the top of the list while its items are scrolled past, so a long grouped list never leaves the user looking at items whose group has scrolled away.

The grouping survives a search: the headers of the groups that still have a match stay above them, and only the ones left naming nothing — along with a divider that lost the items on one of its sides — go with the items they framed. A result that arrived as a flat list would take the grouping away exactly when the list is hardest to read, so the third example below keeps it while filtering.

The Prefix and Suffix parameters put fixed text before and after the selected value — a unit, a currency, a category — and PrefixTemplate and SuffixTemplate replace them with any content, an icon for instance. They are decoration only: they are not part of the value and are not read out with it, so keep a descriptive Label for screen reader users.

The FitWidth parameter makes the dropdown only as wide as its content instead of stretching to the full width of its container, which suits toolbars and inline filters where a full-width control would look out of place. The callout still matches the width of the dropdown unless PreserveCalloutWidth is set.

Three parameters change how much furniture the dropdown draws around itself. NoBorder removes its border entirely, Underlined replaces the box with a single bottom border — the variant that suits a dense form where a box per field would be too much — and Transparent removes the background, so the control can sit on a colored or image surface without cutting a rectangle out of it. They are independent and combine freely; the callout keeps its own surface either way, so the items stay readable. Since the two borderless variants have no box to draw a focus ring around, the keyboard focus (and the invalid state) is shown as an underline instead, which keeps the cue visible without inventing a border that the variant exists to remove.

When the Responsive parameter is true, the callout turns into a side panel on small screens instead of a floating list, making long item lists easier to use on mobile devices. The panel carries the label of the dropdown and a close button, and it can also be dismissed by swiping it away. Resize the window below the small breakpoint to see it.

The DropDirection parameter determines which directions the callout is allowed to open in. All picks whichever side fits best in the viewport, while TopAndBottom (the default) restricts it to opening above or below the dropdown. In both cases the callout flips to the opposite side when there is not enough room, and its item list is capped to the space that is actually available, so it never runs past the edge of the screen. Scroll the page so that these dropdowns sit near the top or the bottom of the viewport to see it.

MaxHeight caps the scrollable item list at a height of your own, in pixels, so a long list stays a modest panel instead of stretching to whatever the viewport allows. It is applied on top of that available space rather than in place of it, so it can only ever make the list shorter — a dropdown near the bottom of the window is still limited by the room it actually has. Note that this is the one size a stylesheet cannot reach: the height is measured and written as an inline style every time the callout opens, so a CSS rule would always lose to it.

The ShowClearButton parameter adds a button that clears the current selection whenever the dropdown has a value, in both single and multi select modes. Clearing raises the usual value change events, plus the dedicated OnClear callback. In the ComboBox mode it also empties the input, so no filter is left behind by a button that says it clears what the dropdown is showing. The button is hidden while the dropdown is read-only or disabled, so it never offers an action that would be ignored.

ClearOnEscape gives the same clear to the keyboard, so taking back a selection does not require finding a button with the mouse. Escape stays a dismiss key first: it closes the callout, and in the ComboBox mode it drops the text that was typed into it, and only a press with nothing left to dismiss reaches the selection. It goes through the very same clear as the button, so it raises OnClear and is refused wherever the button would be — and it needs no ShowClearButton, so a dropdown that shows no clear button can still be cleared this way.

The ShowSearchBox parameter adds a search input at the top of the callout to filter the items, and SearchBoxPlaceholder sets its placeholder. By default an item matches when its text contains the typed term, ignoring case; SearchFunction replaces that algorithm with any predicate of your own (the examples below switch it to a starts-with and an ends-with match). AutoFocusSearchBox puts the caret in the search input as soon as the callout opens - with the pointer and with Enter or Space on the keyboard alike - so typing filters right away. A clear button appears in the search input as soon as there is something to clear, which follows the text being typed rather than the term that has been applied: a search waiting to be committed (or held back by a debounce) can be taken back the moment it is typed. The search term is discarded whenever the callout closes, so the next opening always starts from the full list.

A handful of parameters tune the default search without replacing it. SearchMode picks how the text of an item is matched against the typed term — Contains (the default), StartsWith, EndsWith or ExactMatch, always ignoring case. MinSearchLength holds the filtering back until the term reaches the given number of characters, which keeps a one-letter term from being treated as a real query (and, with an ItemsProvider, from turning every first keystroke into a request). While the term is still too short the callout shows a hint above the items saying how many characters are missing, so the untouched list under it reads as the full list instead of as a search that matched everything; MinSearchLengthText is the composite format of that hint, which receives the number of characters that are still needed and is announced to screen readers along with it. SearchIgnoreDiacritics matches the term against the item texts with the diacritics of both folded away, so Jose finds José and Muller finds Müller — which is what makes the search usable to anyone typing on a keyboard that has no accented keys. HighlightSearch emphasizes the matched part of each item text so the reason an item is in the result is visible at a glance, and it keeps lining up with the accented text because the folding replaces each character with exactly one character. Whenever a search is active the number of results is also announced to screen readers, with a message you can localize through the SearchResultsText parameter; that count follows the list as it is actually rendered, so the items HideSelectedItems takes out of it are not offered as results nobody can reach. All of them configure the built-in algorithm only; a SearchFunction replaces it outright and does its own matching.

By default the search box raises its search when the input is committed (on the change event). Enabling Immediate makes it search as you type (on the input event) instead. Because that can mean a request per keystroke with a remote data source, the immediate search can be rate-limited: DebounceTime waits until the typing pauses for the given number of milliseconds and then searches once, while ThrottleTime lets at most one search through per interval while the typing continues. The OnSearch event reports every search term that gets through. The ComboBox input is a different story: it is a text field whose whole purpose is to filter the list as it is typed, so it always searches on every keystroke and Immediate only decides there whether the two rate limits apply to it.

BitDropdown is a regular form input: inside an EditForm it takes part in data annotations validation, turns red and reports itself as invalid to assistive technologies when its field has an error, and renders a ValidationMessage like any other input. This example requires a value in the single select dropdown and keeps the number of selected items of the multi select one within a range.

Nearly every part of the dropdown can be replaced with your own content. ItemTemplate and HeaderTemplate render the normal items and the group headers of the callout, TextTemplate renders the selected value shown on the closed dropdown and PlaceholderTemplate what is shown while nothing is selected, LabelTemplate replaces the label, CaretDownIconName and CaretDownTemplate the chevron, and CalloutHeaderTemplate and CalloutFooterTemplate add fixed content above and below the scrollable item list — the footer being the usual home of an "add a new item" action. The templates that render an item receive the item itself, so the extra state carried in its Data property is available to them.

Every piece of the dropdown's state can be bound or observed. The selection is two-way bound over Value in single select mode and Values in multi select mode, or left uncontrolled with DefaultValue and DefaultValues and observed through the OnChange and OnValuesChange events; OnSelectItem hands over the clicked item itself rather than its value — in multi select mode for every pick, including the one that unselects an already selected item, which OnDeselectItem reports on its own so that an addition and a removal can be told apart. Reselectable makes the select events fire even when the already selected item is picked again, which is otherwise treated as a no-op. The open state of the callout is two-way bound via IsOpen, so it can be opened and closed from code, and the OnOpen and OnClose events report every change to it — a natural place to start fetching the items on first open.

ValueComparer decides whether two values stand for the same selection, in place of the default equality of the value type. That is what a value which is not its own identity needs: a record or a class used as the value compares by reference by default, so a value arriving from a form, a query string or a fresh fetch would never match the item it names, however equal the two look. The example below uses a case-insensitive comparer, so the value F-APP selects the item whose value is f-app. The comparer governs every value comparison the component makes — which item a value selects, which chip a removal takes away, whether a typed term is already selected — so two values it calls equal are one and the same selection throughout. Finally, OnFocusIn and OnFocusOut follow the focus of the dropdown as a whole: they sit on the trigger and focusin/focusout bubble, so moving between the trigger and the ComboBox input inside it does not report a round trip through the outside.

The Combo parameter turns the dropdown into a ComboBox: an editable input renders in place of the selected text and filters the items as you type, so the trigger doubles as the search box. Enter selects the item whose text matches what was typed, Backspace on an empty input removes the last selected item, the arrow keys — and typing itself, which reveals the list it filters — open the callout, Escape abandons the typed term, and a term that was typed but never turned into a selection is discarded when the callout closes, so the input goes back to showing the current selection.

Requiring the typed text to match an item exactly makes Enter a dead key for anyone who only typed the beginning of a name, so AutoSelectFirstMatch lets a partial term stand for the first item it matches: typing ban and pressing Enter then selects Banana. It takes precedence over the Dynamic mode below, so a term that names an item the list already has selects that item instead of creating a second one beside it.

Whichever item a commit would take — the one the typed text names exactly, or the first one it still matches under AutoSelectFirstMatch — is marked in the list as you type, so what Enter is about to select is visible before it is pressed rather than only afterwards. The same item is named to a screen reader through the aria-activedescendant of the input, so the cue is not a visual-only one. When nothing is marked, Enter either creates a new item (with Dynamic) or does nothing at all.

SelectTextOnFocus selects whatever is already in the input when it takes the focus, so coming back to a combo box that holds a term and typing replaces that term instead of appending to it — which is what a field the user returns to in order to look for something else needs. An empty input has nothing to select, and neither has a read-only one, where the selection would only be a highlight over text that cannot be changed.

When the Chips parameter is true, the selected items render as chips inside the dropdown instead of one joined text, each with its own remove button that is reachable with the keyboard and announced with the text of the item it removes. It works in both single and multi select modes and pairs naturally with the ComboBox mode.

ChipTemplate draws the content of a chip from the item it stands for, which is what turns a bare list of names into avatars, icons or colored categories. It replaces the text only: the remove button is still rendered after it, so a chip stays removable however it is drawn.

A multi select dropdown that lists every selected item quickly runs out of room. MaxDisplayedItems caps how many of them the closed dropdown shows: with Chips the extra ones collapse into an overflow chip whose text comes from OverflowTextFormat ("+{0}" by default), and without chips the joined list is replaced by the summary of SelectedItemsTextFormat ("{0} items selected" by default) as soon as the limit is passed. Nothing is removed from the selection — only the way it is displayed changes.

AutoClearSearch covers the other half of a multi select session: the callout stays open after a pick, so by default the next item has to be found through the filter left over from the previous one. Enabling it clears the search text after every selection instead. HideSelectedItems goes one step further and drops the picked items out of the callout altogether, which makes sense when the chips already show what is selected and the list is only about what is left to choose. A group header whose items have all been picked goes with them, and so does a divider that lost the items on one of its sides, so the list never opens with a stray rule or ends on a group name with nothing under it.

Across all of them the selection is reported in the order it was made rather than in the order of the item list: the chips, the joined text and the overflow summary follow the order of Values, which grows as the user picks, so the Backspace of the ComboBox removes the chip that was added last.

When the Dynamic parameter is true, a text typed into the ComboBox that matches no existing item can be added as a new one, which is what makes free-form values (tags, e-mail recipients, ad-hoc categories) possible. DynamicValueGenerator produces the value of the new item from its text and OnDynamicAdd notifies about the addition so the item can be persisted into the source collection — and only about an addition that stands, so a term refused by the selection limit or by a one-way binding is never reported as one. Before creating anything the component first looks for an existing match; FindItemFunction and ExistsSelectedItemFunction replace the default case-insensitive text comparison used for those two lookups, and AutoSelectFirstMatch gets its turn between them and the creation, so a partially typed term that names an existing item selects it instead of creating a near-duplicate. While the typed text names nothing the list offers to create an item out of it as its first row, so adding one is something to see and click rather than a shortcut to know about; the row is what the enter key would take, it is reached with the arrow keys like any other option, and it disappears the moment the text names something the list already holds.

Combining the Combo, Chips and Dynamic parameters, new items get added by pressing the enter key (or the add button of the responsive panel on mobile) and render as removable chips.

DynamicItemTextFormat is the wording of that offer, which receives the text the item would be created from, and DynamicItemTemplate replaces it with markup of your own when a plain sentence is not enough. Type a name no fruit or vegetable has and the list says so in its own words.

The dropdown is fully operable with the keyboard, following the ARIA authoring practices for a combobox: Enter, Space and the arrow keys open the callout and put the focus on the selected item (or the first one), ArrowUp and ArrowDown move between the items, Home and End jump to the first and the last one — from the closed dropdown too, so reaching the end of a long list never takes an opening key followed by a second one — PageUp and PageDown jump several items at a time, Enter and Space select the focused item, Escape and Alt+ArrowUp close the callout and return the focus to the dropdown, and Tab closes it and moves on — from the trigger just as much as from inside the callout, so a popup revealed without the focus is never left behind when the focus leaves the dropdown. Alt+ArrowDown is the exception among the openers: it reveals the list without moving the focus into it, so the trigger keeps it and the plain arrows can walk the list afterwards. Opening the callout with a mouse click focuses the selected item as well, so the keyboard can take over at any point. In multi select mode Ctrl+A (or Cmd+A) selects every item the current search shows — or clears them when they are all selected already — while inside the search and ComboBox inputs the shortcut keeps its native select-the-text behavior. Typing printable characters runs a typeahead: the accumulated characters jump to the item starting with them, repeating one character cycles through the items starting with it, and the buffer resets after a short pause. The arrow keys wrap around by default, so ArrowDown on the last item comes back to the first one; NoWrapNavigation stops them at the ends instead, which suits a long list where the jump from one end to the other is more likely to read as the focus having been lost than as a move that was asked for — the typeahead keeps wrapping either way, since it looks for the item that matches rather than for the one that comes next. Disabled and hidden items are skipped throughout. In virtualize mode only the rendered items take part in the typeahead, since the ones that have not been rendered yet have no text to match against. The options themselves stay out of the tab order, as the options of a listbox should: they are reached with the arrow keys, and Tab leaves the whole dropdown rather than walking through the list. In ComboBox mode the keys that belong to the typed text — the printable characters, Backspace, Delete, ArrowLeft and ArrowRight — return the focus to the input and act on it there, so arrowing into the list never strands the user away from the term they are typing. However the callout is dismissed — a key, a click outside it, the close button of the responsive panel or a swipe — the focus comes back to the dropdown (to the ComboBox input when there is one) instead of being dropped at the top of the page along with the element that was holding it. ClearOnEscape gives Escape one more job once it has nothing left to dismiss: a press with the callout already closed (and, in the ComboBox mode, with nothing typed) clears the selection, which is what a keyboard user otherwise has to reach the clear button for. See the Clear button section.

When the ShowSelectAll parameter is true, a select all item renders above the item list of a multi select dropdown. It selects everything with one click and clears everything with the next, and its check box shows an indeterminate state while only some of the items are selected, so it doubles as a summary of the current selection. It only ever applies to what the user can actually see: disabled items are skipped, and while a search is active it selects the search result rather than the whole list, leaving selections made outside the result untouched. The SelectAllText parameter customizes its text. It is not available when the items come from an ItemsProvider, since the items that are not loaded yet cannot be selected. It also honors MaxSelectedItems: it stops at the limit, and once there is no room left it clears the selection instead of doing nothing. It also goes away when there is nothing left for it to select — an empty list, or a search that matched nothing — instead of topping the empty state with a control that cannot do anything. While the callout is open, the Ctrl+A (or Cmd+A) shortcut toggles the same select all behavior from the keyboard, even when the select all item itself is not shown.

The MaxSelectedItems parameter limits how many items can be selected in the multi select dropdown. Once the limit is reached the unselected items are disabled rather than silently refusing the click, so the boundary is visible before it is hit, and they become available again as soon as an item is unselected. The select all item honors the same limit and stops adding items once it is reached — and since it can then never reach "all selected", the next click on it clears the selection instead of leaving the user with a control that does nothing. The items turning unavailable is a change only a sighted user notices, so reaching the limit is also announced to screen readers, with a message you can localize through MaxSelectedItemsText — and the announcement goes quiet again as soon as unselecting an item makes room.

When there is no item to show, the callout renders a message instead of an empty list. There are two distinct cases and each gets its own text: EmptyText and EmptyTemplate cover a list that has nothing in it ("No items found" by default), while NoResultsText and NoResultsTemplate cover a search that matched nothing ("No results found" by default) — telling the user that their term found nothing is a different message from telling them the list is empty. When the no-results pair is not set the empty pair is used for both cases.

The IsLoading parameter reports that the items are still on their way: a spinner replaces the caret down element and the callout shows a loading indicator in place of the item list, while the dropdown itself stays enabled so the user can still open it and see what is happening. The message is customized with the LoadingText parameter and the whole indicator with the LoadingTemplate parameter.

The Virtualize parameter renders only the items that are currently visible instead of the whole list, which keeps the callout fast with thousands of items; ItemSize tells it how tall an item is and OverscanCount how many extra items to keep rendered around the visible window. It works over a local Items collection, or over an ItemsProvider that fetches one page at a time from a server (and receives the current search term, so filtering happens remotely too). ItemsProviderDebounceTime (100ms by default) collapses the burst of requests that fast scrolling and typing produce into a single one, so the provider is not asked once per rendered frame. Because a value can be selected before the page holding its item has ever been fetched, InitialSelectedItems supplies those items up front so the dropdown can show their text right away. The VirtualizePlaceholder template fills the rows that are still being fetched. Opening a virtualized dropdown still lands on what is currently selected, even when that item sits thousands of rows down and has never been rendered: the list is scrolled to where its index says it is and the selection is centred in the window, the way a native select behaves. That needs an index to scroll to, so it applies to a local Items collection; with an ItemsProvider the loaded window is all the component has. Each option still reports where it sits in the whole set — the provider says how many items there are and which window it is handing over — so a screen reader announces "Item 4210 of 10,000" in a list that has never been loaded in full.

Every piece of text the dropdown produces on its own is a parameter, so nothing has to stay in English in a localized app. Placeholder, Label and SearchBoxPlaceholder cover what is always visible; SelectAllText, EmptyText, NoResultsText and LoadingText cover the states of the callout; and the composite formats SelectedItemsTextFormat, OverflowTextFormat, SearchResultsText and MaxSelectedItemsText cover the texts built from a count, each receiving that count as {0}. The strings only a screen reader ever reads are parameters too, so a localized dropdown does not fall back to English the moment it is used without sight: ChipsRemoveButtonAriaLabel (a composite format that receives the text of the item its chip stands for), ClearButtonAriaLabel, SearchBoxAriaLabel, SearchBoxClearButtonAriaLabel, ResponsiveCloseButtonAriaLabel and ComboBoxAddButtonAriaLabel.

Every icon the dropdown draws on its own comes from the built-in Fluent UI set and can be swapped by name: CaretDownIconName for the chevron, ClearButtonIconName for the clear button, ItemCheckIconName for the check mark of the multi select items and of the select all row, SearchBoxIconName and SearchBoxClearIconName for the two icons of the search box, ChipsRemoveIconName for the remove button of a chip, and ResponsiveCloseIconName and ComboBoxAddButtonIconName for the close and add buttons that only the responsive panel shows. Each of them has an ...Icon counterpart that takes a BitIconInfo and wins when both are set, which is how an icon from outside the Fluent set gets in — see the External Icons section below. None of them is ever read out on its own: the icons are hidden from assistive technologies and the button around them carries the accessible name, which is why those names are parameters of their own.

Each mode dismisses the callout the way its interaction expects: a single select dropdown closes on the pick, because that pick is the whole interaction, while a multi select one stays open so the next item can be chosen without reopening the list. CloseOnSelect overrides that decision in both directions. Set it to false on a single select dropdown to keep the list open while the user tries one option after another against the page behind it, or to true on a multi select one to turn every pick into a complete interaction of its own — useful when each selection triggers work that the user should see before choosing again.

Whichever way it goes, the focus follows: a callout that closes hands the focus back to the dropdown (or to its ComboBox input), so the keyboard is never left stranded on an element that has just been removed from the page, while a callout that stays open keeps the focus on the option that was picked, ready for the next arrow key.

The TokenSeparators parameter turns the listed characters into term endings for the multi select ComboBox input: typing one commits the term before it exactly as pressing Enter would, and pasting a whole delimited list commits every term it contains in one go. A term that names an existing item selects that item, and — with Dynamic enabled — a term that names none becomes a new item, so a list copied out of a spreadsheet or an e-mail turns into a selection without being retyped item by item. A term the selection already covers is refused, so committing the same list twice does not duplicate anything.

The OpenOnFocus parameter opens the callout the moment 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 — one interaction fewer in a form that is filled top to bottom. The component tells a focus move made by the user apart from one made by its own focus management: a dismissal that returns the focus to the dropdown (Escape, a pick that closes the callout) does not reopen what was just closed.

The Description parameter renders a line of helper text under the dropdown — the place for the rule that the label has no room for ("only the categories you have access to", "leave empty for all regions"). It is not decoration: the dropdown points at it with aria-describedby, so a screen reader reads it along with the control instead of leaving it as text that merely happens to sit underneath. In the ComboBox mode the editable input is described by it as well, since that is the element the user is actually typing into. DescriptionTemplate replaces it with any content — a link, an icon, a warning that changes with the selection — and is tied to the dropdown in exactly the same way.

The Color parameter paints the accents of the dropdown — the focus border, the search box underline and icon, the group headers and the check boxes of the multi select items — in one of the theme colors, Primary being the default. It changes the accents only, not the surface of the control, so the dropdown keeps fitting its surroundings.

Every icon of the dropdown can come from an external library instead of the built-in Fluent UI set. The CaretDownIcon, ClearButtonIcon, ChipsRemoveIcon, SearchBoxIcon, SearchBoxClearIcon, ResponsiveCloseIcon and ItemCheckIcon parameters take a BitIconInfo — built with BitIconInfo.Fa, BitIconInfo.Bi or the generic BitIconInfo.Css — and each takes precedence over its ...IconName counterpart when both are set. The items themselves follow the same rule through their Icon and IconName members. Remember to reference the stylesheet of the icon library you use.

The Size parameter scales the whole component in one step, Medium being the default: the height and the font size of the dropdown, of its search box and of the items in the callout all follow the chosen size.

The dropdown can be styled at every level: Style and Class apply to the root element, each item carries its own style and class, and the Styles and Classes parameters reach every internal part of the component individually — the label, the container, the callout, the search box, the scroll container, the items and everything else listed in the class-styles reference below. Because the callout is rendered outside the root element, styling it through Styles.Callout or Classes.Callout is the way to reach it rather than a descendant selector on the root.