Skip to content
BlazorUI

Navs

DropMenu

Bit.BlazorUI

DropMenu is a button that opens a callout hosting any content: an action list, a form, a filter panel, or a navigation menu. The callout is anchored to the button, flips to the side with the most room, closes on an outside click or Escape, and becomes a swipeable panel on small screens. It opens on click or hover, keeps the keyboard where it belongs, and its button comes in every color, variant and size of the library.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Text labels the button and the content becomes the body of the callout. Disabled turns the whole drop menu off, and FullWidth stretches the button to the available width.



Icons

IconName adds a leading icon and ChevronDownIconName swaps the trailing chevron, which flips while the callout is open; NoChevron removes it. A button holding only an icon is squared off to the control height - give it an AriaLabel, since it has no text to be named by.

Template

Template replaces everything inside the button, so the trigger can be anything. The callout content then goes into Body, an alias of ChildContent.

Variant

Variant decides how the Color is painted: Fill (the default) is a solid surface, Outline a border and a colored label, Text the label alone. Transparent drops the surface of the button in every state, whatever the variant.

Variant

Loading & lazy content

IsLoading swaps the icon for a spinner, closes an open callout and keeps it from opening until the content is ready. The button keeps the focus and is announced as busy and unavailable. LazyRender keeps the content out of the page until the first opening - worth it for heavy content or a drop menu repeated down a list - and keeps it afterwards, so its state survives a close.


Callout appearance

Background and Border paint the callout with a color kind, and NoShadow flattens it - a border usually replaces the shadow. A Transparent background suits content that paints its own.

Background

Border

Sizing the callout

The callout is as large as its content by default. Width, MinWidth and MaxWidth take any CSS length, and MatchWidth makes it at least as wide as the button (winning over Width). MaxHeight caps the height and scrolls the rest; without it the callout is capped to the room the viewport leaves, so tall content never ends up out of reach.


Placement

The callout opens on the side with the most room. DropDirection TopAndBottom (the default) only ever drops it above or below, while All also allows the sides - scroll until the long menu below fits neither above nor below its button to see it move beside it.

DropDirection



Alignment lines the callout up with the Start (the default), the Center or the End of the button - End keeps the menu of a button at the end of a toolbar under that button.

Alignment



Placement asks for a side of the button - Top for a menu in a bottom bar, End for one in a side bar - and falls back to the opposite side when the callout does not fit there. Gap spaces the callout off the button, in pixels.

Placement

Responsive

With Responsive, the callout becomes a panel on screens under 600px that slides in from PanelPlacement and is swiped away along the same axis. ScrollContainerId names the scrollable part of the content, so the swipe does not fight its scrolling. Narrow the window to try it.

PanelPlacement

Open on hover

OpenOnHover opens the callout when the pointer arrives and closes it once the pointer leaves both the button and the callout. HoverOpenDelay ignores a pointer only passing by, and HoverCloseDelay (150ms) bridges the gap between the two. Escape closes a callout opened by hovering wherever the focus is. Touch screens and the keyboard keep the click behavior.

Binding

IsOpen is two-way bindable; DefaultIsOpen only sets the starting state. The Open, Close and Toggle methods do the same through a component reference.




Events

OnClick fires on every activation of the button, OnOpen when the callout opens and OnDismiss when it closes, however that happens.


Clicked: 0, Opened: 0, Dismissed: 0

Auto close

AutoClose closes the callout as soon as a click lands inside it, as an action list should. It is off by default, so a form or a filter panel stays open while it is used.

Accessibility

The button announces the dialog it opens and the callout is a dialog named by the button. Enter, Space and the arrow keys open it and move the focus in; Escape closes the innermost popup first - the dropdown below closes its list, not the form - and returns the focus. Tab past the last element closes the callout and carries on after the button; Shift+Tab from the first goes back to it, and Tab from the button goes back in.

AutoFocus moves the focus in on every opening. TrapFocus keeps Tab cycling inside and makes the callout a modal dialog, which suits a form. AriaLabel names an icon-only button, AriaDescription adds a description, and AriaHidden hides the button from assistive technologies. In forced colors (Windows High Contrast) the open, loading and disabled states keep showing in system colors.

Narrows the list below

Cascading parameters

