Layout

Overview

The layout component structure for admin dashboards or complex applications. It manages sidebar, header, footer, tabs, and main content areas.

Features

• One unified layout — SLayout combines the modern sidebar shell with admin-classic capabilities: scrollable wrapper, fixed header/footer, and orientation support.
• Three variants — sidebar (bordered), floating (rounded shadow), and inset (content with margin and rounded corners).
• Collapsible sidebar — collapsible="icon" collapses the sidebar to a rail width; collapsible="offcanvas" slides it off-canvas while preserving layout space.
• Side control — side="left" or side="right" flips the sidebar position with full RTL-aware logical properties.
• Mobile drawer — unset isMobile follows the viewport and swaps the desktop sidebar for a Dialog-based drawer with overlay and focus trap; pass a boolean to override the breakpoint.
• Slot-level overrides — every region (sidebar, header, tab, content, footer) accepts per-slot *Props for granular attribute forwarding.
• CSS-variable driven — dimensions (sidebarWidth, headerHeight, tabHeight, footerHeight) emit rem-based CSS variables for runtime customization.
• Size scaling — size (xs…2xl) scales the layout spacing and base typography through themeSizeRatio.
• fullContent mode — pins the content area to fill the viewport while keeping the tab bar above it.
• Orientation — Layout supports horizontal (sidebar beside content) and vertical (sidebar stacked under header) orientations.
• Scroll behaviors — scrollBehavior="content" scrolls only the content region; scrollBehavior="wrapper" scrolls the entire main wrapper.
• Fixed header/footer — fixedTop and fixedFooter keep the header/footer pinned during content scroll, with automatic placeholder elements to prevent overlap.
• Base z-index control — baseZIndex derives the stacking order of sidebar, header, tab, and footer so multiple layouts compose predictably.
• Aria composition — every region (LayoutRoot, LayoutSidebar, LayoutRail, LayoutHeader, LayoutTab, LayoutContent, LayoutFooter, LayoutMobile, LayoutTrigger) is exported from @vean/aria/layout for custom styled builds.
• SSR safe — no window/document access in setup; the viewport fallback is guarded, and useId() generates stable scroll ids for server rendering.

Usage

Demos

API

Notes

Architecture and benchmark comparison

Runtime considerations

1. CSS variables are rem-based — sidebarWidth, collapsedSidebarWidth, headerHeight, tabHeight, footerHeight, and mobileSidebarWidth are converted via pxToRem (default px / 16). Pass a custom pxToRem to align with a non-default root font size.
2. size scales spacing and typography — the UI wrapper multiplies pixel dimensions by themeSizeRatio[size] / themeSizeMap.md, so size="xs" shrinks both text and sidebar width proportionally.
3. isMobile resolves through three levels — the prop, then a viewport a host publishes with provideViewportContext (a documentation device frame, an embedded shell), then useMediaQuery(mobileViewportQuery), the breakpoint shared with the styled sidebar’s lt-md hiding rule (767.9px). The winning source is published as data-mobile-source="explicit|viewport", and the styled lt-md fallback only applies to viewport: an explicit isMobile="false" below the breakpoint keeps the inline sidebar and its reserved width, instead of reserving space for a sidebar the CSS had hidden. The drawer is teleported out of the layout, so on mobile the sidebar reserves no space: the start gaps (--vean-layout-start-gap, --vean-layout-header-start-gap, --vean-layout-footer-start-gap) collapse to 0, and each variant falls back to its own end gap — sidebar/floating become full-bleed, inset stays inset symmetrically on both edges. The same fallback covers sidebarVisible="false" on desktop: a hidden sidebar reserves no space either, so the extra spacing floating/inset add beside the sidebar width is withdrawn with it, and the main column stays aligned with the fixed header and footer. A host that resolves the sidebar to no column at all — SAppShell’s split modes do, while a first-level leaf is active — declares sidebarWidth="0" instead: the root then reports data-sidebar-flow="false", the styled layer withdraws the same spacing and paints no column, and because the region itself stays mounted (its mount targets host teleported panes), only the column disappears, not the subtree.
4. The sidebar slot renders from a mode-aware collapsed — the slot hands its content collapsed next to open: it is false on mobile, where the sidebar is a drawer that always shows the expanded navigation, so a collapse picked on desktop does not follow the content into the drawer. Render from collapsed (a menu’s collapsed, a brand title’s visibility); open keeps reporting the desktop state, and the collapse returns the moment the mode does.
5. LayoutTrigger vs LayoutRail — LayoutTrigger is a focusable button in the header for keyboard users; LayoutRail is the edge drag affordance with tabindex="-1" (click-only). Both reflect aria-expanded for whichever sidebar the current mode renders — on mobile that is the drawer, not the desktop open state.
6. Layout placeholder elements — when fixedTop or fixedFooter is enabled, LayoutPlaceholder renders empty spacer divs (data-vean-layout-{header|tab|footer}-placeholder) to prevent content from sliding under the fixed region. Hiding a region removes its placeholder with it, and the fixed regions below close the gap: with the header hidden the tab takes the layout’s top edge instead of keeping the header’s height (inset keeps only its own half-spacing).
7. scrollId for scroll restoration — Layout generates a stable soybean-layout-scroll-{id} on the scrolling element (wrapper or content depending on scrollBehavior). Pass scrollId to make it deterministic across SSR/CSR.

