Skip to content
BlazorUI

Buttons

ButtonGroup

Bit.BlazorUI

The ButtonGroup joins related buttons into a single unit: a plain action toolbar, or a single-select or multi-select group of toggle buttons. The whole group is one tab stop that the arrow, Home, and End keys navigate, and it follows the WAI-ARIA pattern matching its selection mode.

Notes

The BitButtonGroup is a Multi-API component which can accept the list of Items in 3 different ways:
1. The BitButtonGroupItem class
2. A Custom Generic class
3. The BitButtonGroupOption component

The SelectionMode decides what the group is: None renders plain action buttons in a toolbar, Single renders a radiogroup whose buttons report aria-checked, and Multiple renders a toolbar of toggle buttons that report aria-pressed. In every mode the group holds a single tab stop (a roving tabindex) unless Navigable is disabled.

Usage

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

Basic

Related buttons are grouped by listing them in the Items of a single ButtonGroup, which joins them into one unit with shared borders and rounded outer corners. By default the buttons are plain actions that cannot be toggled, and the whole group is a single tab stop the arrow keys move through.

Variant

The visual style of the group is set by the Variant: Fill (default), Outline, or Text. The group can be disabled as a whole through IsEnabled, or one button at a time through the item's IsEnabled.


Fill (default)


Outline


Text

Icon

Each item can render an icon before its text through IconName, which takes a name from the built-in Fluent UI icon set.


Fill (default)


Outline


Text

IconOnly

The IconOnly drops the text of every button and keeps only its icon, which suits compact toolbars and tight spaces. Because such a button has no visible label, give each item an AriaLabel (or at least a Title) so it stays understandable to screen reader users.


Fill (default)


Outline


Text


Alternatively, each button can be set to IconOnly by simply leaving the text field empty.


Fill (default)


Outline


Text

ReversedIcon

The item's ReversedIcon swaps the icon and the text, putting the icon after the content instead of before it. It is set per item, so a single button can point the other way (useful for a trailing "next" arrow).


Fill (default)


Outline


Text

Toggle

The Toggle turns the group into a single-select one, where at most one button is toggled at a time (a shorthand for SelectionMode="BitButtonGroupSelectionMode.Single"). It renders as a radiogroup whose buttons report their state through aria-checked. Toggled buttons can swap their text and icon through the item's OnText/OffText and OnIconName/OffIconName; when they do, also set an AriaLabel so the accessible name stays the same as the state changes. The toggled key is read and set through ToggleKey, seeded by DefaultToggleKey, and every change raises OnToggleChange.


Fill (default)


Outline


Text




Binding:

Toggle key: play




OnToggleChange:

Changed toggle: forward , True




FixedToggle makes the selection mandatory: clicking the toggled button no longer un-toggles it, so the group always keeps exactly one answer.

Vertical

By default the ButtonGroup lays its buttons out horizontally; the Vertical stacks them instead, moving the separators between the buttons from their sides to their edges. The keyboard navigation follows the layout, so the Up and Down arrow keys take over from Left and Right.


Fill (default)


Outline


Text

Events

Clicks can be handled in two places: the group's OnItemClick receives whichever item was clicked, and each item's own OnClick handles just that button. Both run on every click, the group's callback first. Disabled and loading buttons raise neither.


Component's ItemClick event:
Clicked item:


Item's Click event:
Click count: 0

FullWidth

The FullWidth stretches the group to 100% of its container's width. The extra space is shared by the buttons in proportion to their content, so wider labels stay wider - pair it with Justified when every button should end up the same width.


Multiple

Setting the SelectionMode to Multiple lets any number of buttons be toggled at the same time. The toggled keys are available through the ToggleKeys two-way bound parameter.


Binding:
Toggle keys: bold


MaxToggles caps how many buttons can be toggled at once:


FixedToggle keeps at least one button toggled:

Justified

The Justified gives every button an equal width, so the buttons evenly fill the ButtonGroup. Combined with FullWidth it turns the ButtonGroup into a segmented control.


Default (buttons are sized by their content)