BitParams cascades a BitDropMenuParams to every BitDropMenu inside it, so a toolbar sets its shared parameters once. Only the properties you set travel, and a value written on a drop menu itself always wins - which is why the last one keeps its own Fill variant. The open state, the content and the events are not part of it: they belong to one drop menu.

Color

Color paints the button with one of the general colors of the library: the accent colors give a filled button with a matching text color, the background, foreground and border colors a neutral surface.

Color

External Icons

Icon and ChevronDownIcon take icons from external libraries like FontAwesome and Bootstrap Icons through BitIconInfo (Css, Fa, Bi); a plain string of CSS classes works too. Built-in icons are listed on the Iconography(opens in a new tab) page.

Size

Size scales the font, the padding, the icons and the minimum height of the button together. The callout keeps the size of its content.

Style & Class

Style and Class land on the root, which carries the border of the button. Styles and Classes reach each part: the root, the button, the spinner, the icon, the text, the chevron, the overlay, the callout, and Opened, applied to the root only while the callout is open.



For what no parameter covers, the drop menu reads the CSS variables listed below. Set on :root they re-skin every drop menu, and on the Style of one drop menu they re-skin that one, its callout included. An ancestor element reaches the button's variables only: the open callout is moved to the end of the body, out of the ancestor's reach.

RTL

Dir renders the drop menu right-to-left: the button mirrors its content, the callout is anchored to the right edge of the button, and a responsive panel slides in and is swiped away mirrored.

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitDropMenu CSS variables

Name Default value Description
--bit-DropMenu-color Per Variant, from the Color role Text and icon color of the button at rest.
--bit-DropMenu-background Per Variant, from the Color role Background of the button at rest.
--bit-DropMenu-border-color Per Variant Border color of the button, in every state.
--bit-DropMenu-hover-border-color --bit-DropMenu-border-color, or per Variant Border color of the button on hover.
--bit-DropMenu-active-border-color --bit-DropMenu-border-color, or per Variant Border color of the button while pressed or open.
--bit-DropMenu-border-width --bit-shp-brd-width Border thickness of the button.
--bit-DropMenu-radius --bit-shp-radius-button Corner radius of the button, followed by its focus ring.
--bit-DropMenu-hover-color Per Variant, from the Color role Text and icon color on hover.
--bit-DropMenu-hover-background The Color role's hover color Background on hover.
--bit-DropMenu-active-color Per Variant, from the Color role Text and icon color while pressed or while the callout is open.
--bit-DropMenu-active-background The Color role's active color Background while pressed or while the callout is open.
--bit-DropMenu-disabled-color The Color role's disabled text color Text and icon color when disabled or loading.
--bit-DropMenu-disabled-background Per Variant, the Color role's disabled color Background when disabled or loading.
--bit-DropMenu-disabled-border-color Per Variant Border color when disabled or loading.
--bit-DropMenu-focus-color The Color role's focus color Focus ring color of the button.
--bit-DropMenu-min-height Per Size, --bit-siz-ctrl-* Smallest height of the button, and the width of one that holds only an icon.
--bit-DropMenu-padding Per Size Padding of the button.
--bit-DropMenu-gap spacing(1) Room between the icon, the text and the chevron.
--bit-DropMenu-font-size Per Size, from the type ramp Text size of the button.
--bit-DropMenu-font-weight --bit-tpg-font-weight Text weight of the button.
--bit-DropMenu-icon-size Per Size, --bit-siz-icon-* Size of the icon, the chevron and the spinner.
--bit-DropMenu-spinner-color The button's own text color The moving arc of the loading spinner.
--bit-DropMenu-spinner-track-color The text color at 25% The ring the spinner's arc travels on.
--bit-DropMenu-callout-background --bit-clr-bg-pri, or the Background kind Background of the callout.
--bit-DropMenu-callout-color --bit-clr-fg-pri Text color of the callout.
--bit-DropMenu-callout-border-color None, or the Border kind Border color of the callout.
--bit-DropMenu-callout-border-width 0, or --bit-shp-brd-width with Border Border thickness of the callout.
--bit-DropMenu-callout-radius --bit-shp-radius-popup Corner radius of the callout.
--bit-DropMenu-callout-shadow --bit-shd-popup Elevation of the callout.
--bit-DropMenu-callout-padding 0 Padding around the content of the callout.
--bit-DropMenu-callout-width auto (the Width parameter) Width of the callout.
--bit-DropMenu-callout-min-width auto (the MinWidth parameter) Narrowest the callout gets.
--bit-DropMenu-callout-max-width none (the MaxWidth parameter) Widest the callout gets.
--bit-DropMenu-callout-max-height The MaxHeight parameter Tallest the callout grows before it scrolls; only read when MaxHeight is set.
--bit-DropMenu-overlay-background transparent The layer behind an open callout.