FAQ

Which layout mode should I use?

Use SLayout for both modern application shells and admin dashboards. It handles fixed header/footer, orientation switching (horizontal / vertical), and wrapper-level scrolling with placeholder spacers through a single unified component.

How do I control the sidebar open state?

Use v-model:open (controlled) or default-open (uncontrolled). The state is reflected on the root via data-state="expanded|collapsed" and on LayoutTrigger/LayoutRail via aria-expanded.

On mobile the inline sidebar is replaced by a drawer, which carries its own state: bind v-model:mobileOpen (or default-mobile-open uncontrolled) to drive it. open keeps controlling the desktop sidebar, so a host that pins isMobile reaches what the user sees through mobileOpen — and the trigger reports that state. A single open binding cannot mean both, because the desktop sidebar defaults to expanded while the drawer has to start closed.

How do I make the sidebar collapse to icons instead of sliding away?

Set collapsible="icon" (default) and collapsedSidebarWidth to the rail width. The sidebar shrinks to the collapsed width and the sidebarGapHandler adjusts the main area accordingly. Use collapsible="offcanvas" to slide the sidebar off-canvas instead.

How does mobile mode work?

Leave isMobile unset (the default) and the layout follows the viewport, swapping the desktop sidebar for a Dialog-based drawer; pass a boolean to pin the mode yourself. The drawer inherits mobileSidebarWidth and reuses the same sidebar slot content. The drawer overlay and focus trap are provided by the underlying Dialog component.

Can a host decide the mode for a whole subtree?

Yes. A host that already knows the answer — a device preview frame rendering a phone, a shell embedded in a desktop app, an SSR pass with a device hint — publishes it once with provideViewportContext({ isMobile }) from @vean/aria/composables; every layout below it follows, and an explicit isMobile prop still wins per instance. Publishing at the frame rather than per component is also what keeps a documentation preview honest: the frame can simulate a phone viewport while the browser window stays wide. Note that viewport-prefixed utilities (lt-md:hidden, sm:, md:) still key off the browser window, so a simulated viewport moves the JS structure (drawer vs. inline sidebar) and the prop-driven spacing, not those breakpoint classes.

Can I render the sidebar on the right?

Yes — set side="right". The layout uses RTL-aware logical properties (start-*, end-*, border-s, border-e) so the sidebar, gap handler, rail cursor, and fixed header/footer insets all flip correctly.

How are z-index values coordinated?

Layout accepts a baseZIndex (default 50). The sidebar, header, tab, and footer z-index values are derived from this base so they stack predictably. The derived values are exposed as --layout-{sidebar|header|tab|footer}-z-index CSS variables.

How do I customize region-level attributes?

Each region accepts a *Props prop on the compact component (e.g. sidebarProps, headerProps, tabProps, contentProps, footerProps, mainProps, railProps, mobileProps). These are forwarded to the corresponding Aria region component.