005cf56baf
Some checks failed
No response / noResponse (push) Has been cancelled
CI / Continuous releases (push) Has been cancelled
CI / test-dev (macos-latest) (push) Has been cancelled
CI / test-dev (ubuntu-latest) (push) Has been cancelled
CI / test-dev (windows-latest) (push) Has been cancelled
Maintenance / main (push) Has been cancelled
Scorecards supply-chain security / Scorecards analysis (push) Has been cancelled
CodeQL / Analyze (push) Has been cancelled
138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
---
|
||
productId: joy-ui
|
||
title: React Button Group component
|
||
components: Button, IconButton, ButtonGroup
|
||
githubLabel: 'component: ButtonGroup'
|
||
---
|
||
|
||
# Button Group
|
||
|
||
<p class="description">The Button Group combines a set of related buttons.</p>
|
||
|
||
{{"component": "@mui/docs/ComponentLinkHeader"}}
|
||
|
||
## Introduction
|
||
|
||
The Button Group component combines a set of buttons that have similar or related functionality.
|
||
|
||
{{"demo": "ButtonGroupUsage.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
## Basics
|
||
|
||
The Button Group component can wrap [`Button`](/joy-ui/react-button/) and [`IconButton`](/joy-ui/react-button/#icon-button).
|
||
|
||
{{"demo": "BasicButtonGroup.js"}}
|
||
|
||
## Customization
|
||
|
||
### Variants
|
||
|
||
The Button Group component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `outlined` (default), `solid`, `soft`, and `plain`.
|
||
|
||
The `variant` prop is passed to the buttons, not the Button Group itself.
|
||
|
||
{{"demo": "VariantButtonGroup.js"}}
|
||
|
||
:::info
|
||
To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
|
||
Note that you lose the global variants when you add custom variants.
|
||
:::
|
||
|
||
### Sizes
|
||
|
||
The Button Group component comes in three sizes: `sm`, `md` (default), and `lg`.
|
||
|
||
{{"demo": "GroupSizesColors.js"}}
|
||
|
||
:::info
|
||
To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
|
||
:::
|
||
|
||
### Colors
|
||
|
||
Every palette included in the theme is available via the `color` prop.
|
||
Play around combining different colors with different variants.
|
||
|
||
{{"demo": "ButtonGroupColors.js"}}
|
||
|
||
### Disabled
|
||
|
||
Use the `disabled` prop to disable all the buttons.
|
||
Note that if you explicitly specify the `disabled` prop on the buttons directly, it will override what is used in the Button Group.
|
||
|
||
{{"demo": "DisabledButtonGroup.js"}}
|
||
|
||
### Spacing
|
||
|
||
Use `spacing` prop to control the gap between buttons. If the `spacing` is set to `0` (by default), the radius of the buttons will be adjusted to form a continuous surface.
|
||
|
||
{{"demo": "SpacingButtonGroup.js"}}
|
||
|
||
:::success
|
||
The type of value can be:
|
||
|
||
- `string`: any valid CSS length unit, for example `px`, `rem`, `em`, etc.
|
||
- `number`: will be calculated by `theme.spacing` function.
|
||
- `array`: the responsive values based on the breakpoints defined in the theme.
|
||
- `object`: the key must be one of the breakpoints defined in the theme (the defaults are `"xs" | "sm" | "md" | "lg" | "xl")`, and the value is the spacing of type `string` or `number`.
|
||
|
||
```jsx
|
||
<ButtonGroup spacing={{ xs: 0, sm: 1, md: '2rem' }}>...</ButtonGroup>
|
||
```
|
||
|
||
:::
|
||
|
||
### Vertical group
|
||
|
||
The Button Group component can be displayed vertically using the `orientation="vertical"` prop.
|
||
Note that this prop has no effect on `IconButton` component.
|
||
|
||
{{"demo": "GroupOrientation.js"}}
|
||
|
||
### Stretching button
|
||
|
||
Use the `buttonFlex` prop to make the buttons fill the available space of the Button Group component.
|
||
|
||
{{"demo": "FlexButtonGroup.js"}}
|
||
|
||
#### Minimum width
|
||
|
||
For a large container, control the default width of the buttons by providing a valid [CSS `flex`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/flex) value to the `buttonFlex` prop.
|
||
|
||
{{"demo": "MinWidthButtonGroup.js"}}
|
||
|
||
### Split button
|
||
|
||
The Button Group component can also be used to create a split button.
|
||
The dropdown can change the button action (as in this example) or be used to immediately trigger a related action.
|
||
|
||
{{"demo": "SplitButton.js"}}
|
||
|
||
### Separator color
|
||
|
||
When the Button Group's variant is <b>not</b> `outlined`, separators are created between buttons.
|
||
To control the color of the separator, override the CSS variable `--ButtonGroup-separatorColor` via the `sx` prop.
|
||
|
||
{{"demo": "SeparatorButtonGroup.js"}}
|
||
|
||
## Using it with a Tooltip
|
||
|
||
The Button Group component supports arbitrary children that wrap the buttons by preserving the same appearance.
|
||
|
||
{{"demo": "TooltipButtonGroup.js"}}
|
||
|
||
## Common examples
|
||
|
||
### Pill button group
|
||
|
||
Use the CSS variable `--ButtonGroup-radius` to control the radius of the start and end buttons.
|
||
|
||
{{"demo": "RadiusButtonGroup.js"}}
|
||
|
||
### Custom separator
|
||
|
||
This example uses the `Divider` component to create a custom separator between the buttons.
|
||
The CSS variable `--ButtonGroup-separatorColor` is then set with an arbitrary value to remove the default separator.
|
||
|
||
{{"demo": "CustomSeparatorButtonGroup.js"}}
|