Skip to content

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

TypeScript

feat(SideNav): resizable sidebar with drag handle (#658)

Cindy Zhang2c50d6ba849f
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
index 47d07111f0..0fec286925 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
@@ -116,6 +116,7 @@ interface ShellConfig {
showSubheading: boolean;
showNestedItems: boolean;
isCollapsible: boolean;
+ isResizable: boolean;
collapseToggleLocation: 'sidenav' | 'topnav';
mobileNavMode: 'auto' | 'customContent' | 'customToggle' | 'disabled';
mobileNavSide: 'start' | 'end';
@@ -139,6 +140,7 @@ const DEFAULT_CONFIG: ShellConfig = {
showSubheading: false,
showNestedItems: true,
isCollapsible: true,
+ isResizable: false,
collapseToggleLocation: 'sidenav',
mobileNavMode: 'auto',
mobileNavSide: 'start',
@@ -271,6 +273,11 @@ function ConfigPanel({
]}
/>
)}
+ <ToggleRow
+ label="Resizable"
+ value={config.isResizable}
+ onChange={v => onChange({isResizable: v})}
+ />
</XDSVStack>
<XDSDivider />
@@ -486,6 +493,7 @@ function SampleSideNav({
: true
: false
}
+ resizable={config.isResizable}
header={heading}
topContent={
config.showTopContent ? (
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 32dce59b02..ba14abce70 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -13,6 +13,7 @@ export const docs = {
'Collapsible sidebar via collapsible prop — collapses to icon-only toolbar, uncontrolled or controlled',
'Accessible — nav landmark, aria-current="page", role="group" with aria-labelledby on sections',
'Keyboard navigable — Tab through items, Enter/Space to activate',
+ 'Resizable sidebar via resizable prop — drag handle at inline-end edge, pointer-based resize with min/max constraints',
],
accessibility: [
'<nav aria-label="Side navigation"> wraps the entire component',
diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsx
index 1478165605..91b42b66dc 100644
--- a/packages/core/src/SideNav/XDSSideNav.test.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx
@@ -8,7 +8,7 @@
*/
import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {forwardRef, type ComponentPropsWithoutRef} from 'react';
import {XDSSideNav} from './XDSSideNav';
@@ -395,6 +395,77 @@ describe('XDSSideNavSection', () => {
});
});
+// =============================================================================
+// Resizable
+// =============================================================================
+
+describe('XDSSideNav resizable', () => {
+ it('renders drag handle when resizable', () => {
+ render(<XDSSideNav resizable>Content</XDSSideNav>);
+ expect(screen.getByTestId('xds-sidenav-resize-handle')).toBeInTheDocument();
+ });
+
+ it('does not render drag handle without resizable', () => {
+ render(<XDSSideNav>Content</XDSSideNav>);
+ expect(
+ screen.queryByTestId('xds-sidenav-resize-handle'),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not render drag handle when collapsed', () => {
+ render(
+ <XDSSideNav
+ resizable
+ collapsible={{isCollapsed: true, onCollapsedChange: () => {}}}>
+ Content
+ </XDSSideNav>,
+ );
+ expect(
+ screen.queryByTestId('xds-sidenav-resize-handle'),
+ ).not.toBeInTheDocument();
+ });
+
+ it('calls onWidthChange after drag', () => {
+ const handleWidthChange = vi.fn();
+ render(
+ <XDSSideNav resizable={{onWidthChange: handleWidthChange}}>
+ Content
+ </XDSSideNav>,
+ );
+ const handle = screen.getByTestId('xds-sidenav-resize-handle');
+
+ // Simulate pointer drag sequence
+ act(() => {
+ handle.dispatchEvent(
+ new PointerEvent('pointerdown', {
+ clientX: 260,
+ bubbles: true,
+ }),
+ );
+ document.dispatchEvent(
+ new PointerEvent('pointermove', {clientX: 310, bubbles: true}),
+ );
+ document.dispatchEvent(
+ new PointerEvent('pointerup', {clientX: 310, bubbles: true}),
+ );
+ });
+
+ expect(handleWidthChange).toHaveBeenCalledTimes(1);
+ expect(handleWidthChange).toHaveBeenCalledWith(expect.any(Number));
+ });
+
+ it('respects defaultWidth', () => {
+ render(<XDSSideNav resizable={{defaultWidth: 300}}>Content</XDSSideNav>);
+ const nav = screen.getByRole('navigation');
+ expect(nav.style.width).toBe('300px');
+ });
+
+ it('drag handle has separator role', () => {
+ render(<XDSSideNav resizable>Content</XDSSideNav>);
+ expect(screen.getByRole('separator')).toBeInTheDocument();
+ });
+});
+
// =============================================================================
// Integration
// =============================================================================
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 8891a45fc2..bc4df6371f 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -7,6 +7,8 @@
* Sidebar navigation container with five zones: header + topContent (sticky together),
* children (scrollable), footer, and footerIcons (sticky bottom).
*
+ * Supports optional resize via drag handle at the inline-end edge.
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/XDSSideNav.test.tsx
@@ -26,6 +28,7 @@ import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';
import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';
import {useXDSSideNavRenderMode} from './XDSSideNavRenderContext';
import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
+import {useResizable} from './useResizable';
// =============================================================================
// Styles
@@ -125,6 +128,31 @@ const styles = stylex.create({
alignItems: 'center',
gap: spacingVars['--spacing-1'],
},
+ // Resizable container — wraps the nav and the drag handle
+ resizableContainer: {
+ position: 'relative',
+ display: 'flex',
+ flexShrink: 0,
+ height: '100%',
+ },
+ // Drag handle at the inline-end edge
+ dragHandle: {
+ position: 'absolute',
+ insetInlineEnd: 0,
+ top: 0,
+ bottom: 0,
+ width: 6,
+ cursor: 'col-resize',
+ zIndex: 2,
+ // Invisible by default; visible on hover
+ backgroundColor: 'transparent',
+ transition: 'background-color 0.15s ease',
+ touchAction: 'none',
+ },
+ dragHandleHover: {
+ // Applied via @media (hover: hover) in the component
+ backgroundColor: colorVars['--color-divider'],
+ },
// Topbar mode — horizontal layout for mobile top bar
topbar: {
display: 'flex',
@@ -198,6 +226,24 @@ export interface XDSSideNavProps extends XDSBaseProps<HTMLElement> {
*/
'data-testid'?: string;
+ /**
+ * Enables a drag handle at the inline-end edge for resizing the sidebar.
+ * When collapsed, the drag handle is hidden.
+ *
+ * - `true` — resizable with defaults (260px initial width)
+ * - Object — configured:
+ * - `defaultWidth` — initial width in pixels (default: 260)
+ * - `onWidthChange` — called when user finishes resizing
+ *
+ * @default false
+ */
+ resizable?:
+ | boolean
+ | {
+ defaultWidth?: number;
+ onWidthChange?: (width: number) => void;
+ };
+
/**
* Enables collapse behavior. The sidebar can be collapsed to a narrow
* icon-only toolbar.
@@ -251,6 +297,7 @@ export function XDSSideNav({
footer,
footerIcons,
collapsible = false,
+ resizable = false,
xstyle,
className,
style,
@@ -266,6 +313,10 @@ export function XDSSideNav({
const controlledCollapsed = collapsibleConfig.isCollapsed;
const onCollapsedChange = collapsibleConfig.onCollapsedChange;
+ // Resizable config
+ const resizableConfig = typeof resizable === 'object' ? resizable : {};
+ const isResizable = !!resizable;
+
// Collapse state (controlled + uncontrolled)
const isControlled = controlledCollapsed !== undefined;
const [uncontrolledCollapsed, setUncontrolledCollapsed] =
@@ -286,6 +337,21 @@ export function XDSSideNav({
isCollapsible,
};
+ // =========================================================================
+ // Resize — extracted into useResizable hook
+ // =========================================================================
+ const {
+ width,
+ containerRef,
+ showHandle: showResizeHandle,
+ handleProps: resizeHandleProps,
+ isHandleHovered,
+ } = useResizable({
+ enabled: isResizable,
+ config: resizableConfig,
+ collapsed,
+ });
+
// Render mode — when inside AppShell mobile layout, render subsets
const renderMode = useXDSSideNavRenderMode();
@@ -361,7 +427,12 @@ export function XDSSideNav({
const hasStickyTop = !!(header || topContent);
const hasStickyBottom = !!(footer || footerIcons);
- const content = (
+ // When resizable, override the nav width via inline style
+ const resizableNavStyle: React.CSSProperties | undefined = isResizable
+ ? {...(style ?? {}), width: collapsed ? undefined : width}
+ : style;
+
+ const navElement = (
<nav
ref={ref}
role="navigation"
@@ -371,7 +442,7 @@ export function XDSSideNav({
xdsClassName('side-nav'),
stylex.props(styles.root, collapsed && styles.rootCollapsed, xstyle),
className,
- style,
+ resizableNavStyle,
)}
{...props}>
{hasStickyTop && (
@@ -412,6 +483,29 @@ export function XDSSideNav({
</nav>
);
+ // Wrap in resizable container when isResizable
+ const content = showResizeHandle ? (
+ <div
+ ref={containerRef}
+ {...stylex.props(styles.resizableContainer)}
+ style={{width}}>
+ {navElement}
+ <div
+ data-testid="xds-sidenav-resize-handle"
+ role="separator"
+ aria-orientation="vertical"
+ aria-label="Resize sidebar"
+ {...stylex.props(
+ styles.dragHandle,
+ isHandleHovered && styles.dragHandleHover,
+ )}
+ {...resizeHandleProps}
+ />
+ </div>
+ ) : (
+ navElement
+ );
+
if (isCollapsible) {
return (
<XDSSideNavCollapseContext value={collapseContext}>
diff --git a/packages/core/src/SideNav/useResizable.ts b/packages/core/src/SideNav/useResizable.ts
new file mode 100644
index 0000000000..2959096347
--- /dev/null
+++ b/packages/core/src/SideNav/useResizable.ts
@@ -0,0 +1,133 @@
+/**
+ * @file useResizable.ts
+ * @input Resizable configuration (enabled, defaultWidth, onWidthChange)
+ * @output Hook return: width state, containerRef, drag handle props, showHandle flag
+ * @position Internal hook; consumed by XDSSideNav.tsx
+ *
+ * Extracts all resize-related state and pointer event listeners into a
+ * standalone hook so event listeners are only registered when resizable
+ * is enabled.
+ */
+
+import {useCallback, useEffect, useRef, useState} from 'react';
+
+const MIN_WIDTH = 180;
+const MAX_WIDTH = 480;
+const DEFAULT_WIDTH = 260;
+
+export interface ResizableConfig {
+ defaultWidth?: number;
+ onWidthChange?: (width: number) => void;
+}
+
+export interface UseResizableOptions {
+ /** Whether resizing is enabled */
+ enabled: boolean;
+ /** Resizable configuration (defaultWidth, onWidthChange) */
+ config: ResizableConfig;
+ /** Whether the sidebar is collapsed (hides the handle) */
+ collapsed: boolean;
+}
+
+export interface UseResizableReturn {
+ /** Current width in pixels */
+ width: number;
+ /** Ref to attach to the resizable container div */
+ containerRef: React.RefObject<HTMLDivElement | null>;
+ /** Whether the drag handle should be rendered */
+ showHandle: boolean;
+ /** Props to spread onto the drag handle element */
+ handleProps: {
+ onPointerDown: (e: React.PointerEvent) => void;
+ onPointerEnter: () => void;
+ onPointerLeave: () => void;
+ };
+ /** Whether the handle is currently hovered */
+ isHandleHovered: boolean;
+}
+
+export function useResizable({
+ enabled,
+ config,
+ collapsed,
+}: UseResizableOptions): UseResizableReturn {
+ const {defaultWidth = DEFAULT_WIDTH, onWidthChange} = config;
+
+ const [width, setWidth] = useState(
+ Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, defaultWidth)),
+ );
+ const containerRef = useRef<HTMLDivElement>(null);
+ const isDraggingRef = useRef(false);
+ const startXRef = useRef(0);
+ const startWidthRef = useRef(0);
+ const [isHandleHovered, setIsHandleHovered] = useState(false);
+
+ const handlePointerDown = useCallback(
+ (e: React.PointerEvent) => {
+ if (!enabled) return;
+ e.preventDefault();
+ isDraggingRef.current = true;
+ startXRef.current = e.clientX;
+ startWidthRef.current = width;
+ document.body.style.cursor = 'col-resize';
+
+ const onPointerMove = (moveEvent: PointerEvent) => {
+ if (!isDraggingRef.current) return;
+ const delta = moveEvent.clientX - startXRef.current;
+ const newWidth = Math.min(
+ MAX_WIDTH,
+ Math.max(MIN_WIDTH, startWidthRef.current + delta),
+ );
+ if (containerRef.current) {
+ containerRef.current.style.width = `${newWidth}px`;
+ }
+ };
+
+ const onPointerUp = (upEvent: PointerEvent) => {
+ isDraggingRef.current = false;
+ document.body.style.cursor = '';
+ document.removeEventListener('pointermove', onPointerMove);
+ document.removeEventListener('pointerup', onPointerUp);
+
+ const delta = upEvent.clientX - startXRef.current;
+ const finalWidth = Math.min(
+ MAX_WIDTH,
+ Math.max(MIN_WIDTH, startWidthRef.current + delta),
+ );
+ setWidth(finalWidth);
+ onWidthChange?.(finalWidth);
+ };
+
+ document.addEventListener('pointermove', onPointerMove);
+ document.addEventListener('pointerup', onPointerUp);
+ },
+ [enabled, width, onWidthChange],
+ );
+
+ // Clean up listeners if component unmounts during drag
+ useEffect(() => {
+ return () => {
+ if (isDraggingRef.current) {
+ document.body.style.cursor = '';
+ }
+ };
+ }, []);
+
+ const showHandle = enabled && !collapsed;
+
+ const handleProps = {
+ onPointerDown: handlePointerDown,
+ onPointerEnter: () => setIsHandleHovered(true),
+ onPointerLeave: () => {
+ if (!isDraggingRef.current) setIsHandleHovered(false);
+ },
+ };
+
+ return {
+ width,
+ containerRef,
+ showHandle,
+ handleProps,
+ isHandleHovered,
+ };
+}