# ButtonGroup
## Description
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.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AutoFocus | `bool` | false | Gives the keyboard focus to the ButtonGroup when the page first renders. The focus lands on the button that owns the group's single tab stop, which is the same button a Tab into the group reaches. |
| ChildContent | `RenderFragment?` | null | The content of the BitButtonGroup, that are BitButtonGroupOption components. |
| IconOnly | `bool` | false | Determines that only the icon should be rendered, which also squares the buttons the way every icon button in the library is shaped. The hidden text stays the accessible name of the button, so an icon-only group is still readable without an AriaLabel being set on every item. |
| 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. It is what makes a Single-mode group a mandatory choice: without it, activating the toggled item takes the selection back and leaves the radiogroup with nothing checked. |
| 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, as any CSS length. It sets the public --bit-ButtonGroup-gap custom property on this group, which can also be set on :root to space every detached group out at once. |
| 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. While the cap is reached, the items that are not toggled are rendered with the aria-disabled attribute and stop responding, so that the cap is visible rather than a click that silently does nothing; they stay focusable and come back as soon as one of the toggled items is un-toggled. |
| 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?` | null | Toggles the focused item while navigating the ButtonGroup using the keyboard, so that the selection follows the focus. Unset, it follows the SelectionMode: on in the Single mode, whose arrow keys the WAI-ARIA radiogroup pattern expects to check the radio they land on, and off in the Multiple and None modes. Set it to false on a Single-mode group whose selection does work - a filter, a fetch - so that arrowing across it does not fire that work on every keystroke. The navigation only ever selects: a key landing on an item that is already toggled leaves it toggled, and un-toggling stays with Space, Enter and a click. |
| 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. |
| 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. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `ValueTask` | | Gives the keyboard focus to the button that owns the ButtonGroup's tab stop - the toggled one, otherwise the first focusable one - which is the same button a Tab into the group reaches. It does nothing while the group holds no focusable button at all. |
| 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. |
## Enums
### 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. A detached group lets it spill out instead, since it clips nothing at all - which is what keeps the focus ring of its buttons whole. |
| Wrap | 1 | The items wrap onto multiple lines. |
| Scroll | 2 | The items are kept on a single line and the group becomes scrollable along the axis it is laid out on - sideways, or down a vertical group - without rendering a scrollbar. It can still be scrolled by swiping, by the wheel - ordinary wheel input down a vertical group, shift+wheel across a horizontal one - and through the arrow keys, which bring the button they focus into view. |
| Scrollbar | 3 | The same, with a visible scrollbar. The scrollbar is laid out inside the border of the group, so the group grows by the room it takes on the edge it sits on. |
### 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. |
### 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. |
## Sub Classes
### 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. |
| Rel | `BitLinkRels?` | null | The rel attribute of the link when the item renders as an anchor (by providing the Href property). When Target is _blank and no opener-related rel is given, noopener is added automatically. |
| 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. |
| IsToggled | `bool` | false | Determines if the item is toggled. This property's value is assigned by the component. |
### 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. |
| Rel | `BitLinkRels?` | null | The rel attribute of the link when the option renders as an anchor (by providing the Href parameter). When Target is _blank and no opener-related rel is given, noopener is added automatically. |
| 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. |
| IsToggled | `bool` | false | Determines if the option is toggled. This property's value is assigned by the 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. |
| Rel | `BitNameSelectorPair<TItem, BitLinkRels?>` | new(nameof(BitButtonGroupItem.Rel)) | Rel 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. |
| IsToggled | `BitNameSelectorPair<TItem, bool>` | new(nameof(BitButtonGroupItem.IsToggled)) | IsToggled field name and selector of the custom input class. This property's value is assigned by the component. |
### 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. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-ButtonGroup-color` | Per Variant: the Color role's on color (Fill) or its main color (Outline, Text) | Text and icon color of a button at rest. |
| `--bit-ButtonGroup-background` | Per Variant: the Color role's main color (Fill), transparent (Outline, Text) | Background of a button at rest. |
| `--bit-ButtonGroup-border-color` | The Color role's main color (the group) and dark color (the separators) | Color of the group's outer border and of the separators between its buttons. It wins over the hover and pressed states, which otherwise repaint the border along with the buttons. |
| `--bit-ButtonGroup-separator-color` | --bit-ButtonGroup-border-color | Color of the separators between the buttons alone, leaving the group's outer border to the variable above - which is what a segmented control whose dividers are lighter than its outline needs. In the Detached and Wrap layouts every button draws the whole outline itself, so there are no separators of their own there and the border color paints all of it. |
| `--bit-ButtonGroup-hover-color` | The Color role's on color | Text and icon color while hovered (pointer devices only). |
| `--bit-ButtonGroup-hover-background` | The Color role's hover color | Background while hovered, and the fallback of the pressed background below. |
| `--bit-ButtonGroup-active-background` | --bit-ButtonGroup-hover-background | Background while pressed. |
| `--bit-ButtonGroup-selected-color` | The Color role's on color | Text and icon color of a toggled button, which the check mark of ShowSelectionIndicator follows. |
| `--bit-ButtonGroup-selected-background` | The Color role's dark color | Background and border of a toggled button - the whole of what marks a button as selected, so a group that has to read differently when selected is re-skinned here. |
| `--bit-ButtonGroup-selected-hover-background` | The Color role's dark-hover color | Background and border of a toggled button while hovered or pressed. |
| `--bit-ButtonGroup-selected-border-color` | --bit-ButtonGroup-selected-background | Border of a toggled button, for a selection whose outline is not its background: the two are one declaration otherwise, so tinting the background takes the outline down with it. A color set here is kept while the button is hovered and pressed. |
| `--bit-ButtonGroup-disabled-color` | The Color role's disabled text color | Text and icon color of a disabled button, and of a group disabled as a whole. |
| `--bit-ButtonGroup-disabled-background` | Per Variant: the Color role's disabled color (Fill), transparent (Outline, Text) | Background of a disabled button. |
| `--bit-ButtonGroup-disabled-border-color` | The Color role's disabled color | Border and separators of a disabled group. |
| `--bit-ButtonGroup-focus-color` | Per Variant: the Color role's on color (Fill) or its main color (Outline, Text) | Color of the keyboard focus indicator, which is drawn inside the focused button so the group's rounded corners never clip it - or as the library's outset focus ring when Detached, where nothing is clipped. |
| `--bit-ButtonGroup-radius` | --bit-shp-radius-button, or --bit-shp-radius-full when Rounded | Outer corner radius of the group, or of every button when Detached. |
| `--bit-ButtonGroup-border-width` | --bit-shp-brd-width | Width of the group's outer border and of the separators between its buttons. Set it to 0 for a group whose buttons are told apart by their background alone. |
| `--bit-ButtonGroup-min-height` | Per Size: --bit-siz-ctrl-sm / -md / -lg | Smallest height of a button, which is what lines a group up with the other controls of its size and keeps the smallest one above the 24px minimum pointer target of WCAG 2.2. It is a floor, not a height: a wrapped label still grows the button. |
| `--bit-ButtonGroup-padding` | Per Size: --bit-siz-ctrl-pad-y-* and --bit-siz-ctrl-pad-x-* | Padding of a button. |
| `--bit-ButtonGroup-font-size` | Per Size: --bit-tpg-fs-xs / -sm / -md | Text size of a button. |
| `--bit-ButtonGroup-font-weight` | --bit-tpg-font-weight | Text weight of a button. |
| `--bit-ButtonGroup-icon-size` | Per Size: --bit-siz-icon-sm / -md / -lg | Size of the icon, the loading spinner and the selection indicator, which share one slot so a spinner replacing an icon moves nothing around it. |
| `--bit-ButtonGroup-content-gap` | spacing(1) | Room between the icon, the text and the badge inside a button. |
| `--bit-ButtonGroup-gap` | spacing(1) | Room between the buttons in the Detached mode. The Gap parameter sets this same variable on one instance. |
| `--bit-ButtonGroup-badge-color` | The button's own text color | Text color of a button's badge. |
| `--bit-ButtonGroup-badge-font-size` | Per Size: --bit-tpg-fs-2xs / -xs / -sm | Text size of a button's badge, one ramp step below the button's own text. |
| `--bit-ButtonGroup-badge-background` | A 20% tint of the button's own text color | Background of a button's badge, tinted out of the text color by default so it stays legible on every variant. |
## Examples
Item
Custom
Option
\n**Basic**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Variant**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
private List disabledItems =
[
new() { Text = "Add" }, new() { Text = "Edit", IsEnabled = false }, new() { Text = "Delete" }
];
```
\n**Icon**:
```razor
```
```csharp
private List iconItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { Text = "Edit", IconName = BitIconName.Edit },
new() { Text = "Delete", IconName = BitIconName.Delete }
];
```
\n**IconOnly**:
```razor
```
```csharp
private List iconItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { Text = "Edit", IconName = BitIconName.Edit },
new() { Text = "Delete", IconName = BitIconName.Delete }
];
private List onlyIconItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { IconName = BitIconName.Edit, AriaLabel = "Edit" },
new() { Text = "Delete", IconName = BitIconName.Delete }
];
```
\n**ReversedIcon**:
```razor
```
```csharp
private List reversedIconItems =
[
new() { Text = "Add", IconName = BitIconName.Add, ReversedIcon = true },
new() { Text = "Edit", IconName = BitIconName.Edit, ReversedIcon = true },
new() { Text = "Delete", IconName = BitIconName.Delete, ReversedIcon = true }
];
```
\n**Toggle**:
```razor
Forward
Clear
```
```csharp
private string? toggleKey = "play";
private List toggledItems =
[
new() { Key = "back", OnText = "Back (2X)", OffText = "Back (1X)", OnIconName = BitIconName.RewindTwoX, OffIconName = BitIconName.Rewind },
new() { Key = "play", OnText = "Resume", OffText = "Play", OnIconName = BitIconName.PlayResume, OffIconName = BitIconName.Play },
new() { Key = "forward", OnText = "Forward (2X)", OffText = "Forward (1X)", OnIconName = BitIconName.FastForwardTwoX, OffIconName = BitIconName.FastForward, ReversedIcon = true }
];
private BitButtonGroupItem? onChangeToggleItem;
private List changeToggledItems =
[
new() { Key = "back", OnText = "Back (2X)", OffText = "Back (1X)", OnIconName = BitIconName.RewindTwoX, OffIconName = BitIconName.Rewind },
new() { Key = "play", OnText = "Resume", OffText = "Play", OnIconName = BitIconName.PlayResume, OffIconName = BitIconName.Play },
new() { Key = "forward", OnText = "Forward (2X)", OffText = "Forward (1X)", OnIconName = BitIconName.FastForwardTwoX, OffIconName = BitIconName.FastForward, ReversedIcon = true }
];
private List fixedSingleItems =
[
new() { Key = "low", Text = "Low" },
new() { Key = "medium", Text = "Medium" },
new() { Key = "high", Text = "High" }
];
```
\n**Vertical**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Events**:
```razor
eventsItems =
[
new() { Text = "Increase", IconName = BitIconName.Add },
new() { Text = "Reset", IconName = BitIconName.Reset },
new() { Text = "Decrease", IconName = BitIconName.Remove }
];
protected override void OnInitialized()
{
eventsItems[0].OnClick = _ => { clickCounter++; StateHasChanged(); };
eventsItems[1].OnClick = _ => { clickCounter = 0; StateHasChanged(); };
eventsItems[2].OnClick = _ => { clickCounter--; StateHasChanged(); };
}
```
\n**FullWidth**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Multiple**:
```razor
```
```csharp
private IEnumerable? formatKeys = ["bold"];
private List formatItems =
[
new() { Key = "bold", Text = "Bold", IconName = BitIconName.Bold },
new() { Key = "italic", Text = "Italic", IconName = BitIconName.Italic },
new() { Key = "underline", Text = "Underline", IconName = BitIconName.Underline }
];
private readonly string[] maxDefaultKeys = ["bold"];
private List maxToggleItems =
[
new() { Key = "bold", Text = "Bold", IconName = BitIconName.Bold },
new() { Key = "italic", Text = "Italic", IconName = BitIconName.Italic },
new() { Key = "underline", Text = "Underline", IconName = BitIconName.Underline }
];
private readonly string[] fixedDefaultKeys = ["bold"];
private List fixedToggleItems =
[
new() { Key = "bold", Text = "Bold", IconName = BitIconName.Bold },
new() { Key = "italic", Text = "Italic", IconName = BitIconName.Italic },
new() { Key = "underline", Text = "Underline", IconName = BitIconName.Underline }
];
```
\n**Justified**:
```razor
```
```csharp
private List justifiedItems =
[
new() { Text = "Day" }, new() { Text = "Week" }, new() { Text = "A whole month" }
];
```
\n**Detached**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Rounded**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Overflow**:
```razor
```
```csharp
private List overflowItems =
[
new() { Text = "January" }, new() { Text = "February" }, new() { Text = "March" },
new() { Text = "April" }, new() { Text = "May" }, new() { Text = "June" },
new() { Text = "July" }, new() { Text = "August" }, new() { Text = "September" }
];
```
\n**SelectionIndicator**:
```razor
```
```csharp
private List indicatorSingleItems =
[
new() { Key = "list", Text = "List", IconName = BitIconName.BulletedList },
new() { Key = "grid", Text = "Grid", IconName = BitIconName.GridViewMedium },
new() { Key = "tile", Text = "Tile", IconName = BitIconName.Tiles }
];
private readonly string[] indicatorDefaultKeys = ["name", "size"];
private List indicatorMultipleItems =
[
new() { Key = "name", Text = "Name" },
new() { Key = "size", Text = "Size" },
new() { Key = "date", Text = "Date" }
];
```
\n**Loading & Badge**:
```razor
```
```csharp
private List loadingItems =
[
new() { Key = "save", Text = "Save", IconName = BitIconName.Save },
new() { Key = "sync", Text = "Sync", IconName = BitIconName.Sync },
new() { Key = "publish", Text = "Publish", IconName = BitIconName.PublishContent }
];
private List badgeItems =
[
new() { Text = "Inbox", IconName = BitIconName.Inbox, Badge = "12" },
new() { Text = "Drafts", IconName = BitIconName.Edit, Badge = "3" },
new() { Text = "Sent", IconName = BitIconName.Send }
];
private async Task HandleLoadingClick(BitButtonGroupItem item)
{
item.IsLoading = true;
StateHasChanged();
await Task.Delay(2000);
item.IsLoading = false;
StateHasChanged();
}
```
\n**Links**:
```razor
```
```csharp
private List linkItems =
[
new() { Text = "Home", IconName = BitIconName.Home, Href = "/" },
new() { Text = "Components", IconName = BitIconName.Puzzle, Href = "/components" },
new() { Text = "GitHub", IconName = BitIconName.OpenInNewWindow, Href = "https://github.com/bitfoundation/bitplatform", Target = "_blank" }
];
```
\n**Templates**:
```razor
@item.Text
@code {
private readonly RenderFragment editItemTemplate = item =>
@
@item.Text
;
}
```
```csharp
private List templateItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { Text = "Edit", IconName = BitIconName.Edit },
new() { Text = "Delete", IconName = BitIconName.Delete }
];
private List itemTemplateItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { Text = "Edit" },
new() { Text = "Delete", IconName = BitIconName.Delete }
];
protected override void OnInitialized()
{
itemTemplateItems[1].Template = editItemTemplate;
}
```
\n**Tooltips**:
```razor
```
```csharp
private List titleItems =
[
new() { Text = "Add", IconName = BitIconName.Add, Title = "Add a new record", AriaLabel = "Add" },
new() { Text = "Edit", IconName = BitIconName.Edit, Title = "Edit the selected record", AriaLabel = "Edit" },
new() { Text = "Delete", IconName = BitIconName.Delete, Title = "Delete the selected record", AriaLabel = "Delete" }
];
private List toggleTitleItems =
[
new()
{
Key = "mute",
AriaLabel = "Mute",
OnText = "Muted",
OffText = "Mute",
OnTitle = "The sound is muted, click to unmute",
OffTitle = "Click to mute the sound",
OnIconName = BitIconName.Volume0,
OffIconName = BitIconName.Volume3
},
new()
{
Key = "repeat",
AriaLabel = "Repeat",
OnText = "Repeating",
OffText = "Repeat",
OnTitle = "Repeat is on, click to turn it off",
OffTitle = "Click to repeat the playlist",
OnIconName = BitIconName.RepeatOne,
OffIconName = BitIconName.RepeatAll
}
];
```
\n**Accessibility**:
```razor
Focus the group
```
```csharp
private BitButtonGroup? focusGroup;
// FocusAsync returns a ValueTask, which an EventCallback cannot be assigned directly.
private async Task FocusTheGroup()
{
if (focusGroup is not null) await focusGroup.FocusAsync();
}
private List a11yItems =
[
new() { Key = "start", Text = "Start", IconName = BitIconName.AlignLeft, AriaLabel = "Align start" },
new() { Key = "center", Text = "Center", IconName = BitIconName.AlignCenter, AriaLabel = "Align center" },
new() { Key = "end", Text = "End", IconName = BitIconName.AlignRight, AriaLabel = "Align end" }
];
private List selectOnFocusItems =
[
new() { Key = "start", Text = "Start", IconName = BitIconName.AlignLeft, AriaLabel = "Align start" },
new() { Key = "center", Text = "Center", IconName = BitIconName.AlignCenter, AriaLabel = "Align center" },
new() { Key = "end", Text = "End", IconName = BitIconName.AlignRight, AriaLabel = "Align end" }
];
private List disabledItems =
[
new() { Text = "Add" }, new() { Text = "Edit", IsEnabled = false }, new() { Text = "Delete" }
];
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Cascading parameters**:
```razor
```
```csharp
private readonly BitButtonGroupParams[] buttonGroupParams =
[
new()
{
Variant = BitVariant.Outline,
Rounded = true,
Justified = true,
}
];
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Color**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**External Icons**:
```razor
```
```csharp
private List externalIconItems =
[
new() { Text = "Add", Icon = "fa-solid fa-plus" },
new() { Text = "Edit", Icon = BitIconInfo.Css("fa-solid fa-pen") },
new() { Text = "Delete", Icon = BitIconInfo.Fa("solid trash") }
];
```
\n**Size**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
```
\n**Style & Class**:
```razor
```
```csharp
private List basicItems =
[
new() { Text = "Add" }, new() { Text = "Edit" }, new() { Text = "Delete" }
];
private List cssVarItems =
[
new() { Text = "Add", IconName = BitIconName.Add },
new() { Text = "Edit", IconName = BitIconName.Edit },
new()
{
Text = "Delete",
IconName = BitIconName.Delete,
Style = "--bit-ButtonGroup-color: var(--bit-clr-err-text);" +
"--bit-ButtonGroup-background: var(--bit-clr-err);" +
"--bit-ButtonGroup-hover-background: var(--bit-clr-err-hover);",
},
];
private List styleClassItems =
[
new()
{
Text = "Styled",
Style = "color: tomato; border-color: brown; background-color: peachpuff;",
IconName = BitIconName.Brush,
},
new()
{
Text = "Classed",
Class = "custom-item",
IconName = BitIconName.FormatPainter,
}
];
```
Toggle key: @toggleKey
Changed toggle: @onChangeToggleItem?.Key , @onChangeToggleItem?.IsToggled
Clicked item: @clickedItem
Click count: @clickCounter
```
```csharp
private int clickCounter;
private string? clickedItem;
private ListToggle keys: @string.Join(", ", formatKeys ?? [])
Disabled: