An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file ButtonGroup.tsx
* @input Uses React, StyleX, Button/IconButton children, and the shared group
* press tracking (hooks/useGroupPressTracking)
* @output Exports ButtonGroup component, context, and types
* @position Groups buttons with connected styling; consumed by index.ts
*
* Children (Button, IconButton) consume the ButtonGroup context to apply
* position-aware styles in pure CSS — no cloneElement or wrapper divs needed.
* The end-cap radius rules live in Button.tsx; see IS_LAST_ITEM there for why
* the trailing edge cannot use :last-child (#2508).
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/ButtonGroup/ButtonGroup.doc.mjs (props table, features)
* - /packages/core/src/ButtonGroup/ButtonGroup.test.tsx (tests)
* - /packages/core/src/ButtonGroup/index.ts (exports if types change)
* - /apps/storybook/stories/ButtonGroup.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/ButtonGroup/ (showcase blocks)
*/
import {useMemo, useRef, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {ButtonSize} from '../Button';
import {radiusVars, shadowVars} from '../theme/tokens.stylex';
import type {Elevation} from '../utils/types';
import {SizeProvider, useSize} from '../SizeContext/SizeContext';
import {oneTabStopAmong, useInternalListFocus} from '../hooks/useListFocus';
import {PressGroupContext} from '../hooks/pressGroupContext';
import {
GROUP_PRESS_POINTERS,
useGroupPressTracking,
} from '../hooks/useGroupPressTracking';
import {useTouchPresentation} from '../utils/touchPresentation';
import {touchHitAreaStyles} from '../internal/touchHitArea.stylex';
import {mergeProps, composeEventHandlers} from '../utils';
import type {BaseProps} from '../BaseProps';
import {ButtonGroupContext} from './ButtonGroupContext';
import type {ButtonGroupOrientation} from './ButtonGroupContext';
import {themeProps} from '../utils/themeProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
// =============================================================================
// Props
// =============================================================================
export interface ButtonGroupProps extends BaseProps<HTMLDivElement> {
/** Ref forwarded to the root element. */
ref?: React.Ref<HTMLDivElement>;
/**
* Button or IconButton children.
*/
children: ReactNode;
/**
* Accessible label for the group (used as aria-label).
*/
label: string;
/**
* Orientation of the button group.
* @default 'horizontal'
*/
orientation?: ButtonGroupOrientation;
/**
* Default size for buttons in the group.
* Individual buttons can override this with their own `size` prop.
* @default 'md'
*/
size?: ButtonSize;
/**
* Resting elevation for the group. The connected buttons share one surface,
* so the shadow sits on the group and lifts them together. Use for a floating
* group of actions above content.
* @default 'none'
*/
elevation?: Elevation;
/**
* Whether all buttons in the group are disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Test ID for testing frameworks.
*/
'data-testid'?: string;
}
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
group: {
display: 'inline-flex',
alignItems: 'stretch',
},
vertical: {
flexDirection: 'column',
},
// While the group tracks presses, its hit layer is the root's `::before`,
// below its buttons, so the root is the layer's containing block.
tracking: {
position: 'relative',
},
});
// Resting elevation for the whole group — the connected buttons share one
// surface, so the shadow sits on the group wrapper and lifts them as a unit.
// The wrapper takes the element radius so the shadow follows the group's
// rounded outer corners rather than a bare rectangle. 'none' is the default.
const elevationStyles = stylex.create({
none: {boxShadow: 'none'},
low: {
boxShadow: shadowVars['--shadow-low'],
borderRadius: radiusVars['--radius-element'],
},
med: {
boxShadow: shadowVars['--shadow-med'],
borderRadius: radiusVars['--radius-element'],
},
high: {
boxShadow: shadowVars['--shadow-high'],
borderRadius: radiusVars['--radius-element'],
},
});
// =============================================================================
// Component
// =============================================================================
// Roving rewrites `tabindex` on every item, so the selector cannot key off
// a value: `[tabindex="0"]` would drop each member the moment it is stamped
// -1. `a[href]` catches a Button rendered with `href`.
const MEMBER_SELECTOR = 'button, a[href], [tabindex]';
const keepDisabledGroupStop = oneTabStopAmong(
MEMBER_SELECTOR,
'[role="group"], [popover]',
);
/**
* Groups buttons with connected styling — shared borders, proper border-radius
* handling (only on outer edges), and horizontal or vertical orientation.
*
* Children automatically detect the group via context and apply position-aware
* styles in pure CSS.
*
* The group is a single tab stop: arrow keys move between members along the
* orientation, Home/End jump to the ends, and focus wraps (the APG roving
* tabindex technique, via `useListFocus`).
*
* Members that render their own layer — a Button with a `tooltip`, or a
* DropdownMenu — compose correctly, including as the trailing member.
*
* @example
* ```
* <ButtonGroup label="Actions">
* <Button label="Copy" />
* <Button label="Cut" />
* <Button label="Paste" />
* </ButtonGroup>
* ```
*
* @example
* ```
* <ButtonGroup label="Approve action">
* <Button label="Allow once" variant="primary" />
* <DropdownMenu
* button={{label: 'Allow options', variant: 'primary', isIconOnly: true, icon: <Icon icon="chevronDown" />}}
* items={[{label: 'Allow for 30 minutes'}, {label: 'Always allow'}]}
* />
* </ButtonGroup>
* ```
*/
export function ButtonGroup({
children,
label,
orientation = 'horizontal',
size: sizeProp,
isDisabled = false,
elevation = 'none',
xstyle,
className,
style,
ref,
'data-testid': testId,
onKeyDown,
onFocus,
...props
}: ButtonGroupProps): ReactNode {
const size = useSize(sizeProp, 'md');
const {listRef, handleKeyDown, handleFocus} =
useInternalListFocus<HTMLDivElement>({
itemSelector: MEMBER_SELECTOR,
// A member's layer renders inline inside the group (useLayer does not
// portal it), so a key pressed in an open DropdownMenu bubbles here. The
// boundary is the group's own root or any layer, whichever is nearer to
// the target. Naming the group's own root is what keeps a group rendered
// inside a Popover or Toast working: bailing on any [popover] ancestor
// instead would swallow every arrow key it owns.
boundarySelector: '[role="group"], [popover]',
orientation,
hasRovingTabIndex: true,
// A group of disabled buttons keeps its one Tab stop, so a keyboard user
// still reaches it. Its members are focusable while disabled.
tabStopOrder: keepDisabledGroupStop,
});
const contextValue = useMemo(
() => ({orientation, isDisabled}),
[orientation, isDisabled],
);
// Only under the touch presentation does a press slide across the buttons.
// A desktop press stays the native button's.
const {isTouch} = useTouchPresentation();
const tracksPress = !isDisabled && isTouch;
const groupRef = useRef<HTMLDivElement>(null);
const {hitAreaRef} = useGroupPressTracking(groupRef, tracksPress);
return (
<ButtonGroupContext value={contextValue}>
<SizeProvider value={size}>
<div
ref={useMergedRefs(ref, listRef, groupRef, hitAreaRef)}
{...props}
{...mergeProps(
themeProps('button-group', {size, orientation, elevation}),
stylex.props(
styles.group,
tracksPress && styles.tracking,
tracksPress && touchHitAreaStyles.layerBelowChildren,
orientation === 'vertical' && styles.vertical,
elevationStyles[elevation],
xstyle,
),
className,
style,
)}
role="group"
aria-label={label}
onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
onFocus={composeEventHandlers(onFocus, handleFocus)}
aria-disabled={isDisabled || undefined}
data-testid={testId}>
<PressGroupContext value={tracksPress ? GROUP_PRESS_POINTERS : null}>
{children}
</PressGroupContext>
</div>
</SizeProvider>
</ButtonGroupContext>
);
}
ButtonGroup.displayName = 'ButtonGroup';