Justified (buttons share the width equally)

Detached

The Detached breaks the buttons apart: the border and the rounding move from the group onto each button, so they read as separate buttons that still share the group's color, size, and selection behavior. The Gap takes any CSS length and sets the space between them.


Fill (default)


Outline


Gap

Rounded

The Rounded renders pill shaped corners. On an attached group only the outer corners are rounded, while combining it with Detached turns every button into its own pill.


Attached


Detached

Overflow

The Overflow decides what happens when the buttons do not fit: Wrap moves them onto more lines, Scroll keeps one line and lets the group scroll sideways — by swiping, by shift+wheel, or with the arrow keys, since the scrollbar itself is hidden so that the border keeps hugging the buttons — Scrollbar does the same but keeps the scrollbar visible as an affordance, at the cost of the height it occupies inside the border, and Clip (the default) keeps one line and cuts the rest off. Drag the bottom-right corner of the dashed boxes below to resize them and watch the behavior change.


Wrap


Scroll


Scrollbar

SelectionIndicator

The ShowSelectionIndicator renders a check mark at the start of the toggled buttons. The indicator always occupies its space, so toggling a button never shifts the layout.


Single


Multiple

Loading & Badge

Each button can show a spinner in place of its icon by setting the item's IsLoading, which also blocks its click, and can render a short count at its end by setting the item's Badge.


Loading:
Click a button to see it load for a moment.


Badge:

Links

Giving an item an Href renders that button as an anchor tag instead, optionally opened elsewhere through Target.


Templates

The content of the buttons can be replaced entirely: the group's ItemTemplate re-renders every button, while an item's own Template re-renders only that one and wins over the group's template. A template replaces the icon, text, and badge, so anything the button needs has to be part of it.


ItemTemplate (applies to every button):


Item's Template (applies to a single button):

Tooltips

An item's Title becomes the native tooltip of its button, which is the cheapest way to explain an icon-only button on hover. In a toggle group, OnTitle and OffTitle let the tooltip follow the toggle state and fall back to Title when they are not set. A tooltip is not an accessible name, so keep setting AriaLabel for icon-only buttons.


Hover the buttons to see their tooltips:


OnTitle & OffTitle (toggle the button and hover it again):

Accessibility

The ButtonGroup follows the WAI-ARIA patterns: it renders as a radiogroup of radio buttons in the Single selection mode and as a toolbar of toggle buttons otherwise, and the whole group is a single tab stop that the arrow, Home, and End keys navigate (a roving tabindex). Always give the group an AriaLabel.


Tab into the group, then navigate it using the arrow, Home, and End keys:


SelectOnFocus makes the selection follow the keyboard focus:


DisabledInteractive keeps the disabled buttons focusable, so they stay discoverable:


Navigable="false" restores the natural tab order, making every button its own tab stop:

Color

The Color sets the palette of the whole group - its border, fill, hover and active states, the focus ring, and the darker shade used for toggled buttons - from the theme's general, background, foreground, and border colors.


Primary


Secondary


Tertiary


Info


Success


Warning


SevereWarning


Error


PrimaryBackground


SecondaryBackground


TertiaryBackground


PrimaryForeground


SecondaryForeground


TertiaryForeground


PrimaryBorder


SecondaryBorder


TertiaryBorder




Disabled:

Primary


Secondary


Tertiary


Info


Success


Warning


SevereWarning


Error


PrimaryBackground


SecondaryBackground


TertiaryBackground


PrimaryForeground


SecondaryForeground


TertiaryForeground


PrimaryBorder


SecondaryBorder


TertiaryBorder

External Icons

Beyond the built-in Fluent UI icons, the item's Icon takes a BitIconInfo that renders an icon from any external library. Pass the CSS classes directly, or use the helpers such as BitIconInfo.Fa (FontAwesome), BitIconInfo.Bi (Bootstrap Icons), and BitIconInfo.Css. When both are set, Icon takes precedence over IconName.






Size

