An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file LayoutPanel.tsx
* @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext,
* useScrollRegionProps, resizablePane.ts
* @output Exports LayoutPanel component and LayoutPanelProps
* @position Sidebar panel for Layout start/end slots; its resize controller slides it.
* Use for navigation panels, settings sidebars, detail panels, or any fixed-width side content.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Layout/Layout.doc.mjs
* - /apps/storybook/stories/Layout.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)
*/
import type {AriaRole, ReactNode} from 'react';
import type {BaseProps} from '../BaseProps';
import {use, useCallback, useRef, useState, useSyncExternalStore} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {LayoutAreaContext} from './LayoutAreaContext';
import {LayoutSlotsContext} from './LayoutSlotsContext';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
import {mergeProps} from '../utils';
import type {SizeValue, SpacingStep} from '../utils/types';
import {
resizablePropsOf,
type ResizableProps,
type ResizableRegion,
} from '../Resizable/useResizable';
import {
createResizablePaneLink,
regionOfProps,
resizeHandleBeside,
} from '../Resizable/resizablePane';
import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {moveFocusLeftBehind, noteFocusWithin} from '../utils/focusReturn';
import {useFocusLeavingChange} from '../utils/useFocusLeavingChange';
import {themeProps} from '../utils/themeProps';
import {
paddingStyles,
containerPaddingInlineVarStyles,
containerPaddingBlockStartVarStyles,
containerPaddingBlockEndVarStyles,
} from './padding.stylex';
const styles = stylex.create({
panel: {
boxSizing: 'border-box',
flexShrink: 0,
overflow: 'clip',
paddingInlineStart: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
paddingInlineEnd: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
paddingBlockStart: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
paddingBlockEnd: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
'--container-padding-inline-start': `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
'--container-padding-inline-end': `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
'--container-padding-block-start': `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
'--container-padding-block-end': `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
},
// An edge on the Layout's boundary takes the Layout-edge inset. Each edge
// publishes the padding it applies, so full-bleed children line up with it.
startPanel: {
paddingInlineStart: `var(--layout-padding-own-outer-x, var(--layout-padding-outer-x, ${spacingVars['--spacing-4']}))`,
'--container-padding-inline-start': `var(--layout-padding-own-outer-x, var(--layout-padding-outer-x, ${spacingVars['--spacing-4']}))`,
},
endPanel: {
paddingInlineEnd: `var(--layout-padding-own-outer-x, var(--layout-padding-outer-x, ${spacingVars['--spacing-4']}))`,
'--container-padding-inline-end': `var(--layout-padding-own-outer-x, var(--layout-padding-outer-x, ${spacingVars['--spacing-4']}))`,
},
noHeader: {
paddingBlockStart: `var(--layout-padding-own-outer-y, var(--layout-padding-outer-y, ${spacingVars['--spacing-4']}))`,
'--container-padding-block-start': `var(--layout-padding-own-outer-y, var(--layout-padding-outer-y, ${spacingVars['--spacing-4']}))`,
},
noFooter: {
paddingBlockEnd: `var(--layout-padding-own-outer-y, var(--layout-padding-outer-y, ${spacingVars['--spacing-4']}))`,
'--container-padding-block-end': `var(--layout-padding-own-outer-y, var(--layout-padding-outer-y, ${spacingVars['--spacing-4']}))`,
},
fullBleed: {
paddingInlineStart: 0,
paddingInlineEnd: 0,
paddingBlockStart: 0,
paddingBlockEnd: 0,
'--container-padding-inline-start': '0px',
'--container-padding-inline-end': '0px',
'--container-padding-block-start': '0px',
'--container-padding-block-end': '0px',
},
scrollable: {
overflow: 'auto',
},
// At width 0 the padding box is 0 too, so the clip hides every child.
zeroWidth: {
paddingInlineStart: 0,
paddingInlineEnd: 0,
overflow: 'clip',
},
// For start panel: divider on end edge
dividerEnd: {
borderInlineEndWidth: 1,
borderInlineEndStyle: 'solid',
borderInlineEndColor: colorVars['--color-border'],
},
// For end panel: divider on start edge
dividerStart: {
borderInlineStartWidth: 1,
borderInlineStartStyle: 'solid',
borderInlineStartColor: colorVars['--color-border'],
},
// When no divider, collapse spacing on the side facing content
// Start panel: collapse end (right in LTR) to merge with content
// End panel: collapse start (left in LTR) to merge with content
collapseStart: {
marginInlineStart: `calc(-1 * var(--layout-padding-inner-x, ${spacingVars['--spacing-4']}))`,
},
collapseEnd: {
marginInlineEnd: `calc(-1 * var(--layout-padding-inner-x, ${spacingVars['--spacing-4']}))`,
},
});
const returnFalse = () => false;
// Dynamic styles for sizing props
const dynamicStyles = stylex.create({
sizing: (width: SizeValue | null) => ({
width,
}),
});
export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
/**
* Content to render inside the panel.
*/
children?: ReactNode;
/**
* Adds a themed border on the appropriate edge.
* - Start panel: border on end edge (right in LTR)
* - End panel: border on start edge (left in LTR)
* When false and `padding` is unset, the panel and the content share one gap.
*
* Note: When using `resizable` with an adjacent `ResizeHandle hasDivider`,
* set this to `false` to avoid a double-line artifact.
* @default false
*/
hasDivider?: boolean;
/**
* Internal padding of the panel on every edge, using the spacing scale.
* Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
* Replaces the automatic inset and the gap shared with the content.
* `0` is full bleed.
*/
padding?: SpacingStep;
/**
* Enables scrollable overflow for the panel.
* Set to false for auto-height layouts where sticky positioning
* needs to work with parent containers.
* @default true
*/
isScrollable?: boolean;
/**
* Accessible label for the landmark.
* Required when role is set and multiple landmarks of the same type exist.
* While the panel scrolls, it also names the scrolling region, which
* otherwise takes a translated "Content".
*/
label?: string;
/**
* ARIA landmark role for accessibility.
* Use 'navigation' or 'complementary' only for top-level layouts (not nested).
*/
role?: AriaRole;
/**
* Width of the panel.
* Numbers are treated as pixels, strings are used as-is.
* When `resizable` is provided, this is ignored — the hook controls width.
*/
width?: SizeValue;
/**
* The output of `useResizable()`, or its `props`. When provided, the panel
* width is driven by the hook and a resize handle should be placed
* adjacent to this panel.
*
* @example
* ```
* const resizable = useResizable({ defaultSize: 250, minSize: 200 });
* <LayoutPanel resizable={resizable}>
* <Navigation />
* </LayoutPanel>
* <ResizeHandle resizable={resizable} />
* ```
*/
resizable?: ResizableRegion | ResizableProps;
}
/**
* Sidebar or side panel for Layout. Use in the `start` slot for left navigation
* or in the `end` slot for detail/inspector panels.
* Renders with optional divider and context-aware padding.
* Divider position is auto-detected based on which slot the panel is in.
*
* Already provides its own padding and scroll — don't add padding or
* overflow to children. Use `padding={0}` if you need edge-to-edge content.
*
* @example
* ```
* <Card>
* <Layout
* start={
* <LayoutPanel hasDivider role="navigation">
* <Navigation />
* </LayoutPanel>
* }
* content={<LayoutContent>Main content</LayoutContent>}
* end={
* <LayoutPanel hasDivider role="complementary">
* <Sidebar />
* </LayoutPanel>
* }
* />
* </Card>
* ```
*/
export function LayoutPanel({
children,
hasDivider = false,
isScrollable = true,
label,
padding,
role,
width,
resizable: resizableValue,
xstyle,
className,
style,
ref,
...props
}: LayoutPanelProps) {
const resizable =
resizableValue == null ? undefined : resizablePropsOf(resizableValue);
const area = use(LayoutAreaContext);
const {hasHeader, hasFooter} = use(LayoutSlotsContext);
// When resizable props are provided, use the hook-driven size
const effectiveWidth = resizable ? resizable._size : width;
// A collapsed region sizes its panel to 0.
const isZeroWidth = effectiveWidth === 0;
const elementRef = useRef<HTMLDivElement>(null);
// A panel sized by a resize controller lends it its element. The
// controller slides it on collapse and open. Given the hook's own `props`,
// the panel hands itself to that region. With no `resizable`, a
// ResizeHandle beside it that has the region's props finds it and holds it
// collapsed. A hand-built `resizable` object has no region: it lends
// nothing and never slides.
const [paneLink] = useState(createResizablePaneLink);
const isHeldCollapsed = useSyncExternalStore(
paneLink.subscribe,
paneLink.isCollapsed,
returnFalse,
);
const isFoundBeside = resizable == null;
const paneRegion = resizable == null ? undefined : regionOfProps(resizable);
// Syncs the panel's element with its resize controller. It lends here, not
// in the callback ref. The scroll region's ref changes at width 0, so React
// runs every merged ref again. A lend taken back mid-collapse would land the
// slide.
useIsomorphicLayoutEffect(() => {
const isLent = isFoundBeside || paneRegion != null;
const lend = (element: HTMLDivElement | null) => {
const pane = paneLink.attach(isLent ? element : null, isFoundBeside);
paneRegion?.attach(pane);
};
lend(elementRef.current);
return () => {
lend(null);
};
}, [paneLink, isFoundBeside, paneRegion]);
const contentFacingEdge = area === 'end' ? 'inline-start' : 'inline-end';
// A collapse or open reaches the controller before the DOM changes, in the
// commit that renders it. That holds for the controller's own change and
// for a controlled `isCollapsed` it hears of after this commit.
const tellBeforeChange = useCallback(() => {
paneLink.beforeChange(isZeroWidth);
}, [paneLink, isZeroWidth]);
// Syncs the resize controller's pane link with the width and edge this
// commit rendered.
useIsomorphicLayoutEffect(() => {
paneLink.committed(effectiveWidth, contentFacingEdge);
});
// A collapsing panel moves focus inside it to its ResizeHandle, through the
// focus-leaving sequence that disclosures share. It goes inert and hidden
// from assistive technology a commit later, so inert never drops that focus
// to the page. Opening drops both at once. The ResizeHandle beside it holds
// the region's collapse state, or else the `resizable` props hold it.
const isRegionCollapsed =
resizable == null ? isHeldCollapsed : resizable._isCollapsed;
const noteFocusBeforeCollapse = useFocusLeavingChange(
isRegionCollapsed,
(wasCollapsed: boolean) =>
wasCollapsed ? null : noteFocusWithin(elementRef.current),
(noted, isCollapsed) => {
const panel = elementRef.current;
if (isCollapsed && panel != null) {
moveFocusLeftBehind(
noted,
paneLink.focusTarget() ?? resizeHandleBeside(panel, area),
panel,
);
}
},
);
const [isSettledCollapsed, setIsSettledCollapsed] =
useState(isRegionCollapsed);
if (!isRegionCollapsed && isSettledCollapsed) {
setIsSettledCollapsed(false);
}
// Syncs `inert` with the browser's focus: the panel goes inert only after
// this commit's focus move.
useIsomorphicLayoutEffect(() => {
if (isRegionCollapsed && !isSettledCollapsed) {
// eslint-disable-next-line @eslint-react/set-state-in-effect -- the panel goes inert only after the focus-leaving move above ran in this commit; inert in the collapsing commit would drop that focus to the page first
setIsSettledCollapsed(true);
}
}, [isRegionCollapsed, isSettledCollapsed]);
const isConcealed = isRegionCollapsed && isSettledCollapsed;
// Determine panel position
const isStartPanel = area === 'start';
const isEndPanel = area === 'end';
const isZeroPadding = padding === 0;
// When no divider, collapse spacing for seamless visual flow
const shouldCollapseSpacing =
!hasDivider && !isZeroPadding && padding == null && !isZeroWidth;
// At width 0 the panel clips its content, so it does not scroll.
const region = useScrollRegionProps({
isScrollable: isScrollable && !isZeroWidth,
role,
label,
});
const mergedRef = useMergedRefs(ref, region.ref, elementRef);
// Select divider style based on position
const dividerStyle = isStartPanel
? styles.dividerEnd
: isEndPanel
? styles.dividerStart
: null;
// Select collapse style based on position (collapse the side where divider would be)
const collapseStyle = isStartPanel
? styles.collapseEnd
: isEndPanel
? styles.collapseStart
: null;
return (
<div
ref={mergedRef}
role={region.role}
aria-label={region['aria-label']}
{...mergeProps(
themeProps('layout-panel'),
stylex.props(
styles.panel,
dynamicStyles.sizing(effectiveWidth ?? null),
// Outer padding on container edges (unless component is full bleed)
isStartPanel &&
!isZeroPadding &&
padding == null &&
styles.startPanel,
isEndPanel && !isZeroPadding && padding == null && styles.endPanel,
!hasHeader && !isZeroPadding && padding == null && styles.noHeader,
!hasFooter && !isZeroPadding && padding == null && styles.noFooter,
isScrollable && styles.scrollable,
isZeroPadding && styles.fullBleed,
padding != null && paddingStyles[padding],
padding != null && containerPaddingInlineVarStyles[padding],
padding != null && containerPaddingBlockStartVarStyles[padding],
padding != null && containerPaddingBlockEndVarStyles[padding],
hasDivider && dividerStyle,
shouldCollapseSpacing && collapseStyle,
isZeroWidth && styles.zeroWidth,
xstyle,
),
className,
style,
)}
{...props}
{...(isConcealed ? {inert: true, 'aria-hidden': true} : {})}>
<LayoutChangeSnapshot
value={isZeroWidth}
onBeforeChange={tellBeforeChange}
/>
<LayoutChangeSnapshot
value={isRegionCollapsed}
onBeforeChange={noteFocusBeforeCollapse}
/>
{children}
</div>
);
}
LayoutPanel.displayName = 'LayoutPanel';