nuxt-x-app

Layout

Full-application shell with responsive sidebar, header, breadcrumbs, and navigation components.

Layout

The Layout category provides the full application shell and every navigation primitive needed to build a consistent admin or SaaS interface. XALayout orchestrates the responsive sidebar, header, and content area; the individual sub-components can also be used independently. All components integrate with the optional useXNavigation composable for config-driven nav without prop drilling.

Components

`<XALayout />`

Top-level shell that renders a fixed desktop sidebar, an animated mobile slide-in sidebar with backdrop, and a full-height main content area. Sidebar width animates between expanded and collapsed states. Integrates with useXNavigation automatically.

<XALayout color="primary" sidebar-width="16rem">
  <template #logo="{ collapsed }">
    <img v-if="!collapsed" src="/logo.svg" />
  </template>
  <template #nav="{ collapsed }">
    <XALayoutSidebarNav :items="navItems" :collapsed="collapsed" />
  </template>
  <NuxtPage />
</XALayout>

Props

Prop	Type	Default	Description
`sidebarCollapsed`	`Boolean`	`undefined`	Controlled collapsed state of the sidebar
`sidebarWidth`	`String`	`'16rem'`	Width of the expanded sidebar
`collapsedWidth`	`String`	`'4rem'`	Width of the collapsed sidebar
`color`	`String`	`'primary'`	Active color for navigation items
`backgroundColor`	`String`	`''`	Background color class for the page
`sidebarBackgroundColor`	`String`	`''`	Background color class for the sidebar
`sidebarTextMode`	`String`	`''`	Text color mode for sidebar: `'light'` or `'dark'`

Slots

Slot	Props	Description
`logo`	`{ collapsed }`	Brand logo area
`nav`	`{ collapsed, textMode }`	Sidebar navigation content
`sidebar-footer`	`{ collapsed }`	Sidebar footer area
`sidebar-user`	`{ collapsed, textMode }`	Sidebar user menu area
`breadcrumbs`	—	Header breadcrumb override
`header-actions`	—	Additional header action buttons
`user`	—	Header user menu override
`secondary-nav`	—	Below-header secondary navigation
default	—	Main page content

`<XALayoutHeader />`

Sticky top header bar. The left side shows a mobile menu toggle and breadcrumbs (or top nav items). The right side renders search, action buttons with optional badges, and a user menu.

<XALayoutHeader
  :show-breadcrumbs="true"
  :search="{ enabled: true, placeholder: 'Search...', shortcut: '⌘K' }"
  :actions="[{ icon: 'i-lucide-bell', label: 'Notifications', badge: 3 }]"
/>

Props

Prop	Type	Default	Description
`showMobileMenu`	`Boolean`	`true`	Show the hamburger menu button
`showBreadcrumbs`	`Boolean`	`true`	Show the breadcrumbs component
`showUserMenu`	`Boolean`	`true`	Show the default user menu
`search`	`Object`	`{ enabled: false }`	Search config: `{ enabled, placeholder, shortcut }`
`actions`	`Array`	`[]`	Header action buttons: `[{ icon, label, to, action, badge }]`
`topNavItems`	`Array`	`undefined`	Navigation items to render in the header
`useNavigation`	`Boolean`	`true`	Merge config from `useXNavigation` composable

`<XALayoutSidebar />`

The desktop sidebar panel. Supports collapsed/expanded states, collapsible toggle, custom brand, navigation items, footer items, and a user menu slot. Adapts border and text colors via textMode.

<XALayoutSidebar
  v-model:collapsed="collapsed"
  :items="navItems"
  :color="'primary'"
  text-mode="light"
  collapsible
/>

Props

Prop	Type	Default	Description
`collapsed`	`Boolean`	`undefined`	Controlled collapsed state
`collapsible`	`Boolean`	`undefined`	Show the collapse toggle button
`width`	`String`	`undefined`	Sidebar width
`collapsedWidth`	`String`	`'64px'`	Width when collapsed
`items`	`Array`	`undefined`	Navigation items array
`footerItems`	`Array`	`undefined`	Footer navigation items
`brand`	`Object`	`undefined`	Brand config: `{ title, logo, to }`
`user`	`Object`	`undefined`	User config passed to `XALayoutSidebarUserMenu`
`position`	`String`	—	Sidebar position (e.g., `'right'`)
`color`	`String`	`'primary'`	Active item color
`textMode`	`String`	`'dark'`	Text color mode: `'light'` or `'dark'`
`mobile`	`Boolean`	`false`	Renders in mobile mode (shows close button)
`useNavigation`	`Boolean`	`true`	Merge config from `useXNavigation` composable

