Skip to content

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

TypeScript

feat(Button): add endSlot prop (#331)

rubyycheung568415b10337
diff --git a/apps/storybook/stories/Button.stories.tsx b/apps/storybook/stories/Button.stories.tsx
index 6abb8898ac..99b0dbc971 100644
--- a/apps/storybook/stories/Button.stories.tsx
+++ b/apps/storybook/stories/Button.stories.tsx
@@ -1,5 +1,6 @@
import type {Meta, StoryObj} from '@storybook/react';
import {XDSButton} from '@xds/core/Button';
+import {XDSBadge} from '@xds/core/Badge';
import {Cog6ToothIcon, TrashIcon} from '@heroicons/react/24/outline';
const meta: Meta<typeof XDSButton> = {
@@ -29,6 +30,10 @@ const meta: Meta<typeof XDSButton> = {
control: 'boolean',
description: 'Disabled state',
},
+ endSlot: {
+ control: false,
+ description: 'Content rendered after the label (e.g. icon, badge)',
+ },
},
};
@@ -125,6 +130,44 @@ export const IconWithText: Story = {
),
};
+export const WithEndSlot: Story = {
+ render: () => (
+ <div style={{display: 'flex', gap: '12px', alignItems: 'center'}}>
+ <XDSButton
+ label="Messages"
+ variant="primary"
+ endSlot={<XDSBadge variant="info">3</XDSBadge>}
+ />
+ <XDSButton
+ label="Notifications"
+ variant="secondary"
+ endSlot={<XDSBadge variant="neutral">New</XDSBadge>}
+ />
+ </div>
+ ),
+};
+
+export const IconAndEndSlot: Story = {
+ render: () => (
+ <div style={{display: 'flex', gap: '12px', alignItems: 'center'}}>
+ <XDSButton
+ label="Settings"
+ variant="secondary"
+ icon={<Cog6ToothIcon style={{width: 16, height: 16}} />}
+ endSlot={<XDSBadge variant="info">New</XDSBadge>}>
+ Settings
+ </XDSButton>
+ <XDSButton
+ label="Delete"
+ variant="destructive"
+ icon={<TrashIcon style={{width: 16, height: 16}} />}
+ endSlot={<XDSBadge variant="error">5</XDSBadge>}>
+ Delete
+ </XDSButton>
+ </div>
+ ),
+};
+
export const AllVariants: Story = {
render: () => (
<div
diff --git a/packages/core/src/Button/README.md b/packages/core/src/Button/README.md
index 76b6190216..55073b5317 100644
--- a/packages/core/src/Button/README.md
+++ b/packages/core/src/Button/README.md
@@ -38,6 +38,10 @@ import { XDSButton } from '@xds/core/Button';
// Icon + visible label (pass children to show text alongside icon)
<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>
+
+// With endSlot — badge or trailing icon after the label
+<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
+<XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>
```
### Icon-Only Buttons
@@ -54,16 +58,17 @@ or `<span onClick>` for accessibility (keyboard navigation, focus management, sc
## Props
-| Prop | Type | Default | Description |
-| ------------ | ------------------------------------------------------ | ------------- | --------------------------- |
-| `label` | `string` | — | Accessible label (required) |
-| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | `'secondary'` | Visual style variant |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
-| `isLoading` | `boolean` | `false` | Shows isLoading spinner |
-| `isDisabled` | `boolean` | `false` | Disables the button |
-| `icon` | `ReactNode` | — | Icon element |
-| `children` | `ReactNode` | — | Button content |
-| `tooltip` | `string` | — | Tooltip text shown on hover |
+| Prop | Type | Default | Description |
+| ------------ | ----------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label` | `string` | — | Accessible label (required) |
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | `'secondary'` | Visual style variant |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
+| `isLoading` | `boolean` | `false` | Shows isLoading spinner |
+| `isDisabled` | `boolean` | `false` | Disables the button |
+| `icon` | `ReactNode` | — | Icon element |
+| `children` | `ReactNode` | — | Button content |
+| `endSlot` | `ReactElement<XDSIconProps> \| ReactElement<XDSBadgeProps>` | — | Trailing icon or badge after the label. Only accepts `<XDSIcon>` or `<XDSBadge>`. Ignored for icon-only. Color is inherited from the button variant. |
+| `tooltip` | `string` | — | Tooltip text shown on hover |
## Files
@@ -73,8 +78,25 @@ or `<span onClick>` for accessibility (keyboard navigation, focus management, sc
| `XDSButton.tsx` | Core | XDSButton component implementation |
| `XDSButton.test.tsx` | Test | Unit tests for XDSButton component |
+### endSlot
+
+The `endSlot` prop renders an `<XDSIcon>` or `<XDSBadge>` after the label text:
+
+```tsx
+// Counter badge
+<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
+
+// Icon + label + endSlot
+<XDSButton label="Settings" icon={<GearIcon />} endSlot={<XDSBadge>New</XDSBadge>}>
+ Settings
+</XDSButton>
+```
+
+`endSlot` is ignored for icon-only buttons (when `icon` is provided without `children`) to preserve the square aspect ratio. The endSlot is wrapped in a container that inherits the button's text color (`color: inherit`), so `<XDSIcon>` elements will automatically match the button variant's color (e.g., white text on `primary`/`destructive` variants) without needing an explicit `color` prop.
+
## Implementation Notes
- `XDSButtonVariant` type is derived from the `variants` StyleX object using `keyof typeof variants`
- Hover/active states use `backgroundImage` with `linear-gradient` to layer overlay colors on top of the base background
- Destructive variant uses `colorTokens.negative` for its focus outline color
+- `endSlot` is wrapped in a `<span>` with `color: inherit` so icons/badges match the button's text color across all variants
diff --git a/packages/core/src/Button/XDSButton.test.tsx b/packages/core/src/Button/XDSButton.test.tsx
index 14b1033728..25063ac363 100644
--- a/packages/core/src/Button/XDSButton.test.tsx
+++ b/packages/core/src/Button/XDSButton.test.tsx
@@ -11,6 +11,7 @@ import {describe, it, expect, vi} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSButton} from './XDSButton';
+import {XDSBadge} from '../Badge/XDSBadge';
describe('XDSButton', () => {
it('renders label as visible text', () => {
@@ -98,4 +99,100 @@ describe('XDSButton', () => {
render(<XDSButton label="Test" ref={ref} />);
expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement));
});
+
+ // endSlot tests
+ it('renders endSlot after label', () => {
+ render(
+ <XDSButton
+ label="Click me"
+ endSlot={<XDSBadge data-testid="end">3</XDSBadge>}
+ />,
+ );
+ const button = screen.getByRole('button');
+ expect(button).toHaveTextContent('Click me');
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+ expect(screen.getByTestId('end')).toHaveTextContent('3');
+ });
+
+ it('renders endSlot with children', () => {
+ render(
+ <XDSButton
+ label="Accessible name"
+ endSlot={<XDSBadge data-testid="end">New</XDSBadge>}>
+ Custom content
+ </XDSButton>,
+ );
+ const button = screen.getByRole('button');
+ expect(button).toHaveTextContent('Custom content');
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+ });
+
+ it('renders endSlot with icon and children', () => {
+ render(
+ <XDSButton
+ label="Settings"
+ icon={<span data-testid="icon">⚙</span>}
+ endSlot={<XDSBadge data-testid="end">New</XDSBadge>}>
+ Settings
+ </XDSButton>,
+ );
+ const button = screen.getByRole('button');
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ expect(button).toHaveTextContent('Settings');
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+
+ // Verify order: icon, text, endSlot wrapper
+ const children = Array.from(button.childNodes);
+ const iconIndex = children.findIndex(
+ n => n instanceof HTMLElement && n.dataset.testid === 'icon',
+ );
+ // endSlot is inside a wrapper span (direct child of button)
+ const endElement = screen.getByTestId('end');
+ const endWrapper = endElement.parentElement; // wrapper <span>
+ const endIndex = children.findIndex(n => n === endWrapper);
+ expect(iconIndex).toBeLessThan(endIndex);
+ });
+
+ it('does not render endSlot for icon-only buttons', () => {
+ render(
+ <XDSButton
+ label="Settings"
+ icon={<span data-testid="icon">⚙</span>}
+ endSlot={<XDSBadge data-testid="end">3</XDSBadge>}
+ />,
+ );
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ expect(screen.queryByTestId('end')).not.toBeInTheDocument();
+ });
+
+ it('wraps endSlot in a container for color inheritance', () => {
+ render(
+ <XDSButton
+ label="Test"
+ endSlot={<XDSBadge data-testid="end">3</XDSBadge>}
+ />,
+ );
+ const badge = screen.getByTestId('end');
+ // The badge should be inside a wrapper span that inherits color
+ const wrapper = badge.parentElement;
+ expect(wrapper?.tagName).toBe('SPAN');
+ // The wrapper should be a direct child of the button
+ expect(wrapper?.parentElement?.tagName).toBe('BUTTON');
+ });
+
+ it('hides endSlot content when loading', () => {
+ render(
+ <XDSButton
+ label="Submit"
+ isLoading
+ endSlot={<XDSBadge data-testid="end">3</XDSBadge>}
+ />,
+ );
+ // endSlot should still be in the DOM
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+ // Button should be disabled and have aria-busy
+ const button = screen.getByRole('button');
+ expect(button).toBeDisabled();
+ expect(button).toHaveAttribute('aria-busy', 'true');
+ });
});
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index c911e733e4..d16b5f97de 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -9,6 +9,8 @@
* - /packages/core/src/Button/XDSButton.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Button/index.ts (exports if types change)
* - /apps/storybook/stories/Button.stories.tsx (storybook stories)
+ *
+ * Last synced props: label, variant, size, isDisabled, isLoading, onClickAction, icon, children, tooltip, endSlot
*/
import {
@@ -33,6 +35,8 @@ import {
import {ThemeContext} from '../theme/ThemeContext';
import {XDSTooltip} from '../Layer/XDSTooltip';
import {XDSSpinner} from '../Spinner';
+import type {XDSIconProps} from '../Icon/XDSIcon';
+import type {XDSBadgeProps} from '../Badge/XDSBadge';
/**
* Base button styles
@@ -75,6 +79,11 @@ const styles = stylex.create({
aspectRatio: '1 / 1',
paddingInline: spacingVars['--spacing-2'],
},
+ endSlotWrapper: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ color: 'inherit',
+ },
});
const sizeStyles = stylex.create({
@@ -243,6 +252,17 @@ export interface XDSButtonProps extends Omit<
* button becomes icon-only with label used as aria-label.
*/
children?: ReactNode;
+ /**
+ * Content rendered after the label text.
+ * Only accepts `<XDSIcon>` or `<XDSBadge>` elements.
+ * Ignored for icon-only buttons to preserve square aspect ratio.
+ *
+ * The endSlot is wrapped in a container that inherits the button's text
+ * color, so `<XDSIcon>` elements will match the button variant's color
+ * (e.g., white on primary/destructive) without needing an explicit
+ * `color` prop.
+ */
+ endSlot?: ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>;
/**
* Tooltip text shown on hover.
*/
@@ -278,6 +298,10 @@ const loadingStyles = stylex.create({
*
* // Icon + visible label
* <XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>
+ *
+ * // With endSlot (badge or icon)
+ * <XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
+ * <XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>
* ```
*/
export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(
@@ -291,6 +315,7 @@ export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(
onClickAction,
icon,
children,
+ endSlot,
tooltip,
...props
},
@@ -354,6 +379,9 @@ export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(
)}
{icon}
{children ?? (isIconOnly ? null : label)}
+ {!isIconOnly && endSlot && (
+ <span {...stylex.props(styles.endSlotWrapper)}>{endSlot}</span>
+ )}
</button>
);