Skip to content

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

TypeScript

feat(Banner): add collapsible content area with expand/collapse toggle (#326)

rubyycheung31ddb1616a85
diff --git a/apps/storybook/stories/Banner.stories.tsx b/apps/storybook/stories/Banner.stories.tsx
index c37549ccda..501615ad7d 100644
--- a/apps/storybook/stories/Banner.stories.tsx
+++ b/apps/storybook/stories/Banner.stories.tsx
@@ -24,6 +24,11 @@ const meta: Meta<typeof XDSBanner> = {
description:
'Whether the banner can be dismissed (manages its own hidden state)',
},
+ isDefaultExpanded: {
+ control: 'boolean',
+ description:
+ 'Whether the content area starts expanded (only relevant when children are provided)',
+ },
},
};
@@ -104,12 +109,58 @@ export const SectionVariant: Story = {
},
};
+export const CollapsibleContent: Story = {
+ name: 'Collapsible Content (Collapsed)',
+ args: {
+ status: 'info',
+ title: 'Emphasized Text',
+ description: 'Description text',
+ endButton: <XDSButton label="Button" variant="secondary" size="sm" />,
+ isDismissable: true,
+ children: (
+ <div
+ style={{
+ fontSize: '13px',
+ padding: '40px',
+ textAlign: 'center',
+ color: '#999',
+ }}>
+ Flex Slot
+ </div>
+ ),
+ },
+};
+
+export const CollapsibleContentExpanded: Story = {
+ name: 'Collapsible Content (Expanded)',
+ args: {
+ status: 'info',
+ title: 'Emphasized Text',
+ description: 'Description text',
+ isDefaultExpanded: true,
+ endButton: <XDSButton label="Button" variant="secondary" size="sm" />,
+ isDismissable: true,
+ children: (
+ <div
+ style={{
+ fontSize: '13px',
+ padding: '40px',
+ textAlign: 'center',
+ color: '#999',
+ }}>
+ Flex Slot
+ </div>
+ ),
+ },
+};
+
export const WithContentArea: Story = {
name: 'With Content Area (Card Background)',
args: {
status: 'error',
title: 'Multiple errors found',
description: 'The following issues need to be resolved:',
+ isDefaultExpanded: true,
children: (
<ul style={{margin: 0, paddingInlineStart: '20px', fontSize: '13px'}}>
<li>Email address is invalid</li>
@@ -128,6 +179,7 @@ export const ContentAreaWithAction: Story = {
description: 'Review the changes before they take effect.',
endButton: <XDSButton label="Review" variant="secondary" size="sm" />,
isDismissable: true,
+ isDefaultExpanded: true,
children: (
<div style={{fontSize: '13px'}}>
<p style={{margin: '0 0 8px'}}>Changed settings:</p>
@@ -181,13 +233,24 @@ export const AllFeatures: Story = {
/>
<XDSBanner
status="error"
- title="With content area"
- description="Additional content appears on a card background below.">
+ title="With collapsible content"
+ description="Click the chevron to expand."
+ isDismissable>
<div style={{fontSize: '13px'}}>
This content sits on a card-colored background, visually distinct from
the status header above.
</div>
</XDSBanner>
+ <XDSBanner
+ status="success"
+ title="Expanded by default"
+ description="This content area starts open."
+ isDefaultExpanded
+ isDismissable>
+ <div style={{fontSize: '13px'}}>
+ Content is visible immediately because isDefaultExpanded is true.
+ </div>
+ </XDSBanner>
<XDSBanner
status="error"
title="Section variant"
diff --git a/packages/core/src/Banner/XDSBanner.test.tsx b/packages/core/src/Banner/XDSBanner.test.tsx
index 2b47fa7d6e..0001a1ff29 100644
--- a/packages/core/src/Banner/XDSBanner.test.tsx
+++ b/packages/core/src/Banner/XDSBanner.test.tsx
@@ -162,18 +162,92 @@ describe('XDSBanner', () => {
expect(root).toBeInTheDocument();
});
- it('renders children in a separate content area below header', () => {
- const {container} = render(
- <XDSBanner status="info" title="With Children" description="Desc">
+ // =========================================================================
+ // Collapsible content area
+ // =========================================================================
+
+ it('hides children by default (collapsed)', () => {
+ render(
+ <XDSBanner status="info" title="Collapsible">
+ <div data-testid="child-content">Extra content</div>
+ </XDSBanner>,
+ );
+ expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
+ });
+
+ it('shows children when isDefaultExpanded is true', () => {
+ render(
+ <XDSBanner status="info" title="Expanded" isDefaultExpanded>
<div data-testid="child-content">Extra content</div>
</XDSBanner>,
);
expect(screen.getByTestId('child-content')).toBeInTheDocument();
- expect(screen.getByText('Extra content')).toBeInTheDocument();
- // Children should be in a separate div from the header (the content area)
- const root = container.firstElementChild;
- // Root should have 2 child divs: header + content area
- expect(root?.children).toHaveLength(2);
+ });
+
+ it('shows expand button when children are provided', () => {
+ render(
+ <XDSBanner status="info" title="With Toggle">
+ <div>Content</div>
+ </XDSBanner>,
+ );
+ expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
+ });
+
+ it('does not show expand/collapse button when no children', () => {
+ render(<XDSBanner status="info" title="No Children" />);
+ expect(
+ screen.queryByRole('button', {name: 'Expand'}),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Collapse'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('toggles children visibility on expand/collapse click', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSBanner status="info" title="Toggle Test">
+ <div data-testid="child-content">Extra content</div>
+ </XDSBanner>,
+ );
+
+ // Initially collapsed
+ expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
+
+ // Click to expand
+ await user.click(screen.getByRole('button', {name: 'Expand'}));
+ expect(screen.getByTestId('child-content')).toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Collapse'})).toBeInTheDocument();
+
+ // Click to collapse
+ await user.click(screen.getByRole('button', {name: 'Collapse'}));
+ expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
+ expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
+ });
+
+ it('shows collapse button when isDefaultExpanded', () => {
+ render(
+ <XDSBanner status="info" title="Expanded" isDefaultExpanded>
+ <div>Content</div>
+ </XDSBanner>,
+ );
+ expect(screen.getByRole('button', {name: 'Collapse'})).toBeInTheDocument();
+ });
+
+ it('renders expand button to the left of dismiss button', () => {
+ const {container} = render(
+ <XDSBanner status="info" title="Order Test" isDismissable>
+ <div>Content</div>
+ </XDSBanner>,
+ );
+ const buttons = container.querySelectorAll('button');
+ const buttonNames = Array.from(buttons).map(
+ b => b.getAttribute('aria-label') || b.textContent,
+ );
+ const expandIndex = buttonNames.indexOf('Expand');
+ const dismissIndex = buttonNames.indexOf('Dismiss');
+ expect(expandIndex).toBeLessThan(dismissIndex);
});
it('does not render content area when no children', () => {
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 8a7aaf1a04..e0dcc4706c 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -6,8 +6,9 @@
*
* Visual structure:
* - Header area: colored status background with icon, title, description, actions, dismiss
- * - Content area (optional): card background below the header for additional content (children)
+ * - Content area (optional): collapsible card background below the header for additional content (children)
* - No left border accent — color is expressed through the full header background
+ * - When children are provided, a collapse/expand toggle button appears in the end area
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Banner/README.md (props table, features, implementation notes)
@@ -24,6 +25,8 @@ import {
ExclamationTriangleIcon,
XCircleIcon,
CheckCircleIcon,
+ ChevronDownIcon,
+ ChevronUpIcon,
} from '@heroicons/react/24/solid';
import {XDSButton} from '../Button';
import {XDSIcon} from '../Icon';
@@ -97,9 +100,15 @@ export interface XDSBannerProps {
*/
variant?: XDSBannerVariant;
/**
- * Extra content rendered below the header in a card-background area.
+ * Whether the content area (children) starts expanded.
+ * Only relevant when children are provided.
+ * @default false
+ */
+ isDefaultExpanded?: boolean;
+ /**
+ * Extra content rendered below the header in a collapsible card-background area.
* Use for rich content like lists, links, or detailed information.
- * Only renders when provided — without children, only the colored header shows.
+ * When provided, a collapse/expand toggle button appears in the header.
*/
children?: ReactNode;
/**
@@ -257,7 +266,11 @@ const statusStyles = stylex.create({
*
* Two-part visual structure:
* - Header: colored status background with icon, title, description, and actions
- * - Content (optional): card background area for additional rich content
+ * - Content (optional): collapsible card background area for additional rich content
+ *
+ * When children are provided, a collapse/expand chevron button appears in the
+ * header end area (to the left of the dismiss button if present). Clicking it
+ * toggles the visibility of the content area.
*
* Manages its own dismissed state internally — the banner hides on dismiss
* even if `onDismiss` is not provided, so product teams don't need to wire
@@ -279,17 +292,27 @@ const statusStyles = stylex.create({
* onDismiss={() => logDismiss()}
* />
*
- * // With extra content in card area below
+ * // With collapsible content area
* <XDSBanner
* status="error"
* title="Multiple errors found"
* description="The following issues need to be resolved:"
+ * isDismissable
* >
* <ul>
* <li>Email address is invalid</li>
* <li>Password must be at least 8 characters</li>
* </ul>
* </XDSBanner>
+ *
+ * // Content area expanded by default
+ * <XDSBanner
+ * status="warning"
+ * title="Configuration changes"
+ * isDefaultExpanded
+ * >
+ * <p>Details here...</p>
+ * </XDSBanner>
* ```
*/
export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
@@ -303,6 +326,7 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
onDismiss,
endButton,
variant = 'card',
+ isDefaultExpanded = false,
children,
xstyle,
'data-testid': testId,
@@ -310,9 +334,11 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
ref,
) => {
const [isDismissed, setIsDismissed] = useState(false);
+ const [isExpanded, setIsExpanded] = useState(isDefaultExpanded);
const DefaultIcon = defaultIcons[status];
const role = statusRole[status];
const iconColor = statusIconColor[status];
+ const hasChildren = children != null;
if (isDismissed) {
return null;
@@ -323,6 +349,12 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
onDismiss?.();
};
+ const handleToggleExpand = () => {
+ setIsExpanded(prev => !prev);
+ };
+
+ // Show the end area if there are actions, dismiss, or a collapsible toggle
+ const showEndArea = endButton != null || isDismissable || hasChildren;
// Center items vertically when there's only a title (no description)
// and the banner has action buttons
const hasActions = endButton != null || isDismissable;
@@ -359,9 +391,26 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
<p {...stylex.props(styles.description)}>{description}</p>
)}
</div>
- {(endButton != null || isDismissable) && (
+ {showEndArea && (
<div {...stylex.props(styles.endArea)}>
{endButton}
+ {hasChildren && (
+ <XDSButton
+ variant="ghost"
+ size="sm"
+ label={isExpanded ? 'Collapse' : 'Expand'}
+ tooltip={isExpanded ? 'Collapse' : 'Expand'}
+ icon={
+ <XDSIcon
+ icon={isExpanded ? ChevronUpIcon : ChevronDownIcon}
+ size="sm"
+ color="inherit"
+ />
+ }
+ onClick={handleToggleExpand}
+ aria-expanded={isExpanded}
+ />
+ )}
{isDismissable && (
<div {...stylex.props(styles.dismissButton)}>
<XDSButton
@@ -377,8 +426,8 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
</div>
)}
</div>
- {/* Content area: card background for additional content */}
- {children != null && (
+ {/* Content area: collapsible card background for additional content */}
+ {hasChildren && isExpanded && (
<div
{...stylex.props(
styles.contentArea,