`<XALayoutSidebarNav />`

Renders an array of navigation item objects. Items may include section headers (item.section), dividers (item.divider), or regular nav entries delegated to XALayoutSidebarNavItem.

<XALayoutSidebarNav
  :items="[
    { section: 'Main' },
    { label: 'Dashboard', icon: 'i-lucide-home', to: '/' },
    { divider: true },
    { label: 'Settings', icon: 'i-lucide-settings', to: '/settings' }
  ]"
  :collapsed="false"
  color="primary"
  text-mode="dark"
/>

Props

Prop	Type	Default	Description
`items`	`Array`	`[]`	Navigation items array
`collapsed`	`Boolean`	`false`	Collapsed display mode
`color`	`String`	`'primary'`	Active item color
`textMode`	`String`	`'dark'`	Text color mode: `'light'` or `'dark'`

`<XALayoutSidebarNavItem />`

Single navigation item. Supports NuxtLink routing, action callbacks, badges, nested children (collapsible in expanded mode, dropdown in collapsed mode), and tooltip labels when collapsed.

<XALayoutSidebarNavItem
  :item="{
    label: 'Reports',
    icon: 'i-lucide-chart-bar',
    to: '/reports',
    badge: { label: 'New', color: 'success' },
    children: [
      { label: 'Monthly', to: '/reports/monthly' }
    ]
  }"
  :collapsed="false"
  color="primary"
  text-mode="dark"
/>

Props

Prop	Type	Default	Description
`item`	`Object`	required	Nav item: `{ label, icon, to, action, badge, children, disabled }`
`collapsed`	`Boolean`	`false`	Collapsed display mode
`color`	`String`	`'primary'`	Active item color
`textMode`	`String`	`'dark'`	Text color mode: `'light'` or `'dark'`
`nested`	`Boolean`	`false`	Renders as a child item with reduced padding

`<XALayoutSidebarUserMenu />`

Avatar-based dropdown at the bottom of the sidebar. Shows user name and email when expanded; shows avatar only when collapsed. Includes a built-in theme switcher (light/dark/system) and emits logout and navigate events.

<XALayoutSidebarUserMenu
  :user="{ name: 'Jane Doe', email: 'jane@example.com', avatar: '/avatar.png' }"
  :collapsed="false"
  text-mode="dark"
  show-online-status
/>

Props

Prop	Type	Default	Description
`user`	`Object`	`{}`	User object: `{ name, email, avatar }`
`collapsed`	`Boolean`	`false`	Collapsed display mode
`showOnlineStatus`	`Boolean`	`false`	Show green online indicator dot
`textMode`	`String`	`'dark'`	Text color mode: `'light'` or `'dark'`
`items`	`Array`	`undefined`	Custom dropdown menu items

`<XALayoutUserMenu />`

Header-level user dropdown. Renders an avatar button (or icon + name fallback) that opens a dropdown with an info header, theme switcher, settings link, and logout link.

<XALayoutUserMenu
  name="Jane Doe"
  email="jane@example.com"
  avatar="/avatar.png"
  settings-path="/account"
  logout-path="/auth/logout"
/>

Props

Prop	Type	Default	Description
`name`	`String`	`''`	Display name
`email`	`String`	`''`	Email address
`avatar`	`String`	`''`	Avatar image URL
`showAvatar`	`Boolean`	`true`	Show avatar vs. icon+name fallback
`showThemeSwitcher`	`Boolean`	`true`	Include theme toggle in dropdown
`settingsPath`	`String`	`'/settings'`	Route for settings menu item
`logoutPath`	`String`	`'/auth/logout'`	Route for logout menu item
`items`	`Array`	`[]`	Additional dropdown menu items
`useNavigation`	`Boolean`	`true`	Merge config from `useXNavigation` composable

`<XALayoutMobileSidebar />`

Mobile slide-over sidebar driven by USlideover. Renders brand header, nav items, and optional footer items. Closes automatically on navigation when closeOnNavigate is true.

<XALayoutMobileSidebar
  v-model:open="mobileOpen"
  :items="navItems"
  color="primary"
  close-on-navigate
/>

Props

Prop	Type	Default	Description
`open`	`Boolean`	`false`	Controls slide-over visibility
`items`	`Array`	`undefined`	Navigation items
`footerItems`	`Array`	`undefined`	Footer navigation items
`brand`	`Object`	`undefined`	Brand config: `{ title, logo, to }`
`closeOnNavigate`	`Boolean`	`true`	Close on route change
`useNavigation`	`Boolean`	`true`	Merge config from `useXNavigation` composable
`color`	`String`	`'primary'`	Active item color
`textMode`	`String`	`'dark'`	Text color mode: `'light'` or `'dark'`

