HxDropdown
Bootstrap 5 Dropdown component.
Basic structure
Dropdowns are usualy used in combination with a button. For such case use the HxDropdownButtonGroup with HxDropdownToggleButton.
<HxDropdownButtonGroup>
<HxDropdownToggleButton Color="ThemeColor.Secondary">Dropdown button</HxDropdownToggleButton>
<HxDropdownMenu>
<HxDropdownItemNavLink Href="...">Item 1</HxDropdownItemNavLink>
<HxDropdownItem OnClick="...">Item 2</HxDropdownItem>
<HxDropdownDivider />
<HxDropdownItemText>Plain text</HxDropdownItemText>
</HxDropdownMenu>
</HxDropdownButtonGroup>You can also create your own dropdown by using the plain HxDropdown and HxDropdownToggleElement.
<HxDropdown>
<HxDropdownToggleElement ElementName="a" role="button" Caret="true">Custom toggle</HxDropdownToggleElement>
<HxDropdownMenu>
<HxDropdownItemNavLink Href="...">Item 1</HxDropdownItemNavLink>
<HxDropdownItem OnClick="...">Item 2</HxDropdownItem>
<HxDropdownDivider />
<HxDropdownItemText>Plain text</HxDropdownItemText>
</HxDropdownMenu>
</HxDropdown>Examples
Single button #
Button variants #
Split button #
Set HxDropdownButtonGroup.Split="true" and leave the HxDrodownButtonToggle.Text empty (you can use the ChildContent to improve accessibility).
Sizing #
HxDropdowns work with buttons of all sizes, including default and split dropdown buttons.
Directions #
Header, Disabled, Active #
Set CssClass="active" to highlight the item. (In case of NavLink functionality needed, separate HxDropdownMenuNavLinkItem will be implemented.)
Set Enabled="false" to disable the item. The HxFormState.Enabled inheritance is also supported.
Custom content #
Use HxDropdownContent instead of HxDropdownMenu.
Custom toggle element #
Use HxDropdownToggleElement (with ElementName="...") instead of HxDropdownToggleButton to create custom toggler.
(Usually you will add role="button" to apply pointer cursor type.) Use plain HxDropdown instead of HxDropdownButtongGroup
to have more control over the dropdown.
Dropdown offset and reference #
You can change the location of the dropdown by setting the HxDropdownToggleButton.DropdownOffset
and/or HxDropdownToggleButton.DropdownReference.
Reference to custom HTML element #
Bootstrap's dropdown relies on specific structure where the dropdown-toggle and dropdown-menu are direct ancestors of common parent.
When you cannot stick with this structure (e.g. by adding Tooltip wrapping the button with span), you have to use
explicit DropdownReference.
Specific structure of #id gets recognized and handed over to the underlying Bootstraps dropdown.
You might get
TypeError: Failed to execute 'getComputedStyle' on 'Window': parameter 1 is not of type 'Element'.Auto close behavior #
By default, the dropdown menu is closed when clicking inside or outside the dropdown menu. You can use the AutoClose parameter to change this behavior of the dropdown.
Nav with dropdown #
You can use HxDropdown inside HxNav.
Dark dropdowns #
Opt into darker dropdowns to match a dark navbar or custom style by adding .dropdown-menu-dark onto a HxDropdownMenu component.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying div element. |
| AutoClose | DropdownAutoClose |
By default, the dropdown menu is closed when clicking inside or outside the dropdown menu (DropdownAutoClose.True).
You can use the AutoClose parameter to change this behavior of the dropdown.
https://getbootstrap.com/docs/5.1/components/dropdowns/#auto-close-behavior. |
| ChildContent | RenderFragment |
Content of the component. |
| CssClass | string |
Any additional CSS class to apply. |
| Direction | DropdownDirection |
Direction in which the dropdown is opened. |
HxDropdownButtonGroup
Bootstrap 5 Dropdown component for dropdown-buttons.
For generic dropdowns use HxDropdown.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying div element. |
| AutoClose | DropdownAutoClose |
By default, the dropdown menu is closed when clicking inside or outside the dropdown menu (DropdownAutoClose.True).
You can use the AutoClose parameter to change this behavior of the dropdown.
https://getbootstrap.com/docs/5.1/components/dropdowns/#auto-close-behavior. |
| ChildContent | RenderFragment |
Content of the component. |
| CssClass | string |
Any additional CSS class to apply. |
| Direction | DropdownDirection |
Direction in which the dropdown is opened. |
| Split | bool |
Set true to create a split dropdown
(using a btn-group). |
HxDropdownToggleButton
Bootstrap Dropdown toggle button which triggers the HxDropdown to open.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying <button> element. |
| ChildContent | RenderFragment |
Button content. |
| Color | ThemeColor? |
Bootstrap button style - theme color. Default is taken from HxButton.Defaults (ThemeColor.None if not customized). |
| CssClass | string |
Custom CSS class to render with the <button />.When using Tooltip you might want to use TooltipWrapperCssClass instead of CssClass to get the desired result. |
| DropdownOffset | Nullable<ValueTuple<int, int>> |
Offset (skidding, distance)
of the dropdown relative to its target. Default is (0, 2). |
| DropdownReference | string |
Reference element of the dropdown menu. Accepts the values of toggle (default), parent,
an HTMLElement reference (e.g. #id) or an object providing getBoundingClientRect.
For more information refer to Popper's constructor docs
and virtual element docs. |
| EditContext | EditContext |
Associated EditContext. |
| Enabled | bool? |
|
| FormId | string |
Specifies the form the button belongs to. |
| Icon | IconBase |
Icon to render into the button. |
| IconPlacement | ButtonIconPlacement? |
Position of the icon within the button. Default is ButtonIconPlacement.Start (configurable through HxButton.Defaults). |
| OnClick | EventCallback<MouseEventArgs> |
Raised after the button is clicked. |
| OnClickPreventDefault | bool |
Prevents the default action for the onclick event. Deafult is false. |
| OnClickStopPropagation | bool |
Stop onClick-event propagation. Deafult is true. |
| OnInvalidClick | EventCallback<MouseEventArgs> |
Raised after the button is clicked and EditContext validation fails. |
| OnValidClick | EventCallback<MouseEventArgs> |
Raised after the button is clicked and EditContext validation succeeds. |
| Outline | bool? |
Bootstrap "outline" button style. |
| Settings | ButtonSettings |
Set of settings to be applied to the component instance (overrides HxButton.Defaults, overriden by individual parameters). |
| SingleClickProtection | bool |
Set false if you want to allow multiple OnClick handlers in parallel. Default is true. |
| Size | ButtonSize? |
Button size. Default is ButtonSize.Regular. |
| Spinner | bool? |
Set state of the embedded HxSpinner.
Leave null if you want automated spinner when any of the OnClick handlers is running.
You can set an explicit false constant to disable (override) the spinner automation. |
| Text | string |
Text of the button. |
| Tooltip | string |
Tooltip text. If set, a span wrapper will be rendered around the <button />. For most scenarios you will then use TooltipWrapperCssClass instead of CssClass. |
| TooltipCssClass | string |
Custom CSS class to render with the tooltip. |
| TooltipPlacement | TooltipPlacement |
Tooltip placement. |
| TooltipWrapperCssClass | string |
Custom CSS class to render with the tooltip span wrapper of the <button />.If set, the span wrapper will be rendered no matter the Tooltip text is set or not. |
Event callbacks
| Name | Type | Description |
|---|---|---|
| OnHidden | EventCallback |
Fired when the dropdown has finished being hidden from the user and CSS transitions have completed. |
| OnShown | EventCallback |
Fired when the dropdown has been made visible to the user and CSS transitions have completed. |
Methods
| Method | Returns | Description |
|---|---|---|
| HideAsync() | Task |
Hides the dropdown. |
| ShowAsync() | Task |
Shows the dropdown. |
Static properties
| Property | Type | Description |
|---|---|---|
| Defaults | ButtonSettings |
Application-wide defaults for HxDropdownToggleButton and derived components. |
HxDropdownToggleElement
Bootstrap Dropdown toggle button which triggers the HxDropdown to open.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | IDictionary<string, object> |
A collection of additional attributes that will be applied to the created element. |
| Caret | bool |
Gets or sets whether to display caret in the toggle. Default is false. |
| ChildContent | RenderFragment |
Content of the component. |
| CssClass | string |
Custom CSS class to render with the toggle element. |
| DropdownOffset | Nullable<ValueTuple<int, int>> |
Offset (skidding, distance)
of the dropdown relative to its target. Default is (0, 2). |
| DropdownReference | string |
Reference element of the dropdown menu. Accepts the values of toggle (default), parent,
an HTMLElement reference (e.g. #id) or an object providing getBoundingClientRect.
For more information refer to Popper's constructor docs
and virtual element docs. |
| ElementName | string |
Gets or sets the name of the element to render. Default is span. |
Event callbacks
| Name | Type | Description |
|---|---|---|
| OnHidden | EventCallback |
Fired when the dropdown has finished being hidden from the user and CSS transitions have completed. |
| OnShown | EventCallback |
Fired when the dropdown has been made visible to the user and CSS transitions have completed. |
Methods
| Method | Returns | Description |
|---|---|---|
| HideAsync() | Task |
Hides the dropdown. |
| ShowAsync() | Task |
Shows the dropdown. |
HxDropdownMenu
Bootstrap Dropdown menu which opens when triggered.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying ul element. |
| ChildContent | RenderFragment |
Content of the component. |
| CssClass | string |
Any additional CSS class to apply. |
HxDropdownHeader
Dropdown menu header for HxDropdownMenu.
API
Parameters
| Name | Type | Description |
|---|---|---|
| ChildContent | RenderFragment |
Content of the component. |
| CssClass | string |
Any additional CSS class to apply. |
HxDropdownItemNavLink
NavLink item for the HxDropdownMenu.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying NavLink component. |
| ChildContent | RenderFragment |
Content. |
| ContainerCssClass | string |
Additional CSS class for underlying li container (wrapping the main a inside). |
| CssClass | string |
Additional CSS class. |
| Enabled | bool? |
|
| Href | string |
Navigation target. |
| Match | NavLinkMatch? |
URL matching behavior for the underlying NavLink.
Default is NavLinkMatch.Prefix.
You can set the value to null to disable the matching. |
| OnClick | EventCallback<MouseEventArgs> |
Raised when the item is clicked. |
| Text | string |
Text of the item. |
HxDropdownItem
Generic item for the HxDropdownMenu.
API
Parameters
| Name | Type | Description |
|---|---|---|
| AdditionalAttributes | Dictionary<string, object> |
Additional attributes to be splatted onto an underlying li>span element. |
| ChildContent | RenderFragment |
Content of the component. |
| ContainerCssClass | string |
Additional CSS class for underlying li container (wrapping the main span inside). |
| CssClass | string |
Additional CSS class for underlying li>span element. |
| Enabled | bool? |
|
| OnClick | EventCallback<MouseEventArgs> |
Raised when the item is clicked. |
HxDropdownItemText
Text item for the HxDropdownMenu.
API
Parameters
| Name | Type | Description |
|---|---|---|
| ChildContent | RenderFragment |
Content of the component. |
| ContainerCssClass | string |
Additional CSS class for underlying li container (wrapping the main span inside). |
| CssClass | string |
Any additional CSS class to apply. |
HxDropdownDivider
Divider for the HxDropdownMenu.
API
Parameters
| Name | Type | Description |
|---|---|---|
| ContainerCssClass | string |
Additional CSS class for underlying li container (wrapping the main hr inside). |
| CssClass | string |
Additional CSS class for underlying li>hr element. |