Skip to main content

PageLayout

Use the PageLayout to structure app pages with persistent header, sidebar, content, and details panel slots, including responsive breakpoint handling and resizable panels.

OverviewPropertiesUsageMigration guide

When to use​

  • To structure app pages with a persistent header, sidebar, main content area, and details panel.
  • When your page needs responsive layout handling, resizable panels, or a details drawer.

When not to use​

  • For simple single-view pages that don't need navigation panels or a details panel.

The sidebar is for page-level concerns: navigation structures, entity lists, or filter panels that exist independently of any specific selection in the content area. If its content only makes sense in the context of something selected in PageLayout.Content, use the details panel instead.

  • Collapse controls are built in and appear on hover.
  • Keep actions in the sidebar (search fields, add buttons) scoped to the sidebar's own content, not to the content area.

Content​

PageLayout.Content is the central focus of the page.

Details​

The details panel is for content directly tied to a selection or entity shown in PageLayout.Content. If the panel would be useful without anything selected in the content area, it belongs in the sidebar instead.

  • Don't use the details panel for settings or features unrelated to a selection in the content area.
  • Prefer an 'overlay' layout when the content area must remain full-width, such as a canvas, preview, or grid that doesn't reflow nicely at narrower widths.
  • Prefer a 'split' layout when the content naturally adapts to a narrower container, such as a form, list, or text editor.

Collapse handling​

A details panel's open/closed state is a consumer intent, not a responsive concern: it stays where you put it across viewports and is never auto-collapsed by the breakpoint. Below the breakpoint an open panel becomes an open drawer.

  • To open the panel programmatically, derive a controlled collapsed from your selection state: open on select, close on deselect.
  • To keep it closed on small screens, set defaultCollapsed or control collapsed and update it from onBreakpointTransition.

Accessibility concerns​

The 'overlay' layout mode has accessibility constraints. The content area is fully interactive and all elements within it are focusable. This means the details overlay can obstruct a focused element below it. Be aware of the accessibility implications and build your UI accordingly.

Control bar​

PageLayout.Details.ControlBar renders a close button and, above the responsive breakpoint, a toggle between 'split' and 'overlay' layout. Place it at the top of the details panel content to give users a discoverable way to close or reposition the panel.

Compose it in a Flex to add a title, subtitle, and other elements for your details header.

  • Pass custom actions as children to extend the bar with panel-specific buttons. They appear before the default controls, separated by a divider.
  • The layout-toggle button is hidden in drawer mode.

Split vs. overlay​

  • 'split' (default): the details panel displaces the content area. Both share the available width. Use this when the content reflows cleanly at narrower widths.
  • 'overlay': the details panel floats over the content without altering its width. Use this to maximize the content area while the details panel is open.

Control the active mode with layout and onLayoutChange, or set an initial value with defaultLayout.

Responsive behavior​

Below its breakpoint a panel renders as a Drawer. An uncontrolled sidebar auto-collapses there; a details panel keeps its open/closed state. See Responsive behavior for the full contract and Layout hierarchy for how each panel's breakpoint is measured.

Resizing​

Panels are resizable by default within their configured minWidth and maxWidth constraints. Set resizable to false to lock a panel to its configured width and hide the drag handle. Use this when the panel width is fixed by its content rather than user preference.

Content state​

Panel content is never unmounted. Component state, scroll positions, and form input values persist across collapse and expand cycles automatically.

To reset state when a panel closes, do so explicitly in onCollapsedChange. To re-initialize state on open, conditionally render the slot's children based on the collapsed state.

Still have questions?
Find answers in the Dynatrace Community