Inputs
ChoiceGroup
ChoiceGroup, also known as Radio or RadioGroup, lets people select a single value from two or more mutually exclusive choices. Reach for it when all the options are worth showing at once (roughly two to seven of them) and the choice matters enough to stay visible; a Dropdown suits longer lists, and a Checkbox suits choices that are not mutually exclusive. It renders native radio inputs, so the browser provides the full keyboard behavior for free: the whole group is a single tab stop that lands on the checked item, and the arrow keys move the selection with wrapping and RTL awareness. On top of that it adds a group label and helper text, per-item icons, images, prefixes and descriptions, vertical, horizontal and full width layouts, and templates at every level, all through three interchangeable item APIs.
Notes
The BitChoiceGroup is a Multi-API component
which can accept the list of Items in 3 different ways:
1. The BitChoiceGroupItem class
2. A Custom Generic class
3. The BitChoiceGroupOption component
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Disabled
Images and Icons
Horizontal
LabelPosition
LabelTemplate
Item templates
Binding
Validation
Item descriptions
ReadOnly
Gap
Prefix & Suffix
Events
Dynamic items
Group description
FullWidth
Item title
AutoFocus
Color
External Icons
Size
Style & Class
RTL
API
Every parameter, public member, sub-class and enum this component exposes.
BitChoiceGroup parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabelledBy | string? | null | Id of an element to use as the aria label for the ChoiceGroup. |
| AutoFocus | bool | false | Determines if the ChoiceGroup is auto focused on first render, focusing its checked item, or its first enabled item when nothing is checked. Nothing is focused when the ChoiceGroup is read-only or the target item is disabled. |
| AutoReorderOptions | bool | false | Keeps the assigned Index of each option in sync with the markup order of the options, even when an option is added, removed, or reordered conditionally after the first render. |
| ChildContent | RenderFragment? | null | The content of the ChoiceGroup, a list of BitChoiceGroupOption components. |
| Classes | BitChoiceGroupClassStyles? | null | Custom CSS classes for different parts of the BitChoiceGroup. |
| Color | BitColor? | null | The general color of the ChoiceGroup. |
| Description | string? | null | The description (helper text) of the ChoiceGroup, rendered under its label. The group references it through its aria-describedby, so screen readers announce it along with the name of the group. |
| DescriptionTemplate | RenderFragment? | null | Custom RenderFragment for the description (helper text) of the ChoiceGroup. Takes precedence over Description when both are set. |
| FullWidth | bool | false | Expands the ChoiceGroup to the full width of its container instead of hugging its widest item. In the horizontal layout the items also share that width equally. |
| Gap | string? | null | The gap between the items of the ChoiceGroup. |
| Horizontal | bool | false | Renders the items in the ChoiceGroup horizontally. |
| Inline | bool | false | Renders the icons and images in a single line with the items in the ChoiceGroup. |
| Items | IEnumerable<TItem> | new List<TItem>() | Sets the data source that populates the items of the list. |
| ItemLabelTemplate | RenderFragment<TItem>? | Used to customize the label for the Item Label content. | |
| ItemPrefixTemplate | RenderFragment<TItem>? | Used to add a prefix to each item. | |
| ItemSuffixTemplate | RenderFragment<TItem>? | null | Used to add a suffix to each item, rendered after the content of the item. |
| ItemTemplate | RenderFragment<TItem>? | null | Used to customize the label for the Item content. |
| Label | string? | null | The label for the ChoiceGroup. |
| LabelPosition | BitLabelPosition? | null | The position of the content of each item relative to its radio circle. Defaults to End, which renders the circle first and the content after it. Items rendered as image or icon tiles lay their own content out and ignore this parameter. |
| LabelTemplate | RenderFragment? | null | Custom RenderFragment for the label of the ChoiceGroup. |
| Name | string? | null | The name shared by the radio inputs of the items, which is what groups them into a single logical radio group. When not set, a unique name is generated for the ChoiceGroup. |
| NameSelectors | BitChoiceGroupNameSelectors<TItem, TValue>? | null | Names and selectors of the custom input type properties. |
| NoCircle | bool | false | Removes the circle from the start of each item. |
| OnBlur | EventCallback<TItem> | Callback for when an item of the ChoiceGroup loses focus. | |
| OnChange | EventCallback<TValue?> | Callback for when the selected value changes. | |
| OnClick | EventCallback<TItem> | Callback for when an enabled item is clicked, even the already selected one. | |
| OnFocus | EventCallback<TItem> | Callback for when an item of the ChoiceGroup receives focus. | |
| Options | RenderFragment? | null | Alias of ChildContent. |
| ReadOnly | bool | false | Prevents changing the value of the ChoiceGroup while keeping its normal (non-disabled) appearance. |
| Required | bool | false | Makes the ChoiceGroup required and adds the required asterisk to its label. |
| Size | BitSize? | null | The size of the BitChoiceGroup. |
| Styles | BitChoiceGroupClassStyles? | null | Custom CSS styles for different parts of the BitChoiceGroup. |
BitInputBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| DefaultValue | TValue? | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. |
| DisplayName | string? | null | Gets or sets the display name for this field. |
| InputHtmlAttributes | IReadOnlyDictionary<string, object>? | null | Gets or sets a collection of additional attributes that will be applied to the created element. |
| Name | string? | null | Gets or sets the name of the element. Allows access by name from the associated form. |
| NoValidate | bool | false | Disables the validation of the input. |
| OnChange | EventCallback<TValue?> | Callback for when the input value changes. | |
| ReadOnly | bool | false | Makes the input read-only. |
| Required | bool | false | Makes the input required. |
| Value | TValue? | null | Gets or sets the value of the input. This should be used with two-way binding. |
BitInputBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| InputElement | ElementReference | The ElementReference of the input element. | |
| FocusAsync() | () => ValueTask | Gives focus to the input element. | |
| FocusAsync(bool preventScroll) | (bool preventScroll) => ValueTask | Gives focus to the input element. |
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. |
BitChoiceGroupItem properties
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | AriaLabel attribute for the BitChoiceGroup item. |
| Class | string? | null | CSS class attribute for the BitChoiceGroup item. |
| Description | string? | null | The secondary text to show under the text of the BitChoiceGroup item. |
| Id | string? | null | Id attribute of the BitChoiceGroup item. |
| IsEnabled | bool | true | Whether the BitChoiceGroup item is enabled. |
| Icon | BitIconInfo? | null | The icon to show as content of the BitChoiceGroup item. Takes precedence over IconName when both are set. |
| IconName | string? | null | The icon name (built-in Fluent UI) to show as content of the BitChoiceGroup item. |
| ImageSrc | string? | null | The image address to show as the content of the BitChoiceGroup item. |
| ImageAlt | string? | null | The alt attribute for the image of the BitChoiceGroup item. |
| ImageSize | BitImageSize? | null | Provides Width and Height for the image of the BitChoiceGroup item. |
| Prefix | string? | null | The text to show as a prefix for the BitChoiceGroup item. |
| SelectedImageSrc | string? | null | Provides a new image for the selected state of the image of the BitChoiceGroup item. |
| Style | string? | null | CSS style attribute for the BitChoiceGroup item. |
| Suffix | string? | null | The text to show as a suffix for the BitChoiceGroup item, rendered after its content. |
| Template | RenderFragment<BitChoiceGroupItem<TValue>>? | null | The custom template for the BitChoiceGroup item. |
| Text | string? | null | Text to show as the content of BitChoiceGroup item. |
| Title | string? | null | The title attribute (the native tooltip) of the BitChoiceGroup item. Supplementary text only: content that has to reach every user belongs in Text (or a template) or in Description, both of which are visible and exposed to assistive technology. AriaLabel is not an alternative: it only replaces the accessible name for assistive technology and is never visible. |
| Value | TValue? | null | The value returned when BitChoiceGroup item is checked. |
| Index | int | 0 | Index of the BitChoiceGroup item. This property's value is set by the component at render. |
| IsSelected | bool | false | Determines if the item is selected. This property's value is assigned by the component. |
BitChoiceGroupOption properties
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | AriaLabel attribute for the BitChoiceGroup option. |
| Class | string? | null | CSS class attribute for the BitChoiceGroup option. |
| Description | string? | null | The secondary text to show under the text of the BitChoiceGroup option. |
| Id | string? | null | Id attribute of the BitChoiceGroup option. |
| IsEnabled | bool | true | Whether the BitChoiceGroup option is enabled. |
| Icon | BitIconInfo? | null | The icon to show as content of the BitChoiceGroup option. Takes precedence over IconName when both are set. |
| IconName | string? | null | The icon name (built-in Fluent UI) to show as content of the BitChoiceGroup option. |
| ImageSrc | string? | null | The image address to show as the content of the BitChoiceGroup option. |
| ImageAlt | string? | null | The alt attribute for the image of the BitChoiceGroup option. |
| ImageSize | BitImageSize? | null | Provides Width and Height for the image of the BitChoiceGroup option. |
| Prefix | string? | null | The text to show as a prefix for the BitChoiceGroup option. |
| SelectedImageSrc | string? | null | Provides a new image for the selected state of the image of the BitChoiceGroup option. |
| Style | string? | null | CSS style attribute for the BitChoiceGroup option. |
| Suffix | string? | null | The text to show as a suffix for the BitChoiceGroup option, rendered after its content. |
| Template | RenderFragment<BitChoiceGroupOption<TValue>>? | null | The custom template for the BitChoiceGroup option. |
| Text | string? | null | Text to show as the content of BitChoiceGroup option. |
| Title | string? | null | The title attribute (the native tooltip) of the BitChoiceGroup option. Supplementary text only: content that has to reach every user belongs in Text (or a template) or in Description, both of which are visible and exposed to assistive technology. AriaLabel is not an alternative: it only replaces the accessible name for assistive technology and is never visible. |
| Value | TValue? | null | The value returned when BitChoiceGroup option is checked. |
| Index | int | 0 | Index of the BitChoiceGroup option. This property's value is set by the component at render. |
| IsSelected | bool | false | Determines if the option is selected. This property's value is assigned by the component. |
BitChoiceGroupNameSelectors<TItem, TValue> properties
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.AriaLabel)) | AriaLabel attribute for the BitChoiceGroup option. |
| Class | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Class)) | CSS class attribute for the BitChoiceGroup option. |
| Description | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Description)) | The secondary text to show under the text of the BitChoiceGroup option. |
| Id | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Id)) | Id attribute of the BitChoiceGroup option. |
| IsEnabled | BitNameSelectorPair<TItem, bool> | new(nameof(BitChoiceGroupItem<TValue>.IsEnabled)) | Whether the BitChoiceGroup option is enabled. |
| Icon | BitNameSelectorPair<TItem, BitIconInfo?> | new(nameof(BitChoiceGroupItem<TValue>.Icon)) | Icon field name and selector of the custom input class. |
| IconName | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.IconName)) | IconName field name and selector of the custom input class. |
| ImageSrc | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.ImageSrc)) | The image address to show as the content of the BitChoiceGroup option. |
| ImageAlt | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.ImageAlt)) | The alt attribute for the image of the BitChoiceGroup option. |
| ImageSize | BitNameSelectorPair<TItem, BitImageSize?> | new(nameof(BitChoiceGroupItem<TValue>.ImageSize)) | Provides Width and Height for the image of the BitChoiceGroup option. |
| Prefix | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Prefix)) | The text to show as a prefix for the BitChoiceGroup option. |
| SelectedImageSrc | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.SelectedImageSrc)) | Provides a new image for the selected state of the image of the BitChoiceGroup option. |
| Style | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Style)) | CSS style attribute for the BitChoiceGroup option. |
| Suffix | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Suffix)) | The text to show as a suffix for the BitChoiceGroup option, rendered after its content. |
| Template | BitNameSelectorPair<TItem, RenderFragment<TItem>?> | new(nameof(BitChoiceGroupItem<TValue>.Template)) | Template field name and selector of the custom input class. |
| Text | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Text)) | Text to show as the content of BitChoiceGroup option. |
| Title | BitNameSelectorPair<TItem, string?> | new(nameof(BitChoiceGroupItem<TValue>.Title)) | The title attribute (the native tooltip) of the BitChoiceGroup option. |
| Value | BitNameSelectorPair<TItem, TValue?> | new(nameof(BitChoiceGroupItem<TValue>.Value)) | The value returned when BitChoiceGroup option is checked. |
| Index | string | nameof(BitChoiceGroupItem<TValue>.Index) | The Index field name of the custom input class. This property's value is set by the component at render. |
| IsSelected | string | nameof(BitChoiceGroupItem<TValue>.IsSelected) | The IsSelected field name of the custom input class. This property's value is assigned by the component. |
BitChoiceGroupClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitChoiceGroup. |
| LabelContainer | string? | null | Custom CSS classes/styles for the label container of the BitChoiceGroup. |
| Label | string? | null | Custom CSS classes/styles for the label of the BitChoiceGroup. |
| Description | string? | null | Custom CSS classes/styles for the description (helper text) of the BitChoiceGroup. |
| Container | string? | null | Custom CSS classes/styles for the container of the BitChoiceGroup. |
| ItemChecked | string? | null | Custom CSS classes/styles for the checked item of the BitChoiceGroup. |
| ItemContainer | string? | null | Custom CSS classes/styles for the container of each item of the BitChoiceGroup. |
| ItemLabel | string? | null | Custom CSS classes/styles for the label of each item of the BitChoiceGroup. |
| ItemImageContainer | string? | null | Custom CSS classes/styles for the image container of each item of the BitChoiceGroup. |
| ItemImageWrapper | string? | null | Custom CSS classes/styles for the image wrapper of each item of the BitChoiceGroup. |
| ItemRadioButton | string? | null | Custom CSS classes/styles for the radio button of each item of the BitChoiceGroup. |
| ItemImage | string? | null | Custom CSS classes/styles for the image of each item of the BitChoiceGroup. |
| ItemIconWrapper | string? | null | Custom CSS classes/styles for the icon wrapper of each item of the BitChoiceGroup. |
| ItemIcon | string? | null | Custom CSS classes/styles for the icon of each item of the BitChoiceGroup. |
| ItemPrefix | string? | null | Custom CSS classes/styles for the prefix of each item of the BitChoiceGroup. |
| ItemSuffix | string? | null | Custom CSS classes/styles for the suffix of each item of the BitChoiceGroup. |
| ItemTextWrapper | string? | null | Custom CSS classes/styles for the text wrapper of each item of the BitChoiceGroup. |
| ItemText | string? | null | Custom CSS classes/styles for the text of each item of the BitChoiceGroup. |
| ItemDescription | string? | null | Custom CSS classes/styles for the description of each item of the BitChoiceGroup. |
BitIconInfo properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Name | string? | null | Gets or sets the name of the icon. |
| BaseClass | string? | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. |
| Prefix | string? | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. |
BitColor enum
| Name | Value | Description |
|---|---|---|
| Primary | 0 | Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
| PrimaryBackground | 8 | Primary background color. |
| SecondaryBackground | 9 | Secondary background color. |
| TertiaryBackground | 10 | Tertiary background color. |
| PrimaryForeground | 11 | Primary foreground color. |
| SecondaryForeground | 12 | Secondary foreground color. |
| TertiaryForeground | 13 | Tertiary foreground color. |
| PrimaryBorder | 14 | Primary border color. |
| SecondaryBorder | 15 | Secondary border color. |
| TertiaryBorder | 16 | Tertiary border color. |
BitLabelPosition enum
| Name | Value | Description |
|---|---|---|
| Top | 0 | Renders the content above the radio circle. |
| End | 1 | Renders the content after the radio circle. This is the default. |
| Bottom | 2 | Renders the content below the radio circle. |
| Start | 3 | Renders the content before the radio circle and aligns the items to the end of the group. |
BitSize enum
| Name | Value | Description |
|---|---|---|
| Small | 0 | The small size choice group. |
| Medium | 1 | The medium size choice group. |
| Large | 2 | The large size choice group. |
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.