# Button
**Also known as:** CompoundButton, IconButton
## Description
BitButton triggers an action or navigates when the user activates it. It renders a native button, or an anchor when an Href is provided, and offers Fill, Outline, and Text variants across a full palette of semantic colors and sizes. It supports start/end icons, an optional secondary line of text, and loading states that stack a spinner over the content so the box keeps the size and the accessible name it had before the click. It also stretches to the full width of its container, or leaves the flow entirely as a floating (FAB) button pinned to the viewport or to its container and draggable by pointer or by the arrow keys, and a BitParams ancestor carrying a BitButtonParams sets the defaults of every button in a subtree. Its defaults are accessibility-first: disabled buttons stay focusable through aria-disabled, an icon-only button keeps its label as its accessible name, the loading label is announced from a live region rather than folded into the button's name, an external link gets rel='noopener' on its own, and every state is re-established in system colors under Windows High Contrast.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AllowDisabledFocus | `bool` | true | Keeps the disabled button focusable and discoverable by screen readers, rendering aria-disabled instead of the native disabled attribute when Disabled is true, preserving a consistent tab order. Set it to false to render the native disabled attribute and remove the button from the tab order. |
| AriaDescription | `string?` | null | Detailed description of the button for the benefit of screen readers, rendered as visually hidden text beside the button and read after its name, not as part of it. An aria-describedby written on the component by hand is kept and this description is added to it, since the attribute is a list of ids. |
| AriaHidden | `bool` | false | If true, adds an aria-hidden attribute instructing screen readers to ignore the button. |
| AutoFocus | `bool` | false | If true, the button automatically receives focus when the page renders (rendered as the autofocus attribute). |
| AutoLoading | `bool` | false | If true, enters the loading state automatically while awaiting the OnClick event and prevents subsequent clicks by default. The state is left even when the handler throws. |
| ButtonType | `BitButtonType?` | null | The type of the button element; defaults to submit inside an EditForm otherwise button. |
| ChildContent | `RenderFragment?` | null | The content of primary section of the button. |
| Classes | `BitButtonClassStyles?` | null | Custom CSS classes for different parts of the button. |
| Color | `BitColor?` | null | The general color of the button. An explicit value wins over the --bit-Button-* color variables (the disabled and focus colors included); left unset, the button is primary unless they say otherwise. |
| Download | `string?` | null | The value of the download attribute of the link rendered by the button when Href is provided. Instructs the browser to download the linked resource instead of navigating to it, using the provided value as the file name. |
| Draggable | `bool` | false | Makes the Float/FloatAbsolute button draggable on the page, by pointer or with the arrow keys while it has the focus; ignored when neither is set. |
| FixedColor | `bool` | false | Preserves the foreground color of the button through hover and focus. |
| Float | `bool` | false | Enables floating behavior for the button, allowing it to be positioned relative to the viewport. |
| FloatAbsolute | `bool` | false | Enables floating behavior for the button, allowing it to be positioned relative to its container. |
| FloatOffset | `string?` | null | Specifies the offset of the floating button: any CSS length (1rem, 5%, a calc()), or a bare number, which is read as pixels. |
| FloatPosition | `BitPosition?` | null | Specifies the position of the floating button. |
| FormId | `string?` | null | The id of the form element that the button is associated with (rendered as the form attribute). Allows a submit/reset button to be placed outside of its form element. |
| FullWidth | `bool` | false | Expand the button width to 100% of the available width. |
| Href | `string?` | null | The value of the href attribute of the link rendered by the button. If provided, the component will be rendered as an anchor tag instead of button. |
| Icon | `BitIconInfo?` | null | Gets or sets the icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | `string?` | null | Gets or sets the name of the icon to display from the built-in Fluent UI icons. |
| IconOnly | `bool` | false | Determines that only the icon should be rendered; the text is kept as screen-reader-only content, so the button keeps its accessible name unless an AriaLabel replaces it. |
| IconPlacement | `BitPlacement?` | null | Gets or sets the position of the icon relative to the component's content. The default value is Start. Only Start and End are honoured, and they follow the reading direction; any other value leaves the icon where Start would put it. |
| IconUrl | `string?` | null | The url of the custom icon to render inside the button. |
| IsLoading | `bool` | false | Determines whether the button is in loading mode or not. The spinner is stacked over the content rather than replacing it, so the box keeps its size and its accessible name, and the button reports aria-busy - plus aria-disabled unless Reclickable is set, since the click is refused. |
| LoadingDelay | `int` | 0 | The delay in milliseconds before the spinner appears after the button enters the loading state, so an operation that finishes inside the delay never flashes one. Only the visuals wait: the click is blocked and aria-busy is rendered as soon as the loading starts. |
| LoadingLabel | `string?` | null | The loading label text to show next to the spinner icon. It is also announced by assistive technologies from a live region beside the button, so that it is heard as a change of state instead of changing the name of the button itself. |
| LoadingLabelPlacement | `BitPlacement` | BitPlacement.End | The position of the loading Label in regards to the spinner icon. Only Top, Bottom, Start and End are honoured; any other value falls back to the default. |
| LoadingTemplate | `RenderFragment?` | null | The custom template used to replace the default spinner and loading label inside the button in the loading state. Like the spinner it replaces, it is hidden from assistive technologies; use LoadingLabel for what should be announced. |
| NoWrap | `bool` | false | Keeps each line of the button's text on a single line and ends it with an ellipsis where it does not fit. |
| OnClick | `EventCallback<bool>` | | Raised when the button is clicked; receives a bool indicating the current loading state. |
| PrimaryTemplate | `RenderFragment?` | | The content of the primary section of the button (alias of the ChildContent). |
| Reclickable | `bool` | false | Enables re-clicking while the button is in the loading state, which also keeps it reported and drawn as an available control instead of a busy and disabled one. |
| Rel | `BitLinkRels?` | null | Sets the rel attribute for link-rendered buttons when Href is a non-anchor URL; ignored for empty or hash-only hrefs. |
| Rounded | `bool` | false | Renders the button with fully rounded (pill shaped) corners, and an icon-only one as a circle. It wins over --bit-Button-radius, which restyles the default corner and not a rounded one. |
| SecondaryText | `string?` | null | The text of the secondary section of the button. |
| SecondaryTemplate | `RenderFragment?` | | The custom template for the secondary section of the button. |
| Size | `BitSize?` | null | Sets the preset size for typography and padding of the button. An explicit value wins over the --bit-Button-* size variables (padding, min-height, gap, font, icon and spinner sizes); left unset, the button is medium unless they say otherwise. |
| StopPropagation | `bool` | false | If true, stops the click event from bubbling up to the parent elements. |
| Styles | `BitButtonClassStyles?` | null | Custom inline styles for different parts of the button. |
| Target | `string?` | null | Specifies target attribute of the link when the button renders as an anchor (by providing the Href parameter). When set to _blank and no opener-related Rel is provided, noopener is added to the rel automatically for security. |
| Title | `string?` | null | The tooltip to show when the mouse is placed on the button. |
| Variant | `BitVariant?` | null | The visual variant of the button. |
| 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. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| 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. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| 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 focus to the root element of the button. |
| 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. |
### 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. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
### 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). |
### BitPlacement Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Top | 0 | The top edge. |
| Bottom | 1 | The bottom edge. |
| Start | 2 | The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top. |
| End | 3 | The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom. |
| Left | 4 | The left edge, in both reading directions. |
| Right | 5 | The right edge, in both reading directions. |
| Center | 6 | The middle of the axis, against neither edge. |
| TopAndBottom | 7 | Both edges of the block axis at once. |
| StartAndEnd | 8 | Both edges of the inline axis at once, following the reading direction the way Start and End do. |
### BitLinkRels Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Alternate | 1 | Provides a link to an alternate representation of the document. (i.e. print page, translated or mirror) |
| Author | 2 | Provides a link to the author of the document. |
| Bookmark | 4 | Permanent URL used for bookmarking. |
| External | 8 | Indicates that the referenced document is not part of the same site as the current document. |
| Help | 16 | Provides a link to a help document. |
| License | 32 | Provides a link to licensing information for the document. |
| Next | 64 | Provides a link to the next document in the series. |
| NoFollow | 128 | Links to an unendorsed document, like a paid link. ("NoFollow" is used by Google, to specify that the Google search spider should not follow that link) |
| NoOpener | 256 | Requires that any browsing context created by following the hyperlink must not have an opener browsing context. |
| NoReferrer | 512 | Makes the referrer unknown. No referrer header will be included when the user clicks the hyperlink. |
| Prev | 1024 | The previous document in a selection. |
| Search | 2048 | Links to a search tool for the document. |
| Tag | 4096 | A tag (keyword) for the current document. |
| Me | 8192 | Indicates that the linked document represents the person who owns the current content. (used for identity verification) |
| Opener | 16384 | Requires that any browsing context created by following the hyperlink keeps its opener browsing context. (reverses the implicit noopener modern browsers apply to _blank targets) |
| PrivacyPolicy | 32768 | Links to the privacy policy that applies to the current document. (rendered as privacy-policy) |
| Sponsored | 65536 | Marks the link as an advertisement or paid placement, so search engines do not count it as an organic endorsement. |
| TermsOfService | 131072 | Links to the terms of service that apply to the current document. (rendered as terms-of-service) |
| Ugc | 262144 | Marks the link as user-generated content, like forum posts or comments, for search engines. |
### BitPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| TopLeft | 0 | The top left corner, in both reading directions. |
| TopCenter | 1 | The top edge, centered horizontally. |
| TopRight | 2 | The top right corner, in both reading directions. |
| TopStart | 3 | The top edge, on the side the reading direction starts from. |
| TopEnd | 4 | The top edge, on the side the reading direction ends at. |
| CenterLeft | 5 | The left edge, centered vertically, in both reading directions. |
| Center | 6 | Centered both ways. |
| CenterRight | 7 | The right edge, centered vertically, in both reading directions. |
| CenterStart | 8 | Centered vertically, on the side the reading direction starts from. |
| CenterEnd | 9 | Centered vertically, on the side the reading direction ends at. |
| BottomLeft | 10 | The bottom left corner, in both reading directions. |
| BottomCenter | 11 | The bottom edge, centered horizontally. |
| BottomRight | 12 | The bottom right corner, in both reading directions. |
| BottomStart | 13 | The bottom edge, on the side the reading direction starts from. |
| BottomEnd | 14 | The bottom edge, on the side the reading direction ends at. |
### 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
### BitButtonClassStyles Properties
Defines per-part CSS class/style values for BitButton.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom class or style applied to the root element. |
| Icon | `string?` | null | Custom class or style applied to the icon element (the glyph, or the image rendered for IconUrl). |
| Container | `string?` | null | Custom class or style applied to the column that holds the primary and secondary lines of text. |
| Primary | `string?` | null | Custom class or style applied to the primary line of text. |
| Secondary | `string?` | null | Custom class or style applied to the secondary line of text. |
| HiddenContent | `string?` | null | Custom class or style applied to the wrapper of the content that keeps the button size while it is hidden in the loading state. |
| LoadingContainer | `string?` | null | Custom class or style applied to the container of the spinner and its label in the loading state. |
| Spinner | `string?` | null | Custom class or style applied to the loading spinner element. |
| LoadingLabel | `string?` | null | Custom class or style applied to the loading label element. |
### 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 to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-Button-color` | Per variant: --bit-clr-pri-text when filled, --bit-clr-pri otherwise | Foreground (text and icon) in the rest state. FixedColor holds this color of a Fill button through hover and press as well; an Outline or Text button with FixedColor wears its hover color instead. The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-color, --bit-Button-outline-color and --bit-Button-text-color are read ahead of it. |
| `--bit-Button-background` | --bit-clr-pri when filled, transparent otherwise | Background in the rest state. The Color parameter wins over it in Fill; the transparent background of Outline and Text is its alone. Shared by the three variants: --bit-Button-fill-background, --bit-Button-outline-background and --bit-Button-text-background are read ahead of it. |
| `--bit-Button-border-color` | --bit-clr-pri when filled or outlined, transparent otherwise | Border color in the rest state. The border is drawn on every variant, so a Text button can take one without changing its size. The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Button-fill-border-color, --bit-Button-outline-border-color and --bit-Button-text-border-color are read ahead of it. |
| `--bit-Button-hover-color` | --bit-clr-pri-text, and the rest color for the Fill variant | Foreground while hovered (pointer devices only), and the one an Outline or Text button with FixedColor wears in every state. The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-hover-color, --bit-Button-outline-hover-color and --bit-Button-text-hover-color are read ahead of it. |
| `--bit-Button-hover-background` | --bit-clr-pri-hover | Background while hovered (pointer devices only). The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-hover-background, --bit-Button-outline-hover-background and --bit-Button-text-hover-background are read ahead of it. |
| `--bit-Button-hover-border-color` | The rest border color, and the hover background for the Fill variant | Border color while hovered (pointer devices only). The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Button-fill-hover-border-color, --bit-Button-outline-hover-border-color and --bit-Button-text-hover-border-color are read ahead of it. |
| `--bit-Button-active-color` | As the hover foreground | Foreground while pressed. The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-active-color, --bit-Button-outline-active-color and --bit-Button-text-active-color are read ahead of it. |
| `--bit-Button-active-background` | --bit-clr-pri-active | Background while pressed. The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-active-background, --bit-Button-outline-active-background and --bit-Button-text-active-background are read ahead of it. |
| `--bit-Button-active-border-color` | As the hover border color | Border color while pressed. The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Button-fill-active-border-color, --bit-Button-outline-active-border-color and --bit-Button-text-active-border-color are read ahead of it. |
| `--bit-Button-disabled-color` | --bit-clr-pri-dis-text | Foreground when disabled. It also draws the focus ring of a disabled button that AllowDisabledFocus keeps in the tab order. The Color parameter wins over it. Shared by the three variants: --bit-Button-fill-disabled-color, --bit-Button-outline-disabled-color and --bit-Button-text-disabled-color are read ahead of it. |
| `--bit-Button-disabled-background` | --bit-clr-pri-dis when filled, transparent otherwise | Background when disabled. The Color parameter wins over it in Fill; the transparent background of Outline and Text is its alone. Shared by the three variants: --bit-Button-fill-disabled-background, --bit-Button-outline-disabled-background and --bit-Button-text-disabled-background are read ahead of it. |
| `--bit-Button-disabled-border-color` | As the disabled background | Border color when disabled. The Color parameter wins over it, except over the transparent border of Text. Shared by the three variants: --bit-Button-fill-disabled-border-color, --bit-Button-outline-disabled-border-color and --bit-Button-text-disabled-border-color are read ahead of it. |
| `--bit-Button-fill-color` | --bit-Button-color | Foreground (text and icon) in the rest state of a Fill button alone, read ahead of --bit-Button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-background` | --bit-Button-background | Background in the rest state of a Fill button alone, read ahead of --bit-Button-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-border-color` | --bit-Button-border-color | Border color in the rest state of a Fill button alone, read ahead of --bit-Button-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-hover-color` | --bit-Button-hover-color | Foreground while hovered (pointer devices only) of a Fill button alone, read ahead of --bit-Button-hover-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-hover-background` | --bit-Button-hover-background | Background while hovered (pointer devices only) of a Fill button alone, read ahead of --bit-Button-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-hover-border-color` | --bit-Button-hover-border-color | Border color while hovered (pointer devices only) of a Fill button alone, read ahead of --bit-Button-hover-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-active-color` | --bit-Button-active-color | Foreground while pressed of a Fill button alone, read ahead of --bit-Button-active-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-active-background` | --bit-Button-active-background | Background while pressed of a Fill button alone, read ahead of --bit-Button-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-active-border-color` | --bit-Button-active-border-color | Border color while pressed of a Fill button alone, read ahead of --bit-Button-active-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-disabled-color` | --bit-Button-disabled-color | Foreground when disabled of a Fill button alone, read ahead of --bit-Button-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of such a button while AllowDisabledFocus keeps it in the tab order. The Color parameter wins over it. |
| `--bit-Button-fill-disabled-background` | --bit-Button-disabled-background | Background when disabled of a Fill button alone, read ahead of --bit-Button-disabled-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-fill-disabled-border-color` | --bit-Button-disabled-border-color | Border color when disabled of a Fill button alone, read ahead of --bit-Button-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-color` | --bit-Button-color | Foreground (text and icon) in the rest state of an Outline button alone, read ahead of --bit-Button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-background` | --bit-Button-background | Background in the rest state of an Outline button alone, read ahead of --bit-Button-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-outline-border-color` | --bit-Button-border-color | Border color in the rest state of an Outline button alone, read ahead of --bit-Button-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-hover-color` | --bit-Button-hover-color | Foreground while hovered (pointer devices only) of an Outline button alone, and the one it wears in every state with FixedColor, read ahead of --bit-Button-hover-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-hover-background` | --bit-Button-hover-background | Background while hovered (pointer devices only) of an Outline button alone, read ahead of --bit-Button-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-hover-border-color` | --bit-Button-hover-border-color | Border color while hovered (pointer devices only) of an Outline button alone, read ahead of --bit-Button-hover-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-active-color` | --bit-Button-active-color | Foreground while pressed of an Outline button alone, read ahead of --bit-Button-active-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-active-background` | --bit-Button-active-background | Background while pressed of an Outline button alone, read ahead of --bit-Button-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-active-border-color` | --bit-Button-active-border-color | Border color while pressed of an Outline button alone, read ahead of --bit-Button-active-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-outline-disabled-color` | --bit-Button-disabled-color | Foreground when disabled of an Outline button alone, read ahead of --bit-Button-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of such a button while AllowDisabledFocus keeps it in the tab order. The Color parameter wins over it. |
| `--bit-Button-outline-disabled-background` | --bit-Button-disabled-background | Background when disabled of an Outline button alone, read ahead of --bit-Button-disabled-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-outline-disabled-border-color` | --bit-Button-disabled-border-color | Border color when disabled of an Outline button alone, read ahead of --bit-Button-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-color` | --bit-Button-color | Foreground (text and icon) in the rest state of a Text button alone, read ahead of --bit-Button-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-background` | --bit-Button-background | Background in the rest state of a Text button alone, read ahead of --bit-Button-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-text-border-color` | --bit-Button-border-color | Border color in the rest state of a Text button alone, read ahead of --bit-Button-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-text-hover-color` | --bit-Button-hover-color | Foreground while hovered (pointer devices only) of a Text button alone, and the one it wears in every state with FixedColor, read ahead of --bit-Button-hover-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-hover-background` | --bit-Button-hover-background | Background while hovered (pointer devices only) of a Text button alone, read ahead of --bit-Button-hover-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-hover-border-color` | --bit-Button-hover-border-color | Border color while hovered (pointer devices only) of a Text button alone, read ahead of --bit-Button-hover-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-text-active-color` | --bit-Button-active-color | Foreground while pressed of a Text button alone, read ahead of --bit-Button-active-color so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-active-background` | --bit-Button-active-background | Background while pressed of a Text button alone, read ahead of --bit-Button-active-background so a theme can set this variant apart from the other two. The Color parameter wins over it. |
| `--bit-Button-text-active-border-color` | --bit-Button-active-border-color | Border color while pressed of a Text button alone, read ahead of --bit-Button-active-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-text-disabled-color` | --bit-Button-disabled-color | Foreground when disabled of a Text button alone, read ahead of --bit-Button-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of such a button while AllowDisabledFocus keeps it in the tab order. The Color parameter wins over it. |
| `--bit-Button-text-disabled-background` | --bit-Button-disabled-background | Background when disabled of a Text button alone, read ahead of --bit-Button-disabled-background so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-text-disabled-border-color` | --bit-Button-disabled-border-color | Border color when disabled of a Text button alone, read ahead of --bit-Button-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter leaves it alone. |
| `--bit-Button-focus-color` | --bit-clr-pri-focus | Color of the focus ring drawn around the button on keyboard focus. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. |
| `--bit-Button-radius` | --bit-shp-radius-button | Corner radius of the box, which the focus ring follows. The Rounded parameter wins over it. |
| `--bit-Button-border-width` | --bit-shp-brd-width | Thickness of the border on every variant. |
| `--bit-Button-shadow` | none | Elevation of the box, for a design system whose buttons are raised rather than flat. A Float or FloatAbsolute button is lifted by --bit-Button-float-shadow instead. |
| `--bit-Button-padding` | --bit-siz-ctrl-pad-y-md --bit-siz-ctrl-pad-x-md | Padding of the box. An icon-only button takes its vertical padding on all four sides instead. The Size parameter wins over it. |
| `--bit-Button-min-width` | --bit-siz-ctrl-min-width | Smallest width of a labeled button, for lining up a row of buttons whose labels differ in length. FullWidth and NoWrap drop it to zero unless it is set, since both size the button by its container. |
| `--bit-Button-min-height` | --bit-siz-ctrl-md | Smallest height of the box, and the smallest width of an icon-only one. It is a floor, not a height: the box still grows with a wrapped label or a secondary line. The Size parameter wins over it. |
| `--bit-Button-gap` | spacing(1) | Room between the icon and the text, and between the loading spinner and its label. The Size parameter wins over it. |
| `--bit-Button-font-size` | --bit-tpg-fs-sm | Size of the primary text. The Size parameter wins over it. |
| `--bit-Button-secondary-font-size` | --bit-tpg-fs-xs | Size of the secondary text, one ramp step below the primary text by default. The Size parameter wins over it. |
| `--bit-Button-secondary-color` | The button's own foreground | Color of the secondary line of text. It is not muted by default, since on a filled button the contrast of the smaller of the two lines is what a muted color spends first. |
| `--bit-Button-font-weight` | --bit-tpg-font-weight | Weight of both lines of text. |
| `--bit-Button-text-transform` | --bit-tpg-ctrl-text-transform | Casing of both lines of text. Set it to none to drop the uppercasing of the buttons alone, without touching the other controls that share the global token. |
| `--bit-Button-letter-spacing` | --bit-tpg-ctrl-letter-spacing | Tracking of both lines of text, which usually moves with the casing above. |
| `--bit-Button-icon-size` | --bit-siz-icon-md | Size of the icon, for a glyph and an IconUrl image alike. The Size parameter wins over it. |
| `--bit-Button-spinner-size` | --bit-siz-icon-md | Diameter of the loading spinner, the icon's size by default. The Size parameter wins over it. |
| `--bit-Button-spinner-color` | The button's own foreground | The spinner's moving arc. Reading the foreground by default is what keeps it legible over the filled background of one variant and the transparent one of the others. |
| `--bit-Button-spinner-track-color` | The button's own foreground at 25% | The ring the arc travels on. |
| `--bit-Button-float-offset` | 1rem | Inset of a Float or FloatAbsolute button from the edge it is pinned to. The FloatOffset parameter writes this variable on the instance. |
| `--bit-Button-float-shadow` | --bit-shd-card | Elevation of a Float or FloatAbsolute button, which is what lifts it off the content it sits over. The focus ring is a shadow too and replaces it while the button is focused. |
## Examples
\n**Basic**:
```razor
Button
Primary text
Fill
Outline
Text
Fill
Outline
Text
Fill
Outline
Text
Fill
Outline
Text
```
\n**Icon**:
```razor
Start
Start
End
Start
Start
End
Add
Edit
Add
Edit
Click me
Click me
Click me
End
Start
Top
Bottom
Click me
Reclickable
Without a delay
LoadingDelay="500" (250ms)
LoadingDelay="500" (2s)
```
```csharp
private bool fillIsLoading;
private async Task LoadingFillClick()
{
fillIsLoading = true;
await Task.Delay(3000);
fillIsLoading = false;
}
private bool outlineIsLoading;
private async Task LoadingOutlineClick()
{
outlineIsLoading = true;
await Task.Delay(3000);
outlineIsLoading = false;
}
private bool textIsLoading;
private async Task LoadingTextClick()
{
textIsLoading = true;
await Task.Delay(3000);
textIsLoading = false;
}
private int autoLoadCount;
private async Task AutoLoadingClick()
{
autoLoadCount++;
await Task.Delay(3000);
}
// A re-clickable button reports the loading state its click arrived in, which is how a handler
// that is being re-entered knows to abandon the run that is still in flight.
private int reclickableAutoLoadCount;
private TaskCompletionSource clickTsc = new();
private CancellationTokenSource delayCts = new();
private Task AutoLoadingReclick(bool isLoading)
{
if (isLoading)
{
clickTsc.TrySetException(new TaskCanceledException());
delayCts.Cancel();
}
delayCts = new();
clickTsc = new();
reclickableAutoLoadCount++;
_ = Task.Delay(3000, delayCts.Token).ContinueWith(async delayTask =>
{
await delayTask;
clickTsc.TrySetResult();
});
return clickTsc.Task;
}
// Finishes inside the 500ms delay of the second button, so that one never shows a spinner.
private async Task FastOperation() => await Task.Delay(250);
// Outlasts the same delay, so the third button shows its spinner once the 500ms are up.
private async Task SlowOperation() => await Task.Delay(2000);
```
\n**Href**:
```razor
Open bitplatform.dev
Download the bit logo
nofollow
nofollow & noreferrer
```
\n**Form & button type**:
```razor
@if (formIsValidSubmit is false)
{
Submit
Reset
Button
}
else
{
The form submitted successfully.
}
@if (externalFormSubmitted is false)
{
External submit
}
else
{
The external form submitted successfully.
}
```
```csharp
public class ButtonValidationModel
{
[Required(ErrorMessage = "Enter a text")]
public string? RequiredText { get; set; }
public string? NonRequiredText { get; set; }
}
private bool formIsValidSubmit;
private ButtonValidationModel buttonValidationModel = new();
private async Task HandleValidSubmit()
{
formIsValidSubmit = true;
await Task.Delay(2000);
buttonValidationModel = new();
formIsValidSubmit = false;
StateHasChanged();
}
private void HandleInvalidSubmit()
{
formIsValidSubmit = false;
}
// The native reset empties the inputs and stops there, so the bound model - and the validation state
// built from it - would otherwise survive a reset and be submitted by the next click.
private void ResetValidationForm()
{
buttonValidationModel = new();
}
private bool externalFormSubmitted;
private ButtonValidationModel externalFormModel = new();
private async Task HandleExternalFormValidSubmit()
{
externalFormSubmitted = true;
await Task.Delay(2000);
externalFormModel = new();
externalFormSubmitted = false;
StateHasChanged();
}
```
\n**Templates**:
```razor
Primary text
Click me
```
```csharp
private bool templateIsLoading;
private async Task LoadingTemplateClick()
{
templateIsLoading = true;
await Task.Delay(3000);
templateIsLoading = false;
}
```
\n**Events**:
```razor
Click me (@clickCounter)
With StopPropagation
Without StopPropagation
```
```csharp
private int clickCounter;
private int parentClickCounter;
private int buttonClickCounter;
```
\n**FullWidth & NoWrap**:
```razor
Full width button
Reply to everyone on this unusually long conversation
```
```csharp
private bool noWrap = true;
```
`BitButtonDemo.razor.scss`:
```scss
// Narrow enough that the label of the button inside it has to wrap, or be clamped by NoWrap.
.narrow-container {
max-width: 18rem;
}
```
\n**FixedColor**:
```razor
Default (not fixed)
FixedColor
> floatPositionList = Enum.GetValues()
.Cast()
.Select(enumValue => new BitDropdownItem
{
Value = enumValue,
Text = enumValue.ToString()
})
.ToList();
```
`BitButtonDemo.razor.scss`:
```scss
.float-container {
position: relative;
border: 1px solid var(--bit-clr-brd-sec);
}
.float-container-content {
height: 300px;
overflow: auto;
padding: 0.5rem;
}
```
\n**Accessibility**:
```razor
Hover me
Download the bit logo
Disabled (still focusable)
Disabled (skipped by Tab)
Focus the next button
Focus lands here
```
```csharp
private BitButton focusButtonRef = default!;
```
\n**Cascading parameters**:
```razor
Save
Duplicate
Delete
Outside the cascade, and back to the defaults
```
```csharp
private readonly BitButtonParams[] buttonParams =
[
new()
{
Size = BitSize.Small,
Rounded = true,
Variant = BitVariant.Outline,
Color = BitColor.Secondary,
}
];
```
\n**Color**:
```razor
Primary
Primary
Primary
Secondary
Secondary
Secondary
Tertiary
Tertiary
Tertiary
Info
Info
Info
Success
Success
Success
Warning
Warning
Warning
SevereWarning
SevereWarning
SevereWarning
Error
Error
Error
PrimaryBackground
PrimaryBackground
PrimaryBackground
SecondaryBackground
SecondaryBackground
SecondaryBackground
TertiaryBackground
TertiaryBackground
TertiaryBackground
PrimaryForeground
PrimaryForeground
PrimaryForeground
SecondaryForeground
SecondaryForeground
SecondaryForeground
TertiaryForeground
TertiaryForeground
TertiaryForeground
PrimaryBorder
PrimaryBorder
PrimaryBorder
SecondaryBorder
SecondaryBorder
SecondaryBorder
TertiaryBorder
TertiaryBorder
TertiaryBorder
```
\n**External Icons**:
```razor
House
Heart
GitHub
Rocket
House
Heart
GitHub
Gear
```
\n**Size**:
```razor
Fill
Outline
Text
Loading
Compound
Fill
Outline
Text
Loading
Compound
Fill
Outline
Text
Loading
Compound
```
\n**Style & Class**:
```razor
Styled Button
Classed Button
Click me
Click me
@* The public CSS variables are inherited, so .compact-buttons in the stylesheet beside this page
re-skins both of the buttons inside it without naming a class of the component. *@
Squared off
Ghost on hover
Raised & tracked
```
```csharp
private bool stylesIsLoading;
private async Task LoadingStylesClick()
{
stylesIsLoading = true;
await Task.Delay(3000);
stylesIsLoading = false;
}
private bool classesIsLoading;
private async Task LoadingClassesClick()
{
classesIsLoading = true;
await Task.Delay(3000);
classesIsLoading = false;
}
```
`BitButtonDemo.razor.scss`:
```scss
.compact-buttons {
--bit-Button-gap: 0.25rem;
--bit-Button-font-size: 0.75rem;
--bit-Button-padding: 0 0.75rem;
--bit-Button-min-height: 1.75rem;
}
::deep {
.custom-class {
border-radius: 1rem;
border-color: blueviolet;
transition: background-color 1s;
background: linear-gradient(90deg, magenta, transparent) blue;
}
.custom-class:hover {
border-color: magenta;
background-color: magenta;
}
.custom-root {
color: aqua;
min-width: 7.2rem;
font-weight: bold;
border-radius: 1rem;
border-color: aqua;
box-shadow: aqua 0 0 0.5rem;
}
.custom-root:hover {
color: black;
background-color: aqua;
}
.custom-container {
text-shadow: tomato 0 0 0.5rem;
}
.custom-spinner {
border-color: red;
border-top-color: goldenrod;
}
}
```
\n**RTL**:
```razor
دکمه با آیکن
دکمه با آیکن
دکمه با آیکن
AutoLoading click count: @autoLoadCount
Re-clickable AutoLoading click count: @reclickableAutoLoadCount
Button clicks: @buttonClickCounter, Parent clicks: @parentClickCounter
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
...