ButtonGroup
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, 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
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.
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
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
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. |
| 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. |
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. |
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
You can give us your feedback through our GitHub repo by filing a new Issue or starting a new Discussion.
Or you can review / edit this page on GitHub.
- On this page