Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(ButtonGroup): add XDSButtonGroup component (#210) (#2202)

Andrey Goder061a16da7f10
diff --git a/apps/storybook/stories/ButtonGroup.stories.tsx b/apps/storybook/stories/ButtonGroup.stories.tsx
new file mode 100644
index 0000000000..5c974bb748
--- /dev/null
+++ b/apps/storybook/stories/ButtonGroup.stories.tsx
@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSButtonGroup} from '@xds/core/ButtonGroup';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {XDSIcon} from '@xds/core/Icon';
+import {
+ ClipboardDocumentIcon,
+ ScissorsIcon,
+ ClipboardIcon,
+ ArrowUturnLeftIcon,
+ ArrowUturnRightIcon,
+ BoldIcon,
+ ItalicIcon,
+ UnderlineIcon,
+ ChevronDownIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSButtonGroup> = {
+ title: 'Core/Buttons/ButtonGroup',
+ component: XDSButtonGroup,
+ tags: ['autodocs'],
+ argTypes: {
+ orientation: {control: 'select', options: ['horizontal', 'vertical']},
+ size: {control: 'select', options: ['sm', 'md', 'lg']},
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSButtonGroup>;
+
+const iconSize = {width: 16, height: 16} as const;
+
+/** Basic horizontal button group with text buttons. */
+export const Horizontal: Story = {
+ render: () => (
+ <XDSButtonGroup label="Clipboard actions">
+ <XDSButton
+ label="Copy"
+ icon={<ClipboardDocumentIcon style={iconSize} />}
+ />
+ <XDSButton label="Cut" icon={<ScissorsIcon style={iconSize} />} />
+ <XDSButton label="Paste" icon={<ClipboardIcon style={iconSize} />} />
+ </XDSButtonGroup>
+ ),
+};
+
+/** Vertical button group. */
+export const Vertical: Story = {
+ render: () => (
+ <XDSButtonGroup label="Actions" orientation="vertical">
+ <XDSButton label="Copy" />
+ <XDSButton label="Cut" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>
+ ),
+};
+
+/** Icon-only button group for compact toolbars. */
+export const IconOnly: Story = {
+ render: () => (
+ <XDSButtonGroup label="Text formatting">
+ <XDSIconButton
+ label="Bold"
+ icon={<XDSIcon icon={BoldIcon} size="sm" />}
+ />
+ <XDSIconButton
+ label="Italic"
+ icon={<XDSIcon icon={ItalicIcon} size="sm" />}
+ />
+ <XDSIconButton
+ label="Underline"
+ icon={<XDSIcon icon={UnderlineIcon} size="sm" />}
+ />
+ </XDSButtonGroup>
+ ),
+};
+
+/** Undo/redo pair with ghost variant. */
+export const GhostPair: Story = {
+ render: () => (
+ <XDSButtonGroup label="History">
+ <XDSButton
+ label="Undo"
+ variant="ghost"
+ icon={<ArrowUturnLeftIcon style={iconSize} />}
+ isIconOnly
+ />
+ <XDSButton
+ label="Redo"
+ variant="ghost"
+ icon={<ArrowUturnRightIcon style={iconSize} />}
+ isIconOnly
+ />
+ </XDSButtonGroup>
+ ),
+};
+
+/** All three sizes side by side. */
+export const Sizes: Story = {
+ render: () => (
+ <div style={{display: 'flex', gap: 16, alignItems: 'center'}}>
+ <XDSButtonGroup label="Small actions" size="sm">
+ <XDSButton label="Copy" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>
+ <XDSButtonGroup label="Medium actions" size="md">
+ <XDSButton label="Copy" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>
+ <XDSButtonGroup label="Large actions" size="lg">
+ <XDSButton label="Copy" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>
+ </div>
+ ),
+};
+
+/** Primary variant button group. */
+export const PrimaryVariant: Story = {
+ render: () => (
+ <XDSButtonGroup label="Save options">
+ <XDSButton label="Save" variant="primary" />
+ <XDSButton
+ label="Save options"
+ variant="primary"
+ icon={<ChevronDownIcon style={iconSize} />}
+ isIconOnly
+ />
+ </XDSButtonGroup>
+ ),
+};
+
+/** Two-button group (common split button pattern). */
+export const SplitButton: Story = {
+ render: () => (
+ <XDSButtonGroup label="Merge options">
+ <XDSButton label="Merge pull request" variant="primary" />
+ <XDSButton
+ label="More merge options"
+ variant="primary"
+ icon={<ChevronDownIcon style={iconSize} />}
+ isIconOnly
+ />
+ </XDSButtonGroup>
+ ),
+};
+
+/** Mixed button and icon button children. */
+export const Mixed: Story = {
+ render: () => (
+ <XDSButtonGroup label="Edit actions">
+ <XDSButton label="Edit" />
+ <XDSIconButton
+ label="More options"
+ icon={<ChevronDownIcon style={iconSize} />}
+ />
+ </XDSButtonGroup>
+ ),
+};
diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjs b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjs
new file mode 100644
index 0000000000..4989840e7b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjs
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ButtonGroup',
+ name: 'ButtonGroup',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ isShowcase: true,
+ componentsUsed: ['Button', 'ButtonGroup', 'Icon', 'IconButton', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsx b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsx
new file mode 100644
index 0000000000..b0ff54dc09
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsx
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSButtonGroup} from '@xds/core/ButtonGroup';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSIcon} from '@xds/core/Icon';
+import {
+ ClipboardDocumentIcon,
+ ScissorsIcon,
+ ClipboardIcon,
+ ChevronDownIcon,
+} from '@heroicons/react/24/outline';
+
+export default function ButtonGroupShowcase() {
+ return (
+ <XDSStack direction="horizontal" gap={6} vAlign="center">
+ <XDSButtonGroup label="Clipboard actions">
+ <XDSButton
+ label="Copy"
+ icon={<XDSIcon icon={ClipboardDocumentIcon} />}
+ />
+ <XDSButton label="Cut" icon={<XDSIcon icon={ScissorsIcon} />} />
+ <XDSButton label="Paste" icon={<XDSIcon icon={ClipboardIcon} />} />
+ </XDSButtonGroup>
+ <XDSButtonGroup label="Save options">
+ <XDSButton label="Save" variant="primary" />
+ <XDSIconButton
+ label="Save options"
+ variant="primary"
+ icon={<XDSIcon icon={ChevronDownIcon} />}
+ />
+ </XDSButtonGroup>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 1577e41fc5..4ef970919d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -121,6 +121,12 @@
"import": "./dist/Button/index.mjs",
"require": "./dist/Button/index.js"
},
+ "./ButtonGroup": {
+ "source": "./src/ButtonGroup/index.ts",
+ "types": "./dist/ButtonGroup/index.d.ts",
+ "import": "./dist/ButtonGroup/index.mjs",
+ "require": "./dist/ButtonGroup/index.js"
+ },
"./Calendar": {
"source": "./src/Calendar/index.ts",
"types": "./dist/Calendar/index.d.ts",
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index 4e1d262d10..0a43cb19c1 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -26,6 +26,7 @@ import {
sizeVars,
spacingVars,
radiusVars,
+ borderVars,
durationVars,
easeVars,
fontWeightVars,
@@ -36,6 +37,7 @@ import {XDSSpinner} from '../Spinner';
import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
import {useXDSSize} from '../SizeContext/XDSSizeContext';
+import {useXDSButtonGroup} from '../ButtonGroup/XDSButtonGroupContext';
import {xdsClassName, mergeProps} from '../utils';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
@@ -392,6 +394,69 @@ const loadingStyles = stylex.create({
},
});
+const groupStyles = stylex.create({
+ horizontal: {
+ borderStartStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderEndStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderStartEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderEndEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderInlineStartWidth: {
+ default: borderVars['--border-width'],
+ ':first-child': 0,
+ },
+ borderInlineStartStyle: {
+ default: 'solid' as const,
+ ':first-child': 'none' as const,
+ },
+ borderInlineStartColor: colorVars['--color-border'],
+ },
+ vertical: {
+ borderStartStartRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderStartEndRadius: {
+ default: 0,
+ ':first-child': radiusVars['--radius-element'],
+ },
+ borderEndStartRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderEndEndRadius: {
+ default: 0,
+ ':last-child': radiusVars['--radius-element'],
+ },
+ borderBlockStartWidth: {
+ default: borderVars['--border-width'],
+ ':first-child': 0,
+ },
+ borderBlockStartStyle: {
+ default: 'solid' as const,
+ ':first-child': 'none' as const,
+ },
+ borderBlockStartColor: colorVars['--color-border'],
+ },
+ onSolidHorizontal: {
+ borderInlineStartColor: colorVars['--color-on-accent'],
+ },
+ onSolidVertical: {
+ borderBlockStartColor: colorVars['--color-on-accent'],
+ },
+});
+
/**
* A versatile button component with multiple variants.
*
@@ -441,11 +506,13 @@ export function XDSButton({
...props
}: XDSButtonProps): ReactNode {
const size = useXDSSize(sizeProp, 'md');
+ const buttonGroup = useXDSButtonGroup();
const [isPending, startTransition] = useTransition();
const actionInFlightRef = useRef(false);
const isLoadingState = isLoading || isPending;
- const buttonDisabled = isDisabled || isLoadingState;
+ const groupDisabled = buttonGroup?.isDisabled ?? false;
+ const buttonDisabled = isDisabled || groupDisabled || isLoadingState;
const useLightSpinner = variant === 'primary' || variant === 'destructive';
// isIconOnly prop is the source of truth for icon-only rendering.
// When false (default), label is always rendered as visible text.
@@ -505,6 +572,15 @@ export function XDSButton({
useAriaDisabled && styles.ariaDisabled,
isLoadingState && loadingStyles.loading,
renderAsLink && styles.link,
+ buttonGroup &&
+ (buttonGroup.orientation === 'horizontal'
+ ? groupStyles.horizontal
+ : groupStyles.vertical),
+ buttonGroup &&
+ (variant === 'primary' || variant === 'destructive') &&
+ (buttonGroup.orientation === 'horizontal'
+ ? groupStyles.onSolidHorizontal
+ : groupStyles.onSolidVertical),
xstyle,
);
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
new file mode 100644
index 0000000000..1f038d77b3
--- /dev/null
+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ButtonGroup',
+ group: 'Button',
+ keywords: ["button-group","connected","split","toolbar","actions","grouped","buttons"],
+ playground: {
+ defaults: {
+ label: 'Actions',
+ },
+ },
+ theming: {
+ targets: [
+ {className: 'xds-button-group'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSButtonGroup',
+ description: 'Groups multiple buttons together with connected styling — shared borders, proper border-radius handling (only on outer edges), and horizontal or vertical orientation.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'XDSButton or XDSIconButton children.', required: true, slotElements: [{__element: 'XDSButton', props: {label: 'Action'}}]},
+ {name: 'label', type: 'string', description: 'Accessible label for the group (aria-label).', required: true},
+ {name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},
+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},
+ {name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},
+ {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
+ {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
+ ],
+ },
+ ],
+ usage: {
+ description:
+ 'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually — like copy/cut/paste, or undo/redo.',
+ bestPractices: [
+ {guidance: true, description: 'Group buttons that perform related actions on the same object — like copy, cut, paste on selected text.'},
+ {guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},
+ {guidance: true, description: 'Keep groups small (2–4 buttons). For more actions, use a Toolbar or DropdownMenu instead.'},
+ {guidance: false, description: "Don't mix wildly different actions — a Save button next to a Delete button in the same group is confusing."},
+ {guidance: false, description: "Don't use ButtonGroup for navigation — use SegmentedControl or TabList for switching between views."},
+ {guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},
+ ],
+ anatomy: [
+ {name: 'Button', required: true, description: 'One or more XDSButton or XDSIconButton children that form the connected group.'},
+ {name: 'Divider', required: false, description: 'A thin border between buttons, rendered automatically by the group.'},
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+ components: [
+ {
+ name: 'XDSButtonGroup',
+ description: '将多个按钮组合在一起,带有连接样式 — 共享边框、正确的圆角处理(仅外边缘),以及水平或垂直方向。',
+ propDescriptions: {
+ children: 'XDSButton 或 XDSIconButton 子元素。',
+ label: '按钮组的无障碍标签 (aria-label)。',
+ orientation: '按钮组的布局方向。',
+ size: '组内按钮的默认尺寸。单个按钮可覆盖。',
+ isDisabled: '组内所有按钮是否禁用。',
+ ref: '转发到根元素的引用。',
+ xstyle: 'StyleX 样式,用于布局自定义。必须是 stylex.create() 的值。',
+ 'data-testid': '自动化测试的选择器。',
+ },
+ },
+ ],
+ usage: {
+ description:
+ 'ButtonGroup 将相关操作连接成一个控件。当多个按钮表示对同一对象的相关操作时使用 — 如复制/剪切/粘贴,或撤销/重做。',
+ bestPractices: [
+ {guidance: true, description: '将对同一对象执行相关操作的按钮分组 — 如对选中文本的复制、剪切、粘贴。'},
+ {guidance: true, description: '组内所有按钮使用相同的变体,使其看起来像一个连接的整体。'},
+ {guidance: true, description: '保持组较小(2-4 个按钮)。更多操作请使用工具栏或下拉菜单。'},
+ {guidance: false, description: '不要混合差异很大的操作 — 将保存按钮和删除按钮放在同一组中会令人困惑。'},
+ {guidance: false, description: '不要使用 ButtonGroup 进行导航 — 使用 SegmentedControl 或 TabList 切换视图。'},
+ {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组,请并排放置并留有间隔。'},
+ ],
+ anatomy: [
+ {name: '按钮', required: true, description: '一个或多个 XDSButton 或 XDSIconButton 子元素,形成连接的组。'},
+ {name: '分隔线', required: false, description: '按钮之间的细边框,由组自动渲染。'},
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'connected button group w/ shared borders, outer-only radius, horizontal/vertical',
+ usage: {
+ description:
+ 'ButtonGroup joins related actions into a single connected control. Use for related operations on the same object.',
+ bestPractices: [
+ {guidance: true, description: 'Group related actions on the same object — copy/cut/paste, undo/redo.'},
+ {guidance: true, description: 'Same variant for all buttons to look like one unit.'},
+ {guidance: true, description: 'Keep groups small (2–4 buttons). Use Toolbar or DropdownMenu for more.'},
+ {guidance: false, description: "Don't mix unrelated actions in one group."},
+ {guidance: false, description: "Don't use for navigation — use SegmentedControl or TabList."},
+ {guidance: false, description: "Don't nest ButtonGroups."},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSButtonGroup',
+ description: 'connected button group w/ shared borders, outer-only radius',
+ propDescriptions: {
+ children: 'XDSButton or XDSIconButton children',
+ label: 'a11y label (aria-label)',
+ orientation: 'layout direction',
+ size: 'default btn size; individual btns override',
+ isDisabled: 'all btns disabled',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ 'data-testid': 'test selector',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx b/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx
new file mode 100644
index 0000000000..b1cb40f3c7
--- /dev/null
+++ b/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx
@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file XDSButtonGroup.test.tsx
+ * @input Uses vitest, @testing-library/react, ButtonGroup and Button components
+ * @output Unit tests for XDSButtonGroup
+ * @position Testing; validates ButtonGroup component implementation
+ *
+ * SYNC: When ButtonGroup component changes, update tests to match new behavior
+ */
+
+import {createRef} from 'react';
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSButtonGroup} from './XDSButtonGroup';
+import {XDSButton} from '../Button';
+import {XDSIconButton} from '../IconButton';
+
+describe('XDSButtonGroup', () => {
+ it('renders a group with aria-label', () => {
+ render(
+ <XDSButtonGroup label="Actions">
+ <XDSButton label="Copy" />
+ <XDSButton label="Cut" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>,
+ );
+
+ const group = screen.getByRole('group');
+ expect(group).toBeInTheDocument();
+ expect(group).toHaveAttribute('aria-label', 'Actions');
+ });
+
+ it('renders all child buttons', () => {
+ render(
+ <XDSButtonGroup label="Actions">
+ <XDSButton label="Copy" />
+ <XDSButton label="Cut" />
+ <XDSButton label="Paste" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Cut'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Paste'})).toBeInTheDocument();
+ });
+
+ it('works with XDSIconButton children', () => {
+ render(
+ <XDSButtonGroup label="Text formatting">
+ <XDSIconButton
+ label="Bold"
+ icon={<span data-testid="bold-icon">B</span>}
+ />
+ <XDSIconButton
+ label="Italic"
+ icon={<span data-testid="italic-icon">I</span>}
+ />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('button', {name: 'Bold'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Italic'})).toBeInTheDocument();
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSButtonGroup label="Actions" data-testid="my-group">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByTestId('my-group')).toBeInTheDocument();
+ });
+
+ it('forwards ref to the root element', () => {
+ const ref = createRef<HTMLDivElement>();
+ render(
+ <XDSButtonGroup label="Actions" ref={ref}>
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(ref.current).toBeInstanceOf(HTMLDivElement);
+ expect(ref.current).toBe(screen.getByRole('group'));
+ });
+
+ it('sets aria-orientation', () => {
+ const {rerender} = render(
+ <XDSButtonGroup label="Actions">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('group')).toHaveAttribute(
+ 'aria-orientation',
+ 'horizontal',
+ );
+
+ rerender(
+ <XDSButtonGroup label="Actions" orientation="vertical">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('group')).toHaveAttribute(
+ 'aria-orientation',
+ 'vertical',
+ );
+ });
+
+ it('renders with vertical orientation', () => {
+ render(
+ <XDSButtonGroup label="Actions" orientation="vertical">
+ <XDSButton label="Copy" />
+ <XDSButton label="Cut" />
+ </XDSButtonGroup>,
+ );
+
+ const group = screen.getByRole('group');
+ expect(group).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Cut'})).toBeInTheDocument();
+ });
+
+ it('renders with different sizes', () => {
+ const {rerender} = render(
+ <XDSButtonGroup label="Actions" size="sm">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();
+
+ rerender(
+ <XDSButtonGroup label="Actions" size="lg">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();
+ });
+
+ it('disables all buttons when isDisabled is true', () => {
+ render(
+ <XDSButtonGroup label="Actions" isDisabled>
+ <XDSButton label="Copy" />
+ <XDSButton label="Cut" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('group')).toHaveAttribute('aria-disabled', 'true');
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeDisabled();
+ expect(screen.getByRole('button', {name: 'Cut'})).toBeDisabled();
+ });
+
+ it('does not set aria-disabled when not disabled', () => {
+ render(
+ <XDSButtonGroup label="Actions">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('group')).not.toHaveAttribute('aria-disabled');
+ });
+
+ it('renders a single button without errors', () => {
+ render(
+ <XDSButtonGroup label="Actions">
+ <XDSButton label="Copy" />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();
+ });
+
+ it('renders mixed Button and IconButton children', () => {
+ render(
+ <XDSButtonGroup label="Edit actions">
+ <XDSButton label="Edit" />
+ <XDSIconButton label="More options" icon={<span>▼</span>} />
+ </XDSButtonGroup>,
+ );
+
+ expect(screen.getByRole('button', {name: 'Edit'})).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'More options'}),
+ ).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/ButtonGroup/XDSButtonGroup.tsx b/packages/core/src/ButtonGroup/XDSButtonGroup.tsx
new file mode 100644
index 0000000000..bec618dbb7
--- /dev/null
+++ b/packages/core/src/ButtonGroup/XDSButtonGroup.tsx
@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSButtonGroup.tsx
+ * @input Uses React, StyleX, XDSButton/XDSIconButton children
+ * @output Exports XDSButtonGroup component, context, and types
+ * @position Groups buttons with connected styling; consumed by index.ts
+ *
+ * Children (XDSButton, XDSIconButton) consume the ButtonGroup context to
+ * apply position-aware styles using CSS :first-child / :last-child
+ * pseudo-classes — no cloneElement or wrapper divs needed.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/ButtonGroup/ButtonGroup.doc.mjs (props table, features)
+ * - /packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx (tests)
+ * - /packages/core/src/ButtonGroup/index.ts (exports if types change)
+ * - /apps/storybook/stories/ButtonGroup.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/ButtonGroup/ (showcase blocks)
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {XDSButtonSize} from '../Button';
+import {XDSSizeProvider, useXDSSize} from '../SizeContext/XDSSizeContext';
+import {useListFocus} from '../hooks/useListFocus';
+import {xdsClassName, mergeProps} from '../utils';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import {XDSButtonGroupContext} from './XDSButtonGroupContext';
+import type {XDSButtonGroupOrientation} from './XDSButtonGroupContext';
+
+// =============================================================================
+// Props
+// =============================================================================
+
+export interface XDSButtonGroupProps extends XDSBaseProps<HTMLDivElement> {
+ /** Ref forwarded to the root element. */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * XDSButton or XDSIconButton children.
+ */
+ children: ReactNode;
+
+ /**
+ * Accessible label for the group (used as aria-label).
+ */
+ label: string;
+
+ /**
+ * Orientation of the button group.
+ * @default 'horizontal'
+ */
+ orientation?: XDSButtonGroupOrientation;
+
+ /**
+ * Default size for buttons in the group.
+ * Individual buttons can override this with their own `size` prop.
+ * @default 'md'
+ */
+ size?: XDSButtonSize;
+
+ /**
+ * 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',
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * 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 using CSS :first-child / :last-child pseudo-classes.
+ *
+ * @example
+ * ```
+ * <XDSButtonGroup label="Actions">
+ * <XDSButton label="Copy" />
+ * <XDSButton label="Cut" />
+ * <XDSButton label="Paste" />
+ * </XDSButtonGroup>
+ * ```
+ */
+export function XDSButtonGroup({
+ children,
+ label,
+ orientation = 'horizontal',
+ size: sizeProp,
+ isDisabled = false,
+ xstyle,
+ className,
+ style,
+ ref,
+ 'data-testid': testId,
+ ...props
+}: XDSButtonGroupProps): ReactNode {
+ const size = useXDSSize(sizeProp, 'md');
+
+ const {listRef, handleKeyDown} = useListFocus({
+ itemSelector: 'button, [tabindex="0"]',
+ orientation,
+ });
+
+ const contextValue = useMemo(
+ () => ({orientation, isDisabled}),
+ [orientation, isDisabled],
+ );
+
+ return (
+ <XDSButtonGroupContext.Provider value={contextValue}>
+ <XDSSizeProvider value={size}>
+ <div
+ ref={(node: HTMLDivElement | null) => {
+ (listRef as React.MutableRefObject<HTMLElement | null>).current =
+ node;
+ if (typeof ref === 'function') ref(node);
+ else if (ref)
+ (ref as React.MutableRefObject<HTMLDivElement | null>).current =
+ node;
+ }}
+ role="group"
+ aria-label={label}
+ onKeyDown={handleKeyDown}
+ aria-orientation={orientation}
+ aria-disabled={isDisabled || undefined}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('button-group', {size}),
+ stylex.props(
+ styles.group,
+ orientation === 'vertical' && styles.vertical,
+ xstyle,
+ ),
+ className,
+ style,
+ )}
+ {...props}>
+ {children}
+ </div>
+ </XDSSizeProvider>
+ </XDSButtonGroupContext.Provider>
+ );
+}
+
+XDSButtonGroup.displayName = 'XDSButtonGroup';
diff --git a/packages/core/src/ButtonGroup/XDSButtonGroupContext.ts b/packages/core/src/ButtonGroup/XDSButtonGroupContext.ts
new file mode 100644
index 0000000000..2ee8aab029
--- /dev/null
+++ b/packages/core/src/ButtonGroup/XDSButtonGroupContext.ts
@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSButtonGroupContext.ts
+ * @input None (pure context definition)
+ * @output Exports ButtonGroup context and useXDSButtonGroup hook
+ * @position Shared context; consumed by XDSButton for group-aware styling
+ */
+
+import {createContext, useContext} from 'react';
+
+export type XDSButtonGroupOrientation = 'horizontal' | 'vertical';
+
+export interface XDSButtonGroupContextValue {
+ orientation: XDSButtonGroupOrientation;
+ isDisabled: boolean;
+}
+
+export const XDSButtonGroupContext =
+ createContext<XDSButtonGroupContextValue | null>(null);
+
+/**
+ * Hook for XDSButton to detect when it's inside a ButtonGroup.
+ * Returns null when used outside a group.
+ */
+export function useXDSButtonGroup(): XDSButtonGroupContextValue | null {
+ return useContext(XDSButtonGroupContext);
+}
diff --git a/packages/core/src/ButtonGroup/index.ts b/packages/core/src/ButtonGroup/index.ts
new file mode 100644
index 0000000000..bc40a596b7
--- /dev/null
+++ b/packages/core/src/ButtonGroup/index.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from XDSButtonGroup.tsx and XDSButtonGroupContext.ts
+ * @output Exports XDSButtonGroup, context hook, and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+
+export {XDSButtonGroup} from './XDSButtonGroup';
+export type {XDSButtonGroupProps} from './XDSButtonGroup';
+
+export {useXDSButtonGroup} from './XDSButtonGroupContext';
+export type {XDSButtonGroupOrientation} from './XDSButtonGroupContext';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 25f287421e..8e03e29c90 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -23,6 +23,7 @@ export * from './Banner';
export * from './Blockquote';
export * from './Breadcrumbs';
export * from './Button';
+export * from './ButtonGroup';
export * from './IconButton';
export * from './Card';
export * from './ClickableCard';