Skip to content

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

TypeScript

feat(TopNav): mobile responsive rendering (#565) (#652)

Cindy Zhanga1ff924be6fd
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 877cd959d6..151af29800 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -40,6 +40,8 @@ import {XDSLayoutContent} from '../Layout/XDSLayoutContent';
import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';
import {XDSSideNavRenderContext} from '../SideNav/XDSSideNavRenderContext';
+import {XDSTopNavRenderContext} from '../TopNav/XDSTopNavRenderContext';
+import {XDSTopNavMobileContentContext} from '../TopNav/XDSTopNavMobileContentContext';
import {XDSAppShellMobileContext} from './XDSAppShellMobileContext';
import type {XDSAppShellMobileContextValue} from './XDSAppShellMobileContext';
import type {SpacingStep} from '../utils/types';
@@ -553,7 +555,7 @@ export function XDSAppShell({
// efficient and does not over-trigger.
// =========================================================================
useEffect(() => {
- if (sideNavBreakpoint === 'none' || !hasSideNav) return;
+ if (sideNavBreakpoint === 'none' || !hasNavContent) return;
const breakpointPx = BREAKPOINT_VALUES[sideNavBreakpoint];
const mql = window.matchMedia(`(max-width: ${breakpointPx}px)`);
@@ -568,7 +570,7 @@ export function XDSAppShell({
mql.addEventListener('change', handleChange);
return () => mql.removeEventListener('change', handleChange);
- }, [sideNavBreakpoint, hasSideNav]);
+ }, [sideNavBreakpoint, hasNavContent]);
// =========================================================================
// Determine if sideNav should show as overlay (mobile) or inline
@@ -577,16 +579,25 @@ export function XDSAppShell({
// Three mobile nav rendering modes:
// 1. ReactNode shorthand — render the user's element as-is (they own the drawer)
const shouldRenderMobileNavReactNode = mobileNavReactNode != null;
- // 2. Config with custom content — render inside AppShell-managed drawer
+ // 2. Config with custom content — render directly
const shouldRenderConfigContent =
mobileNavEnabled && mobileNavConfigContent != null && isBelowBreakpoint;
- // 3. Auto — wrap sideNav content in a managed drawer
+ // 3. Auto — render nav content in drawer mode
const shouldRenderAutoMobileNav =
mobileNavEnabled &&
!mobileNavReactNode &&
!mobileNavConfigContent &&
isBelowBreakpoint &&
- hasSideNav;
+ hasNavContent;
+ // TopNav-only auto mobile (no SideNav) — TopNav handles its own drawer
+ const shouldRenderTopNavDrawer =
+ shouldRenderAutoMobileNav && hasTopNav && !hasSideNav;
+ // TopNav + SideNav combined — TopNav owns drawer, SideNav content via context
+ const shouldRenderCombinedDrawer =
+ shouldRenderAutoMobileNav && hasTopNav && hasSideNav;
+ // SideNav-only auto mobile (no TopNav) — SideNav handles its own drawer
+ const shouldRenderSideNavDrawer =
+ shouldRenderAutoMobileNav && !hasTopNav && hasSideNav;
// =========================================================================
// Mobile context — shared with XDSMobileNavToggle and future TopNav mobile
@@ -610,6 +621,17 @@ export function XDSAppShell({
// stays pinned while the page scrolls. The ref is used to measure header
// height for the sideNav's sticky offset.
// =========================================================================
+ // When below breakpoint, TopNav renders in mobile-bar mode (heading + endContent + toggle)
+ const topNavContent = hasTopNav ? (
+ isBelowBreakpoint && mobileNavEnabled ? (
+ <XDSTopNavRenderContext value="mobile-bar">
+ {topNav}
+ </XDSTopNavRenderContext>
+ ) : (
+ topNav
+ )
+ ) : null;
+
const headerInner =
hasTopNav || hasBanner ? (
<XDSLayoutHeader
@@ -617,7 +639,7 @@ export function XDSAppShell({
hasDivider={navHasDividers && hasTopNav}
xstyle={navAreaStyle}>
{hasBanner && <div {...stylex.props(styles.banner)}>{banner}</div>}
- {hasTopNav && topNav}
+ {topNavContent}
</XDSLayoutHeader>
) : undefined;
@@ -763,13 +785,32 @@ export function XDSAppShell({
content={mainContent}
/>
- {/* Mobile nav — three modes:
+ {/* Mobile nav — rendering modes:
1. ReactNode shorthand: render user's element as-is
- 2. Config content: render inside AppShell-managed drawer
- 3. Auto: wrap sideNav in a managed drawer */}
+ 2. Config content: render directly
+ 3. TopNav-only: TopNav renders its own drawer
+ 4. TopNav+SideNav: TopNav owns drawer, SideNav passed via context
+ 5. SideNav-only: SideNav renders its own drawer */}
{shouldRenderMobileNavReactNode && mobileNavReactNode}
{shouldRenderConfigContent && mobileNavConfigContent}
- {shouldRenderAutoMobileNav && (
+ {shouldRenderTopNavDrawer && (
+ <XDSTopNavRenderContext value="drawer">
+ {topNav}
+ </XDSTopNavRenderContext>
+ )}
+ {shouldRenderCombinedDrawer && (
+ <XDSTopNavMobileContentContext
+ value={
+ <XDSSideNavRenderContext value="drawer-content">
+ {sideNav}
+ </XDSSideNavRenderContext>
+ }>
+ <XDSTopNavRenderContext value="drawer">
+ {topNav}
+ </XDSTopNavRenderContext>
+ </XDSTopNavMobileContentContext>
+ )}
+ {shouldRenderSideNavDrawer && (
<XDSSideNavRenderContext value="drawer">
{sideNav}
</XDSSideNavRenderContext>
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 043783d594..aa60181aed 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -308,6 +308,20 @@ export function XDSSideNav({
);
}
+ // =========================================================================
+ // Drawer-content mode — render just items (no XDSMobileNav wrapper)
+ // Used when TopNav owns the drawer and SideNav items are nested inside
+ // =========================================================================
+ if (renderMode === 'drawer-content') {
+ return (
+ <>
+ {topContent}
+ {children}
+ {footer}
+ </>
+ );
+ }
+
// =========================================================================
// Default mode — full sidebar
// =========================================================================
diff --git a/packages/core/src/SideNav/XDSSideNavRenderContext.ts b/packages/core/src/SideNav/XDSSideNavRenderContext.ts
index dd0ca498fd..01e4fdf62c 100644
--- a/packages/core/src/SideNav/XDSSideNavRenderContext.ts
+++ b/packages/core/src/SideNav/XDSSideNavRenderContext.ts
@@ -13,7 +13,11 @@
import {createContext, useContext} from 'react';
-export type XDSSideNavRenderMode = 'default' | 'topbar' | 'drawer';
+export type XDSSideNavRenderMode =
+ | 'default'
+ | 'topbar'
+ | 'drawer'
+ | 'drawer-content';
export const XDSSideNavRenderContext =
createContext<XDSSideNavRenderMode>('default');
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 4880a72b71..81313b9381 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -20,6 +20,10 @@ import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {edgeSignals} from '../Layout/edgeCompensation.stylex';
import {xdsClassName, mergeProps} from '../utils';
import {TopNavSlotContext} from './TopNavContext';
+import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
+import {useXDSTopNavMobileContent} from './XDSTopNavMobileContentContext';
+import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
+import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';
/**
* Base TopNav styles
@@ -81,6 +85,30 @@ const styles = stylex.create({
flexShrink: 0,
marginInlineStart: 'auto',
},
+ // Mobile bar mode — simplified top bar with heading + toggle + endContent
+ mobileBar: {
+ display: 'flex',
+ alignItems: 'center',
+ width: '100%',
+ height: spacingVars['--spacing-12'],
+ paddingInline: spacingVars['--spacing-4'],
+ boxSizing: 'border-box',
+ },
+ mobileBarEnd: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ marginInlineStart: 'auto',
+ },
+ // Drawer mode — vertical list of nav items
+ drawerItems: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ },
+ drawerExtraContent: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ },
});
export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {
@@ -144,7 +172,64 @@ export function XDSTopNav({
ref,
...props
}: XDSTopNavProps) {
+ const renderMode = useXDSTopNavRenderMode();
+ const mobileContent = useXDSTopNavMobileContent();
const hasCenterContent = centerContent != null;
+ const hasCollapsibleContent = startContent != null || centerContent != null;
+
+ // =========================================================================
+ // Mobile bar mode — heading + endContent + toggle, hide nav items
+ // =========================================================================
+ if (renderMode === 'mobile-bar') {
+ return (
+ <nav
+ ref={ref}
+ role="navigation"
+ aria-label={label}
+ {...mergeProps(
+ xdsClassName('top-nav', {mode: 'mobile-bar'}),
+ stylex.props(styles.mobileBar, xstyle),
+ className,
+ style,
+ )}
+ {...props}>
+ {heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
+ <div {...stylex.props(styles.mobileBarEnd)}>
+ {endContent}
+ {hasCollapsibleContent && <XDSMobileNavToggle />}
+ </div>
+ </nav>
+ );
+ }
+
+ // =========================================================================
+ // Drawer mode — render nav items vertically inside a MobileNav,
+ // plus any additional content passed via context (e.g. SideNav items)
+ // =========================================================================
+ if (renderMode === 'drawer') {
+ // Only render if there are collapsible items or extra content
+ if (!hasCollapsibleContent && !mobileContent) return null;
+
+ return (
+ <XDSMobileNav header={heading}>
+ {hasCollapsibleContent && (
+ <div {...stylex.props(styles.drawerItems)}>
+ {startContent}
+ {centerContent}
+ </div>
+ )}
+ {mobileContent && (
+ <div {...stylex.props(styles.drawerExtraContent)}>
+ {mobileContent}
+ </div>
+ )}
+ </XDSMobileNav>
+ );
+ }
+
+ // =========================================================================
+ // Default mode — full top bar
+ // =========================================================================
return (
<nav
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index 923a81027b..d947e6f2e6 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -27,6 +27,7 @@ import {
} from '../theme/tokens.stylex';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
import {xdsClassName, mergeProps} from '../utils';
/**
@@ -83,6 +84,44 @@ const styles = stylex.create({
iconOnly: {
paddingInline: spacingVars['--spacing-2'],
},
+ // Drawer mode — SideNavItem-style vertical list element
+ drawerItem: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-3'],
+ width: '100%',
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderRadius: radiusVars['--radius-element'],
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-base'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ color: colorVars['--color-text-secondary'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ boxSizing: 'border-box',
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-hover-overlay'],
+ },
+ ':active': colorVars['--color-pressed-overlay'],
+ },
+ outline: {
+ default: null,
+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,
+ },
+ },
+ drawerItemSelected: {
+ color: colorVars['--color-text-primary'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ backgroundColor: {
+ default: colorVars['--color-deemphasized'],
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-deemphasized'],
+ },
+ },
+ },
});
export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {
@@ -164,9 +203,42 @@ export function XDSTopNavItem({
...props
}: XDSTopNavItemProps) {
const LinkComponent = useXDSLinkComponent(as);
+ const renderMode = useXDSTopNavRenderMode();
const isIconOnly = icon != null && children == null && !label;
const showLabel = !isIconOnly;
+ // =========================================================================
+ // Drawer mode — render as a SideNavItem-style vertical list element
+ // =========================================================================
+ if (renderMode === 'drawer') {
+ return (
+ <LinkComponent
+ ref={ref}
+ aria-current={isSelected ? 'page' : undefined}
+ aria-disabled={isDisabled || undefined}
+ tabIndex={isDisabled ? -1 : undefined}
+ {...mergeProps(
+ xdsClassName('top-nav-item', {mode: 'drawer'}),
+ stylex.props(
+ styles.drawerItem,
+ isSelected && styles.drawerItemSelected,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}
+ {...props}>
+ {icon}
+ {children ?? label}
+ </LinkComponent>
+ );
+ }
+
+ // =========================================================================
+ // Default / mobile-bar mode — standard horizontal nav item
+ // =========================================================================
+
return (
<LinkComponent
ref={ref}
diff --git a/packages/core/src/TopNav/XDSTopNavMobileContentContext.ts b/packages/core/src/TopNav/XDSTopNavMobileContentContext.ts
new file mode 100644
index 0000000000..d72c1de7ce
--- /dev/null
+++ b/packages/core/src/TopNav/XDSTopNavMobileContentContext.ts
@@ -0,0 +1,22 @@
+/**
+ * @file XDSTopNavMobileContentContext.ts
+ * @input React createContext, useContext
+ * @output Exports XDSTopNavMobileContentContext and useXDSTopNavMobileContent
+ * @position Internal context for passing additional drawer content to TopNav
+ *
+ * When both TopNav and SideNav exist, AppShell passes the SideNav content
+ * to TopNav via this context. TopNav renders it below its own items in the
+ * mobile drawer, producing a single combined drawer.
+ */
+
+import {createContext, useContext, type ReactNode} from 'react';
+
+export const XDSTopNavMobileContentContext = createContext<ReactNode>(null);
+
+/**
+ * Read additional mobile drawer content provided by AppShell.
+ * Returns null when no additional content is available.
+ */
+export function useXDSTopNavMobileContent(): ReactNode {
+ return useContext(XDSTopNavMobileContentContext);
+}
diff --git a/packages/core/src/TopNav/XDSTopNavRenderContext.ts b/packages/core/src/TopNav/XDSTopNavRenderContext.ts
new file mode 100644
index 0000000000..d95c190f5e
--- /dev/null
+++ b/packages/core/src/TopNav/XDSTopNavRenderContext.ts
@@ -0,0 +1,26 @@
+/**
+ * @file XDSTopNavRenderContext.ts
+ * @input React createContext, useContext
+ * @output Exports XDSTopNavRenderContext and useXDSTopNavRenderMode hook
+ * @position Internal context for controlling TopNav rendering mode
+ *
+ * When AppShell renders TopNav in multiple locations (top bar, mobile drawer),
+ * this context tells TopNav and its children which parts to render:
+ * - 'default': full top bar (desktop)
+ * - 'mobile-bar': heading + endContent + toggle, hide nav items (mobile top bar)
+ * - 'drawer': nav items as vertical list elements (mobile drawer)
+ */
+
+import {createContext, useContext} from 'react';
+
+export type XDSTopNavRenderMode = 'default' | 'mobile-bar' | 'drawer';
+
+export const XDSTopNavRenderContext =
+ createContext<XDSTopNavRenderMode>('default');
+
+/**
+ * Read the current TopNav render mode from context.
+ */
+export function useXDSTopNavRenderMode(): XDSTopNavRenderMode {
+ return useContext(XDSTopNavRenderContext);
+}
diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.ts
index 97e2901404..6ef476f07c 100644
--- a/packages/core/src/TopNav/index.ts
+++ b/packages/core/src/TopNav/index.ts
@@ -25,3 +25,9 @@ export type {
XDSTopNavMegaMenuItemData,
XDSTopNavMegaMenuFeatured,
} from './XDSTopNavMegaMenu';
+
+export {
+ XDSTopNavRenderContext,
+ useXDSTopNavRenderMode,
+} from './XDSTopNavRenderContext';
+export type {XDSTopNavRenderMode} from './XDSTopNavRenderContext';