API

Every parameter, public member, sub-class and enum this component exposes.

BitDropMenu parameters

Name Type Default value Description
Alignment BitPlacement? null How the callout is lined up with the button across the side it opens on: Start (the default), Center or End, which follow the reading direction; Left and Right are honoured above or below the button, Top and Bottom beside it. Anything else falls back to Start.
AriaDescription string? null The description of the drop menu for screen readers, rendered as visually hidden text the button points at through aria-describedby.
AriaHidden bool false If true, adds an aria-hidden attribute instructing screen readers to ignore the button of the drop menu.
AutoClose bool false Closes the callout as soon as a click lands anywhere inside it, as an action list should. Off by default, so a form or a filter panel stays open while it is used.
AutoFocus bool false Moves the focus into the callout as soon as it opens, to its first focusable element, or to the callout itself when it holds none.
Background BitColorKind? null The color kind of the background of the callout of the drop menu.
Body RenderFragment? null Alias of the ChildContent.
Border BitColorKind? null The color kind of the border of the callout of the drop menu.
ChevronDownIcon BitIconInfo? null The icon for the chevron down part of the drop menu using custom CSS classes for external icon libraries. Takes precedence over ChevronDownIconName when both are set.
ChevronDownIconName string? null The icon name for the chevron down part of the drop menu from the built-in Fluent UI icons. For external icon libraries, use ChevronDownIcon instead.
ChildContent RenderFragment? null The content of the callout of the drop menu.
Classes BitDropMenuClassStyles? null Custom CSS classes for different parts of the drop menu.
Color BitColor? null The general color of the button of the drop menu.
DefaultIsOpen bool? null The initial opening state of the callout in the uncontrolled mode, which is when the IsOpen parameter is not set.
DropDirection BitDropDirection BitDropDirection.TopAndBottom Determines the allowed drop directions of the callout of the drop menu.
FullWidth bool false Expands the drop menu width to 100% of the available width.
Gap int 0 The distance in pixels between the button and the callout, on whichever side the callout ends up on.
HoverCloseDelay int 150 The delay in milliseconds before the callout closes once the pointer leaves the drop menu in the OpenOnHover mode. It bridges the gap between the button and the callout, so moving the pointer from one to the other does not close what the pointer is on its way to.
HoverOpenDelay int 0 The delay in milliseconds before the callout opens once the pointer enters the drop menu in the OpenOnHover mode, so that passing over the button on the way somewhere else does not open it.
Icon BitIconInfo? null The icon to display inside the header using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set.
IconName string? null The name of the icon to display inside the header from the built-in Fluent UI icons. For external icon libraries, use Icon instead.
IsLoading bool false Determines whether the drop menu is in the loading state: the icon becomes a spinner, an open callout closes and it cannot be opened again until the loading ends. The button keeps the focus and is marked aria-disabled and aria-busy.
IsOpen bool false Determines the opening state of the callout of the drop menu.
LazyRender bool false Keeps the content of the callout out of the page until the first opening, then keeps it, so its state survives a close.
MatchWidth bool false Expands the callout of the drop menu to at least the width of the button of the drop menu. It is applied after the callout is measured, so it takes precedence over Width.
MaxHeight string? null The maximum height of the callout of the drop menu as a CSS value (e.g. "20rem"), beyond which its content scrolls. It takes over from the automatic cap that otherwise keeps the callout within the room the viewport leaves, so it should stay within what the shortest screen the drop menu is used on can show.
MaxWidth string? null The maximum width of the callout of the drop menu as a CSS value (e.g. "20rem"), beyond which its content wraps.
MinWidth string? null The minimum width of the callout of the drop menu as a CSS value (e.g. "20rem"), so that a narrow content does not end up in a cramped callout.
NoChevron bool false Removes the chevron-down icon from the button of the drop menu.
NoShadow bool false Removes the box-shadow from the callout of the drop menu.
OnClick EventCallback The callback is called when the drop menu is clicked.
OnDismiss EventCallback The callback is called when the drop menu is dismissed.
OnOpen EventCallback The callback is called when the callout of the drop menu is opened.
OpenOnHover bool false Opens the callout when the pointer enters the drop menu and closes it when the pointer leaves it, which is what a navigation menu is usually expected to do. The button keeps toggling the callout on a click, so the keyboard and the touch screens - where hovering does not exist and this mode turns itself off - are left with a way to reach it.
PanelPlacement BitPlacement? null The position of the responsive panel to show on the screen. Start and End follow the text direction, Left and Right stay where they are named in both; Center and the two combined values fall back to End.
Responsive bool false Renders the drop menu in responsive mode on small screens.
ScrollContainerId string? null The id of the element which needs to be scrollable in the content of the callout of the drop menu.
Placement BitPlacement? null The side of the button the callout opens on when there is room for it there; it falls back to the opposite side when there is not. Top, Bottom, Left and Right are honoured as they are named, Start and End against the reading direction; Center, the two combined values, or none leave the choice to DropDirection.
Size BitSize? null The size of the button of the drop menu.
Styles BitDropMenuClassStyles? null Custom CSS styles for different parts of the drop menu.
Template RenderFragment? null The custom content to render inside the header of the drop menu.
Text string? null The text to show inside the header of the drop menu.
Title string? null The tooltip to show when the mouse is placed on the button of the drop menu.
Transparent bool false Makes the background of the header of the drop menu transparent.
TrapFocus bool false Keeps the keyboard inside the callout while it is open: the focus moves into it as it opens, Tab and Shift+Tab cycle within it instead of running on into the page behind it, and the callout reports itself as a modal dialog to the screen readers. It implies AutoFocus.
Variant BitVariant? null The visual variant of the button of the drop menu: filled (the default look), outlined, or text only. It decides how the Color is painted onto the button, so the two are set together.
Width string? null The width of the callout of the drop menu as a CSS value (e.g. "20rem"). By default the callout is only as wide as its content needs. MatchWidth takes precedence over it.

