ButtonGroup
ButtonGroup handles overflow for a group of Buttons. When there isn't enough horizontal space for every Button, then it switches to a vertical layout. Anytime there are two or more Buttons next to each other, a ButtonGroup should be used.
| install | yarn add @react-spectrum/buttongroup |
|---|---|
| version | 3.0.0-alpha.1 |
| usage | import {ButtonGroup} from '@react-spectrum/buttongroup' |
Example#
To see the orientation switch, reduce the width of your window.
<ButtonGroup width="50%">
<Button variant="primary">Rate Now</Button>
<Button variant="secondary">No, thanks</Button>
<Button variant="secondary">Remind me later</Button>
</ButtonGroup>Content#
ButtonGroup expects Buttons as children.
Props#
| Name | Type | Default | Description |
isDisabled | boolean | — | Whether the Buttons in the ButtonGroup are all disabled. |
orientation | Orientation | "horizontal" | The axis the ButtonGroup should align with. Setting this to 'vertical' will prevent any switching behaviors between 'vertical' and 'horizontal'. |
children | ReactNode | — | The Buttons contained within the ButtonGroup. |
align | Alignment | 'center' | "start" | The alignment of the buttons within the ButtonGroup. |
Layout
| Name | Type | Default | Description |
flex | string | number | boolean | — | When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN. |
flexGrow | number | — | When used in a flex layout, specifies how the element will grow to fit the space available. See MDN. |
flexShrink | number | — | When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN. |
flexBasis | number | string | — | When used in a flex layout, specifies the initial main size of the element. See MDN. |
alignSelf | 'auto'
| 'normal'
| 'start'
| 'end'
| 'center'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'stretch' | — | Overrides the alignItems property of a flex or grid container. See MDN. |
justifySelf | 'auto'
| 'normal'
| 'start'
| 'end'
| 'flex-start'
| 'flex-end'
| 'self-start'
| 'self-end'
| 'center'
| 'left'
| 'right'
| 'stretch' | — | Specifies how the element is justified inside a flex or grid container. See MDN. |
order | number | — | The layout order for the element within a flex or grid container. See MDN. |
gridArea | string | — | When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN. |
gridColumn | string | — | When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN. |
gridRow | string | — | When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN. |
gridColumnStart | string | — | When used in a grid layout, specifies the starting column to span within the grid. See MDN. |
gridColumnEnd | string | — | When used in a grid layout, specifies the ending column to span within the grid. See MDN. |
gridRowStart | string | — | When used in a grid layout, specifies the starting row to span within the grid. See MDN. |
gridRowEnd | string | — | When used in a grid layout, specifies the ending row to span within the grid. See MDN. |
Spacing
| Name | Type | Default | Description |
margin | DimensionValue | — | The margin for all four sides of the element. See MDN. |
marginTop | DimensionValue | — | The margin for the top side of the element. See MDN. |
marginBottom | DimensionValue | — | The margin for the bottom side of the element. See MDN. |
marginStart | DimensionValue | — | The margin for the logical start side of the element, depending on layout direction. See MDN. |
marginEnd | DimensionValue | — | The margin for the logical end side of an element, depending on layout direction. See MDN. |
marginX | DimensionValue | — | The margin for both the left and right sides of the element. See MDN. |
marginY | DimensionValue | — | The margin for both the top and bottom sides of the element. See MDN. |
Sizing
| Name | Type | Default | Description |
width | DimensionValue | — | The width of the element. See MDN. |
minWidth | DimensionValue | — | The minimum width of the element. See MDN. |
maxWidth | DimensionValue | — | The maximum width of the element. See MDN. |
height | DimensionValue | — | The height of the element. See MDN. |
minHeight | DimensionValue | — | The minimum height of the element. See MDN. |
maxHeight | DimensionValue | — | The maximum height of the element. See MDN. |
Positioning
| Name | Type | Default | Description |
position | 'static'
| 'relative'
| 'absolute'
| 'fixed'
| 'sticky' | — | Specifies how the element is positioned. See MDN. |
top | DimensionValue | — | The top position for the element. See MDN. |
bottom | DimensionValue | — | The bottom position for the element. See MDN. |
left | DimensionValue | — | The left position for the element. See MDN. Consider using start instead for RTL support. |
right | DimensionValue | — | The right position for the element. See MDN. Consider using start instead for RTL support. |
start | DimensionValue | — | The logical start position for the element, depending on layout direction. See MDN. |
end | DimensionValue | — | The logical end position for the element, depending on layout direction. See MDN. |
zIndex | number | — | The stacking order for the element. See MDN. |
isHidden | boolean | — | Hides the element. |
Accessibility
| Name | Type | Default | Description |
role | string | — | |
id | string | — | |
tabIndex | number | — | |
aria-label | string | — | Defines a string value that labels the current element. |
aria-labelledby | string | — | Identifies the element (or elements) that labels the current element. |
aria-describedby | string | — | Identifies the element (or elements) that describes the object. |
aria-controls | string | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
aria-owns | string | — | Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship. |
aria-hidden | boolean | 'false' | 'true' | — | Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. |
Advanced
| Name | Type | Default | Description |
UNSAFE_className | string | — | Sets the CSS className for the element. Only use as a last resort. Use style props instead. |
UNSAFE_style | CSSProperties | — | Sets inline style for the element. Only use as a last resort. Use style props instead. |
Visual options#
Orientation#
Setting this to 'vertical' will prevent any dynamic orientation changes, the ButtonGroup will remain in vertical regardless of the available width.
<ButtonGroup orientation="vertical">
<Button variant="secondary">No, thanks</Button>
<Button variant="secondary">Remind me later</Button>
<Button variant="primary">Rate Now</Button>
</ButtonGroup>Alignment#
Button groups are aligned contextually. Generally (in LTR languages), button groups should be left-aligned to follow content. However, they should be right-aligned inside container components, such as in dialogs, popovers, or cards. They should be center-aligned in the context of an empty state. In RTL, left and right should be flipped. To see the orientation switch, reduce the width of your window.
<View width="50%">
<ButtonGroup align="end" width="100%">
<Button variant="secondary">No, thanks</Button>
<Button variant="secondary">Remind me later</Button>
<Button variant="primary">Rate Now</Button>
</ButtonGroup>
</View><View width="50%">
<ButtonGroup align="center" width="100%">
<Button variant="secondary">No, thanks</Button>
<Button variant="secondary">Remind me later</Button>
<Button variant="primary">Rate Now</Button>
</ButtonGroup>
</View>