The Size picks one of three presets - Small, Medium (default), and Large - which scale the font size and padding of every button, along with the spinner, badge, and selection indicator that follow the text size.


Small


Medium


Large

Style & Class

Styling works at three levels: Style and Class target the root element, each item's own Style and Class target a single button, and Styles and Classes reach every part of the component - Root, Button, ToggledButton, Icon, Text, Badge, Spinner, and SelectionIndicator.


Component's style & class:


Item's style & class:


Styles & Classes:

RTL

Setting Dir to Rtl (or inheriting it from an ancestor) flips the ButtonGroup for right-to-left languages: the buttons, their icons, and the separators between them all reverse, and so does the arrow key navigation, where Left now moves forward and Right moves back.





API

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

BitButtonGroup parameters

Name Type Default value Description
ChildContent RenderFragment? null The content of the BitButtonGroup, that are BitButtonGroupOption components.
IconOnly bool false Determines that only the icon should be rendered.
Classes BitButtonGroupClassStyles? null Custom CSS classes for different parts of the ButtonGroup.
Color BitColor? null The general color of the button group.
DefaultToggleKey string? null The default key that will be initially used to set toggled item in toggle mode if the ToggleKey parameter is not set.
DefaultToggleKeys IEnumerable<string>? null The default keys that will be initially used to set the toggled items in the Multiple selection mode if the ToggleKeys parameter is not set.
Detached bool false Detaches the buttons from each other, so each button is rendered as a separate rounded button.
DisabledInteractive bool false Keeps the disabled buttons focusable by rendering them with the aria-disabled attribute instead of the disabled attribute, so that assistive technologies can still discover them.
FixedToggle bool false Enables the fixed-toggle mode that ensures one item to be always toggled. In the Multiple selection mode it prevents un-toggling the last toggled item.
FullWidth bool false Expand the ButtonGroup width to 100% of the available width.
Gap string? null The gap between the buttons of the ButtonGroup in the detached mode.
Justified bool false Gives every button an equal width so that the buttons evenly fill the width of the ButtonGroup.
Items IEnumerable<TItem> new List<TItem>() List of Item, each of which can be a Button with different action in the ButtonGroup.
ItemTemplate RenderFragment<TItem>? null The content inside the item can be customized.
MaxToggles int? null The maximum number of items that can be toggled at the same time in the Multiple selection mode.
NameSelectors BitButtonGroupNameSelectors<TItem>? null Names and selectors of the custom input type properties.
Navigable bool true Enables the roving tabindex behavior, which turns the whole ButtonGroup into a single tab stop that is navigable using the arrow, Home, and End keys.
OnItemClick EventCallback<TItem> The callback that is called when a button is clicked.
OnToggleChange EventCallback<TItem> The callback that called when toggled item change.
Options RenderFragment? null Alias of ChildContent.
Overflow BitButtonGroupOverflow? null Determines how the ButtonGroup behaves when its buttons do not fit in the available space.
Rounded bool false Renders the ButtonGroup with fully rounded (pill shaped) corners.
SelectionMode BitButtonGroupSelectionMode? null Determines how many items can be toggled at the same time. When not set, it falls back to Single if the Toggle parameter is enabled, otherwise None.
SelectOnFocus bool false Toggles the focused item while navigating the ButtonGroup using the keyboard, so that the selection follows the focus.
ShowSelectionIndicator bool false Renders a check mark at the start of the toggled buttons.
Toggle bool false Display ButtonGroup with toggle mode enabled for each button. It is a shorthand of setting the SelectionMode parameter to Single.
ToggleKey string? null The key of the toggled item in the Single selection mode. (two-way bound)
ToggleKeys IEnumerable<string>? null The keys of the toggled items in the Multiple selection mode. (two-way bound)
Size BitSize null The size of ButtonGroup, Possible values: Small | Medium | Large.
Styles BitButtonGroupClassStyles? null Custom CSS styles for different parts of the ButtonGroup.
Variant BitVariant? null The visual variant of the button group.
Vertical bool false Defines whether to render ButtonGroup children vertically.

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.
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.

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.