`<XALayoutPageHeader />`

Standardized page header block. Shows optional breadcrumbs row, a title with optional back button, description (or slot), actions slot, and a tab bar that highlights the active route.

<XALayoutPageHeader
  title="Users"
  description="Manage your team members"
  :back="{ to: '/admin', label: 'Admin' }"
  :tabs="[
    { label: 'All', to: '/users' },
    { label: 'Admins', to: '/users/admins', badge: 2 }
  ]"
  sticky
>
  <template #actions>
    <UButton icon="i-lucide-plus">Invite</UButton>
  </template>
</XALayoutPageHeader>

Props

Prop	Type	Default	Description
`title`	`String`	required	Page title
`description`	`String`	`undefined`	Subtitle text
`back`	`Object`	`undefined`	Back button: `{ to, label? }`
`breadcrumbs`	`Array`	`undefined`	Breadcrumb items: `[{ label, to? }]`
`tabs`	`Array`	`undefined`	Tab items: `[{ label, to, badge? }]`
`sticky`	`Boolean`	`false`	Stick header to top on scroll
`loading`	`Boolean`	`false`	Show skeleton placeholders

`<XALayoutBreadcrumbs />`

Accessible breadcrumb trail. When auto is true and no items are provided, it auto-generates crumbs from the current route path.

<!-- Auto-generated from route -->
<XALayoutBreadcrumbs />

<!-- Manual items -->
<XALayoutBreadcrumbs :items="[{ label: 'Home', to: '/' }, { label: 'Settings' }]" />

Props

Prop	Type	Default	Description
`items`	`Array`	`[]`	Manual breadcrumb items: `[{ label, to? }]`
`auto`	`Boolean`	`true`	Auto-generate from route path when items is empty

`<XALayoutContentNav />`

Settings-style secondary sidebar. On desktop it renders a sticky sidebar nav panel; on mobile it collapses to a USelect dropdown.

<XALayoutContentNav
  label="Account"
  :items="[
    { label: 'Profile', to: '/settings/profile', icon: 'i-lucide-user' },
    { label: 'Security', to: '/settings/security', icon: 'i-lucide-shield' }
  ]"
/>

Props

Prop	Type	Default	Description
`items`	`Array`	`[]`	Navigation items: `[{ label, to, icon? }]`
`label`	`String`	`''`	Section label shown above the list

`<XALayoutSecondaryNav />`

Horizontal sub-navigation bar rendered below the header. Supports links and action callbacks, an optional back button, and a right-side #actions slot.

<XALayoutSecondaryNav
  :items="[
    { label: 'Overview', to: '/project' },
    { label: 'Tasks', to: '/project/tasks', badge: 12 }
  ]"
  show-back
  @back="$router.back()"
/>

Props

Prop	Type	Default	Description
`items`	`Array`	`[]`	Nav items: `[{ label, to?, icon?, badge?, action? }]`
`label`	`String`	`''`	Accessible label (not displayed)
`showBack`	`Boolean`	`false`	Show back arrow button

`<XALayoutResponsiveNav />`

Renders a UNavigationMenu (horizontal) on md+ screens and a UDropdownMenu on smaller screens. The dropdown button label automatically reflects the active route item.

<XALayoutResponsiveNav
  :items="[
    { label: 'Dashboard', to: '/', icon: 'i-lucide-home' },
    { label: 'Reports', to: '/reports', icon: 'i-lucide-chart-bar' }
  ]"
/>

Props

Prop	Type	Default	Description
`items`	`Array`	required	Navigation items: `[{ label, to?, icon?, click? }]`

AI Context

category: Layout
package: "@xenterprises/nuxt-x-app"
use-when: >
  Building an admin panel, dashboard, or SaaS application that needs a
  full-page shell with a collapsible sidebar. Use XALayout as the root
  shell, XALayoutPageHeader on individual pages, XALayoutBreadcrumbs or
  XALayoutSecondaryNav for in-page orientation, and XALayoutContentNav
  for settings-style sub-pages. All components integrate with the
  useXNavigation composable for config-driven setup.

Edit this pageorReport an issue

Kanban

Drag-and-drop Kanban board with configurable columns, card metadata, mobile column switching, and useXCrud integration.

Modal

Flexible modal dialogs including a general-purpose modal, a confirmation dialog, and a key-value data viewer.