Skip to content

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

TypeScript

feat(TopNav): add centerContent slot for centered navigation layout (#240)

rubyycheung9c9a0da0b240
diff --git a/apps/sandbox/src/app/Sidebar.tsx b/apps/sandbox/src/app/Sidebar.tsx
index c867de60a7..42c3b061ee 100644
--- a/apps/sandbox/src/app/Sidebar.tsx
+++ b/apps/sandbox/src/app/Sidebar.tsx
@@ -19,6 +19,7 @@ import {usePathname} from 'next/navigation';
const pages = [
{name: 'Home', href: '/'},
{name: 'Example', href: '/pages/example/'},
+ {name: 'Navigation', href: '/pages/navigation/'},
{name: 'TopNav Menu', href: '/pages/topnav-menu/'},
];
diff --git a/apps/sandbox/src/app/pages/navigation/page.tsx b/apps/sandbox/src/app/pages/navigation/page.tsx
new file mode 100644
index 0000000000..b27e680bcb
--- /dev/null
+++ b/apps/sandbox/src/app/pages/navigation/page.tsx
@@ -0,0 +1,135 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSButton} from '@xds/core/Button';
+import {XDSDivider} from '@xds/core';
+import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
+
+const styles = stylex.create({
+ container: {
+ maxWidth: 960,
+ },
+ navWrapper: {
+ border: '1px solid #e0e0e0',
+ borderRadius: 8,
+ overflow: 'hidden',
+ },
+});
+
+type Alignment = 'start' | 'center' | 'end';
+
+/**
+ * Navigation exploration page.
+ *
+ * Demonstrates XDSTopNav with nav items aligned to start (left),
+ * center, or end (right) using the slot-based API.
+ */
+export default function NavigationPage() {
+ const [alignment, setAlignment] = useState<Alignment>('start');
+
+ return (
+ <div {...stylex.props(styles.container)}>
+ <XDSVStack gap="space6">
+ <XDSVStack gap="space2">
+ <XDSHeading level={1}>Navigation Alignment</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Explore how nav items can be positioned left, center, or right using
+ XDSTopNav&apos;s slot-based API.
+ </XDSText>
+ </XDSVStack>
+
+ {/* Alignment picker */}
+ <XDSHStack gap="space3" vAlign="center">
+ <XDSText type="body" weight="bold">
+ Alignment:
+ </XDSText>
+ <XDSButton
+ label="Left"
+ variant={alignment === 'start' ? 'primary' : 'secondary'}
+ size="sm"
+ onPress={() => setAlignment('start')}
+ />
+ <XDSButton
+ label="Center"
+ variant={alignment === 'center' ? 'primary' : 'secondary'}
+ size="sm"
+ onPress={() => setAlignment('center')}
+ />
+ <XDSButton
+ label="Right"
+ variant={alignment === 'end' ? 'primary' : 'secondary'}
+ size="sm"
+ onPress={() => setAlignment('end')}
+ />
+ </XDSHStack>
+
+ <XDSDivider />
+
+ {/* Live preview */}
+ <XDSVStack gap="space3">
+ <XDSHeading level={2}>Preview</XDSHeading>
+ <div {...stylex.props(styles.navWrapper)}>
+ <NavPreview alignment={alignment} />
+ </div>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* All three side by side */}
+ <XDSVStack gap="space4">
+ <XDSHeading level={2}>All Alignments</XDSHeading>
+
+ <XDSVStack gap="space2">
+ <XDSText type="supporting" weight="bold">
+ Left-aligned (startContent)
+ </XDSText>
+ <div {...stylex.props(styles.navWrapper)}>
+ <NavPreview alignment="start" />
+ </div>
+ </XDSVStack>
+
+ <XDSVStack gap="space2">
+ <XDSText type="supporting" weight="bold">
+ Center-aligned (centerContent)
+ </XDSText>
+ <div {...stylex.props(styles.navWrapper)}>
+ <NavPreview alignment="center" />
+ </div>
+ </XDSVStack>
+
+ <XDSVStack gap="space2">
+ <XDSText type="supporting" weight="bold">
+ Right-aligned (endContent)
+ </XDSText>
+ <div {...stylex.props(styles.navWrapper)}>
+ <NavPreview alignment="end" />
+ </div>
+ </XDSVStack>
+ </XDSVStack>
+ </XDSVStack>
+ </div>
+ );
+}
+
+const navItems = (
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavItem label="Products" href="#" />
+ <XDSTopNavItem label="About" href="#" />
+ </>
+);
+
+function NavPreview({alignment}: {alignment: Alignment}) {
+ return (
+ <XDSTopNav
+ label={`${alignment}-aligned navigation`}
+ title={<XDSTopNavTitle title="My App" />}
+ startContent={alignment === 'start' ? navItems : undefined}
+ centerContent={alignment === 'center' ? navItems : undefined}
+ endContent={alignment === 'end' ? navItems : undefined}
+ />
+ );
+}
diff --git a/apps/storybook/stories/TopNav.stories.tsx b/apps/storybook/stories/TopNav.stories.tsx
index 015396f365..8c30d1849e 100644
--- a/apps/storybook/stories/TopNav.stories.tsx
+++ b/apps/storybook/stories/TopNav.stories.tsx
@@ -187,6 +187,86 @@ export const TitleIconSizes: Story = {
),
};
+export const CenteredNavigation: Story = {
+ render: () => (
+ <XDSTopNav
+ label="Main navigation"
+ title={
+ <XDSTopNavTitle
+ title="My App"
+ logo={
+ <XDSTopNavTitleIcon
+ icon={<CubeIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ href="#"
+ />
+ }
+ centerContent={
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavItem label="Products" href="#" />
+ <XDSTopNavItem label="About" href="#" />
+ </>
+ }
+ endContent={
+ <>
+ <XDSButton
+ label="Search"
+ variant="ghost"
+ icon={<MagnifyingGlassIcon style={{width: 16, height: 16}} />}
+ />
+ <XDSButton
+ label="Profile"
+ variant="ghost"
+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}
+ />
+ </>
+ }
+ />
+ ),
+};
+
+export const CenteredWithStartContent: Story = {
+ render: () => (
+ <XDSTopNav
+ label="Main navigation"
+ title={
+ <XDSTopNavTitle
+ title="Dashboard"
+ logo={
+ <XDSTopNavTitleIcon
+ icon={<ChartBarIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ href="#"
+ />
+ }
+ startContent={
+ <XDSTopNavItem
+ label="Back"
+ href="#"
+ icon={<HomeIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ centerContent={
+ <>
+ <XDSTopNavItem label="Overview" href="#" isSelected />
+ <XDSTopNavItem label="Analytics" href="#" />
+ <XDSTopNavItem label="Reports" href="#" />
+ </>
+ }
+ endContent={
+ <XDSButton
+ label="Profile"
+ variant="ghost"
+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ />
+ ),
+};
+
export const FullExample: Story = {
render: () => (
<XDSTopNav
diff --git a/internal/vibe-tests/src/screenshot.ts b/internal/vibe-tests/src/screenshot.ts
index cbc90a6d92..3b8575161c 100644
--- a/internal/vibe-tests/src/screenshot.ts
+++ b/internal/vibe-tests/src/screenshot.ts
@@ -37,7 +37,9 @@ function parseArgs(): {iteration: string; prompt?: string} {
}
if (!iteration) {
- console.error('Usage: tsx src/screenshot.ts --iteration <id> [--prompt <promptId>]');
+ console.error(
+ 'Usage: tsx src/screenshot.ts --iteration <id> [--prompt <promptId>]',
+ );
process.exit(1);
}
@@ -153,7 +155,9 @@ async function main() {
await server.listen();
const serverUrl = 'http://localhost:5174';
- console.log(`πŸ“Έ Capturing screenshots for ${promptIds.length} components...\n`);
+ console.log(
+ `πŸ“Έ Capturing screenshots for ${promptIds.length} components...\n`,
+ );
const browser = await chromium.launch();
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index 10978ea902..0b3b2c650e 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -6,7 +6,7 @@ Top navigation bar component for application headers.
## Features
-- **Slot-based layout**: `title`, `startContent`, `endContent` for flexible organization
+- **Slot-based layout**: `title`, `startContent`, `centerContent`, `endContent` for flexible organization
- **Companion components**: XDSTopNavTitle, XDSTopNavTitleIcon, XDSTopNavItem
- **Accessible**: Proper ARIA roles and keyboard navigation
- **Themeable**: Uses XDS design tokens for styling
@@ -72,12 +72,13 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
### XDSTopNav
-| Prop | Type | Default | Description |
-| -------------- | ----------- | ------- | ----------------------------------------------------- |
-| `title` | `ReactNode` | β€” | Title slot (logo, brand) - left aligned |
-| `startContent` | `ReactNode` | β€” | Start content (nav items, breadcrumbs) - left aligned |
-| `endContent` | `ReactNode` | β€” | End content (search, icons, profile) - right aligned |
-| `label` | `string` | β€” | Accessible label for navigation landmark |
+| Prop | Type | Default | Description |
+| --------------- | ----------- | ------- | ------------------------------------------------------------------ |
+| `title` | `ReactNode` | β€” | Title slot (logo, brand) - left aligned |
+| `startContent` | `ReactNode` | β€” | Start content (nav items, breadcrumbs) - left aligned |
+| `centerContent` | `ReactNode` | β€” | Center content (nav items) - centered; enables three-column layout |
+| `endContent` | `ReactNode` | β€” | End content (search, icons, profile) - right aligned |
+| `label` | `string` | β€” | Accessible label for navigation landmark |
### XDSTopNavTitle
@@ -192,6 +193,8 @@ import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
## Slot Layout Structure
+**Standard layout** (no `centerContent`):
+
```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ [title] [startContent ...] [...endContent] β”‚
@@ -199,10 +202,24 @@ import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```
+**Three-column layout** (with `centerContent`):
+
+```
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ [title] [start...] [centerContent...] [...endContent] β”‚
+β”‚ └─ flex: 1 ──────── centered ──────────── flex: 1 ─────────
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+When `centerContent` is provided, the left and right sections flex equally
+(`flex: 1 1 0%`) so the center content stays visually centered regardless
+of how much content is in the start or end slots.
+
## Implementation Notes
- XDSTopNav uses `role="navigation"` and accepts `aria-label` via the `label` prop
-- Title and startContent are in a flex container that grows to push endContent right
+- Without `centerContent`: title and startContent grow to push endContent right
+- With `centerContent`: left and right sections use equal flex basis for true centering
- XDSTopNavItem supports `aria-current="page"` when `isSelected` is true
- XDSTopNavTitleIcon uses `--color-accent` background with `--color-icon-on-media` for contrast
- Default height is 48px with 16px horizontal padding
diff --git a/packages/core/src/TopNav/XDSTopNav.test.tsx b/packages/core/src/TopNav/XDSTopNav.test.tsx
index 04f90898c6..3f9eb0da94 100644
--- a/packages/core/src/TopNav/XDSTopNav.test.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.test.tsx
@@ -50,7 +50,31 @@ describe('XDSTopNav', () => {
expect(screen.getByTestId('end-content')).toBeInTheDocument();
});
+ it('renders centerContent slot', () => {
+ render(
+ <XDSTopNav
+ centerContent={<span data-testid="center-content">Center</span>}
+ />,
+ );
+ expect(screen.getByTestId('center-content')).toBeInTheDocument();
+ });
+
it('renders all slots together', () => {
+ render(
+ <XDSTopNav
+ title={<span data-testid="title">Title</span>}
+ startContent={<span data-testid="start">Start</span>}
+ centerContent={<span data-testid="center">Center</span>}
+ endContent={<span data-testid="end">End</span>}
+ />,
+ );
+ expect(screen.getByTestId('title')).toBeInTheDocument();
+ expect(screen.getByTestId('start')).toBeInTheDocument();
+ expect(screen.getByTestId('center')).toBeInTheDocument();
+ expect(screen.getByTestId('end')).toBeInTheDocument();
+ });
+
+ it('renders without centerContent (backward compatible)', () => {
render(
<XDSTopNav
title={<span data-testid="title">Title</span>}
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 409ed96827..f9547a41ef 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -39,7 +39,8 @@ const styles = stylex.create({
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-4'],
- flex: '1 1 auto',
+ flex: '1 1 0%',
+ minWidth: 0,
},
title: {
display: 'flex',
@@ -51,7 +52,23 @@ const styles = stylex.create({
alignItems: 'center',
gap: spacingVars['--spacing-1'],
},
+ centerContent: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-1'],
+ flexShrink: 0,
+ },
endContent: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'flex-end',
+ gap: spacingVars['--spacing-2'],
+ flex: '1 1 0%',
+ minWidth: 0,
+ },
+ // When there's no centerContent, revert to the simpler layout
+ endContentNoCenterContent: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
@@ -86,6 +103,12 @@ export interface XDSTopNavProps extends Omit<
* Positioned after the title, left-aligned.
*/
startContent?: ReactNode;
+ /**
+ * Center content slot - navigation items or content centered in the nav bar.
+ * When present, the layout switches to a three-column mode where
+ * start and end sections flex equally to keep center content visually centered.
+ */
+ centerContent?: ReactNode;
/**
* End content slot - typically search, icons, user profile, utility menus.
* Positioned at the right edge of the nav bar.
@@ -101,15 +124,20 @@ export interface XDSTopNavProps extends Omit<
/**
* Top navigation bar component for application headers.
*
- * Uses a slot-based API with `title`, `startContent`, and `endContent` props
- * for flexible layout. Title and startContent are left-aligned, endContent
- * is right-aligned.
+ * Uses a slot-based API with `title`, `startContent`, `centerContent`, and
+ * `endContent` props for flexible layout. Title and startContent are
+ * left-aligned, centerContent is centered, and endContent is right-aligned.
+ *
+ * When `centerContent` is provided, the layout switches to a three-column
+ * mode where the left and right sections flex equally to keep the center
+ * content visually centered in the nav bar.
*
* Positioning is handled by the layout system (e.g. XDSAppShell applies sticky
* behavior in auto height mode). TopNav itself is a pure content component.
*
* @example
* ```tsx
+ * // Standard layout (left + right)
* <XDSTopNav
* label="Main navigation"
* title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
@@ -126,12 +154,29 @@ export interface XDSTopNavProps extends Omit<
* </>
* }
* />
+ *
+ * // Centered layout (left + center + right)
+ * <XDSTopNav
+ * label="Main navigation"
+ * title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
+ * centerContent={
+ * <>
+ * <XDSTopNavItem label="Home" href="/" isSelected />
+ * <XDSTopNavItem label="Products" href="/products" />
+ * </>
+ * }
+ * endContent={<Avatar />}
+ * />
* ```
*/
export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(
- function XDSTopNav({title, startContent, endContent, label, ...props}, ref) {
+ function XDSTopNav(
+ {title, startContent, centerContent, endContent, label, ...props},
+ ref,
+ ) {
const themeContext = useContext(ThemeContext);
const rootOverride = themeContext?.theme.components?.topNav?.root;
+ const hasCenterContent = centerContent != null;
return (
<nav
@@ -146,8 +191,18 @@ export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(
<div {...stylex.props(styles.startContent)}>{startContent}</div>
)}
</div>
+ {hasCenterContent && (
+ <div {...stylex.props(styles.centerContent)}>{centerContent}</div>
+ )}
{endContent && (
- <div {...stylex.props(styles.endContent)}>{endContent}</div>
+ <div
+ {...stylex.props(
+ hasCenterContent
+ ? styles.endContent
+ : styles.endContentNoCenterContent,
+ )}>
+ {endContent}
+ </div>
)}
</nav>
);