BitButtonGroupItem properties

Name Type Default value Description
AriaLabel string? null The accessible label of the item, rendered as the aria-label attribute. Required for icon-only items, and strongly recommended in toggle mode when OnText/OffText are used, so that the accessible name of the item stays the same while its toggle state changes.
Badge string? null The content of the badge rendered at the end of the item, usually a short count.
Class string? null The custom CSS classes of the item.
Href string? null The url of the link rendered by the item. If provided, the item renders as an anchor tag instead of a button.
Icon BitIconInfo? null The icon to render next to the item text. Takes precedence over IconName.
IconName string? null Name of an icon to render next to the item text.
IsEnabled bool true Whether or not the item is enabled.
IsLoading bool false Whether or not the item is in the loading state, which replaces its icon with a spinner and blocks its click.
Key string? null A unique value to use as a Key of the item.
OffIcon BitIconInfo? null The icon of the item when it is not checked in toggle mode. Takes precedence over OffIconName.
OffIconName string? null The icon of the item when it is not checked in toggle mode.
OffText string? null The text of the item when it is not checked in toggle mode.
OffTitle string? null The title of the item when it is not checked in toggle mode.
OnIcon BitIconInfo? null The icon of the item when it is checked in toggle mode. Takes precedence over OnIconName.
OnIconName string? null The icon of the item when it is checked in toggle mode.
OnText string? null The text of the item when it is checked in toggle mode.
OnTitle string? null The title of the item when it is checked in toggle mode.
OnClick EventCallback Click event handler of the item.
ReversedIcon bool false Reverses the positions of the icon and the main content of the item.
Style string? null The custom value for the style attribute of the item.
Target string? null The target attribute of the link when the item renders as an anchor (by providing the Href property).
Template RenderFragment<BitButtonGroupItem>? null The custom template for the item.
Text string? null Text to render in the item.
Title string? null Title to render in the item.

BitButtonGroupOption properties

Name Type Default value Description
AriaLabel string? null The accessible label of the option, rendered as the aria-label attribute. Required for icon-only options, and strongly recommended in toggle mode when OnText/OffText are used, so that the accessible name of the option stays the same while its toggle state changes.
Badge string? null The content of the badge rendered at the end of the option, usually a short count.
Class string? null The custom CSS classes of the option.
Href string? null The url of the link rendered by the option. If provided, the option renders as an anchor tag instead of a button.
Icon BitIconInfo? null The icon to render next to the option text. Takes precedence over IconName.
IconName string? null Name of an icon to render next to the option text.
IsEnabled bool true Whether or not the option is enabled.
IsLoading bool false Whether or not the option is in the loading state, which replaces its icon with a spinner and blocks its click.
Key string? null A unique value to use as a key of the option.
OffIcon BitIconInfo? null The icon of the option when it is not checked in toggle mode. Takes precedence over OffIconName.
OffIconName string? null The icon of the option when it is not checked in toggle mode.
OffText string? null The text of the option when it is not checked in toggle mode.
OffTitle string? null The title of the option when it is not checked in toggle mode.
OnIcon BitIconInfo? null The icon of the option when it is checked in toggle mode. Takes precedence over OnIconName.
OnIconName string? null The icon of the option when it is checked in toggle mode.
OnText string? null The text of the option when it is checked in toggle mode.
OnTitle string? null The title of the option when it is checked in toggle mode.
OnClick EventCallback Click event handler of the option.
ReversedIcon bool false Reverses the positions of the icon and the main content of the option.
Style string? null The custom value for the style attribute of the option.
Target string? null The target attribute of the link when the option renders as an anchor (by providing the Href parameter).
Template RenderFragment<BitButtonGroupOption>? null The custom template for the option.
Text string? null Text to render in the option.
Title string? null Title to render in the option.

BitButtonGroupClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitButtonGroup.
Button string? null Custom CSS classes/styles for the internal button of the BitButtonGroup.
Badge string? null Custom CSS classes/styles for the badge of the buttons of the BitButtonGroup.
Icon string? null Custom CSS classes/styles for the icon of the BitButtonGroup.
SelectionIndicator string? null Custom CSS classes/styles for the selection indicator (check mark) of the toggled buttons of the BitButtonGroup.
Spinner string? null Custom CSS classes/styles for the loading spinner of the buttons of the BitButtonGroup.
Text string? null Custom CSS classes/styles for the text of the BitButtonGroup.
ToggledButton string? null Custom CSS classes/styles for the button when in toggle mode of the BitButtonGroup.

BitButtonGroupNameSelectors properties

Name Type Default value Description
AriaLabel BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.AriaLabel)) AriaLabel field name and selector of the custom input class.
Badge BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Badge)) Badge field name and selector of the custom input class.
Class BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Class)) The CSS Class field name and selector of the custom input class.
Href BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Href)) Href field name and selector of the custom input class.
Icon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitButtonGroupItem.Icon)) Icon field name and selector of the custom input class.
IconName BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.IconName)) IconName field name and selector of the custom input class.
IsEnabled BitNameSelectorPair<TItem, bool> new(nameof(BitButtonGroupItem.IsEnabled)) IsEnabled field name and selector of the custom input class.
IsLoading BitNameSelectorPair<TItem, bool> new(nameof(BitButtonGroupItem.IsLoading)) IsLoading field name and selector of the custom input class.
Key BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Key)) Key field name and selector of the custom input class.
OffIcon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitButtonGroupItem.OffIcon)) OffIcon field name and selector of the custom input class.
OffIconName BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OffIconName)) OffIconName field name and selector of the custom input class.
OffText BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OffText)) OffText field name and selector of the custom input class.
OffTitle BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OffTitle)) OffTitle field name and selector of the custom input class.
OnIcon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitButtonGroupItem.OnIcon)) OnIcon field name and selector of the custom input class.
OnIconName BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OnIconName)) OnIconName field name and selector of the custom input class.
OnText BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OnText)) OnText field name and selector of the custom input class.
OnTitle BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.OnTitle)) OnTitle field name and selector of the custom input class.
OnClick BitNameSelectorPair<TItem, Action<TItem>?> new(nameof(BitButtonGroupItem.OnClick)) OnClick field name and selector of the custom input class.
ReversedIcon BitNameSelectorPair<TItem, bool> new(nameof(BitButtonGroupItem.ReversedIcon)) ReversedIcon field name and selector of the custom input class.
Style BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Style)) Style field name and selector of the custom input class.
Target BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Target)) Target field name and selector of the custom input class.
Template BitNameSelectorPair<TItem, RenderFragment?> new(nameof(BitButtonGroupItem.Template)) Template field name and selector of the custom input class.
Text BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Text)) Text field name and selector of the custom input class.
Title BitNameSelectorPair<TItem, string?> new(nameof(BitButtonGroupItem.Title)) Title field name and selector of the custom input class.

BitNameSelectorPair 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.

BitVariant enum

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

BitButtonGroupSelectionMode enum

Name Value Description
None 0 The items act as plain action buttons and cannot be toggled.
Single 1 At most one item can be toggled at a time (rendered with the radiogroup accessibility pattern).
Multiple 2 Any number of items can be toggled at the same time (rendered with the toolbar accessibility pattern).

BitButtonGroupOverflow enum

Name Value Description
Clip 0 The items are kept on a single line and the overflowing part is clipped.
Wrap 1 The items wrap onto multiple lines.
Scroll 2 The items are kept on a single line and the group becomes scrollable, without rendering a scrollbar. It can still be scrolled by swiping, by shift+wheel, and through the arrow keys.
Scrollbar 3 The items are kept on a single line and the group becomes scrollable, with a visible scrollbar. The scrollbar is laid out inside the border of the group, which makes the group taller.

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 Severe Warning 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.

BitSize enum

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

BitButtonType enum

Name Value Description
Button 0 The button is a clickable button.
Submit 1 The button is a submit button (submits form-data).
Reset 2 The button is a reset button (resets the form-data to its initial values).

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.