BitDropMenu public members

Name Type Default value Description
Open () => Task Opens the callout of the drop menu programmatically, unless the drop menu is disabled or loading.
Close () => Task Closes the callout of the drop menu programmatically.
Toggle () => Task Toggles the callout of the drop menu programmatically.

BitComponentBase parameters

Name Type Default value Description
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.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
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.
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.

BitComponentBase public members

Name Type Default value Description
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.

BitDropMenuClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitDropMenu.
Opened string? null Custom CSS classes/styles for the root element of the BitDropMenu while its callout is open, applied on top of the Root ones.
Button string? null Custom CSS classes/styles for the button of the BitDropMenu.
Spinner string? null Custom CSS classes/styles for the loading spinner of the BitDropMenu.
Icon string? null Custom CSS classes/styles for the icon of the BitDropMenu.
Text string? null Custom CSS classes/styles for the text of the BitDropMenu.
ChevronDown string? null Custom CSS classes/styles for the chevron-down icon of the BitDropMenu.
Overlay string? null Custom CSS classes/styles for the overlay of the BitDropMenu.
Callout string? null Custom CSS classes/styles for the callout of the BitDropMenu.

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.

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.

BitColorKind enum

Name Value Description
Primary 0 The primary color kind.
Secondary 1 The secondary color kind.
Tertiary 2 The tertiary color kind.
Transparent 3 The transparent color kind.

BitDropDirection enum

Name Value Description
All 0 The direction determined automatically based on the available spaces in all directions.
TopAndBottom 1 The direction determined automatically based on the available spaces in only top and bottom directions.

BitPlacement enum

Name Value Description
Top 0 The top edge.
Bottom 1 The bottom edge.
Start 2 The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top.
End 3 The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom.
Left 4 The left edge, in both reading directions.
Right 5 The right edge, in both reading directions.
Center 6 The middle of the axis, against neither edge.
TopAndBottom 7 Both edges of the block axis at once.
StartAndEnd 8 Both edges of the inline axis at once, following the reading direction the way Start and End do.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

BitVariant enum

Name Value Description
Fill 0 Fill styled variant.
Outline 1 Outline styled variant.
Text 2 Text styled variant.

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.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.