Sidebar

Sidebar renders persistent navigation on desktop and reuses modal Drawer behavior on small screens. Content stays consumer-owned while Akaza UI manages responsive state, collapse geometry, resizing, focus, dismissal, and accessibility.

Anatomy

• #header: Fixed region for branding, workspace controls, or an internal collapse action.
• #default: Scrollable navigation or application content.
• #footer: Fixed region for account controls or secondary actions.
• #resize-handle: Optional content inside the generated accessible resize separator.

Every slot receives responsive state, size, and safe action functions. Toggle controls outside the sidebar should use v-model or useSidebar; Akaza does not require a separate trigger sub-component.

Usage

<script setup lang="ts">
import type { SidebarController } from "akaza-ui";
import { NavigationMenu, Sidebar, useSidebar } from "akaza-ui";
import { ref, useTemplateRef } from "vue";

const sidebarRef = useTemplateRef<SidebarController>("sidebar");
const selected = ref("dashboard");
const { collapsed, isMobile, open, toggle } = useSidebar(sidebarRef);
const items = [
  { label: "Dashboard", value: "dashboard" },
  { label: "Projects", value: "projects" },
];
</script>

<template>
  <button
    type="button"
    :aria-expanded="isMobile ? open : !collapsed"
    @click="toggle"
  >
    Navigation
  </button>

  <Sidebar
    ref="sidebar"
    collapsible="icon"
    aria-label="Workspace navigation"
  >
    <template #header="{ collapsed: isCollapsed }">
      <Logo />
      <span v-if="!isCollapsed">Workspace</span>
    </template>

    <template #default="{ collapsed: isCollapsed }">
      <NavigationMenu
        v-model="selected"
        orientation="vertical"
        :collapsed="isCollapsed"
        :tooltip="isCollapsed"
        :items="items"
        aria-label="Workspace"
      />
    </template>

    <template #footer>Account</template>
  </Sidebar>
</template>

Examples

Nested navigation

Compose Sidebar with a vertical NavigationMenu for groups, nested items, active state, badges, collapsed tooltips, and side flyouts. The sidebar owns responsive layout; the navigation menu owns navigation state.

<script setup lang="ts">
import { NavigationMenu, Sidebar } from "akaza-ui";
import { ref } from "vue";

const collapsed = ref(false);
const selected = ref("akaza-ui");
const expanded = ref(["projects"]);
const items = [
  { label: "Overview", value: "overview" },
  {
    label: "Projects",
    value: "projects",
    children: [
      { label: "Akaza UI", value: "akaza-ui" },
      { label: "Website", value: "website" },
    ],
  },
  { label: "Settings", value: "settings" },
];
</script>

<template>
  <Sidebar
    v-model:collapsed="collapsed"
    :mobile="false"
    collapsible="icon"
  >
    <template #header="{ toggleCollapsed }">
      <button type="button" @click="toggleCollapsed">Toggle</button>
    </template>

    <template #default="{ collapsed: isCollapsed }">
      <NavigationMenu
        v-model="selected"
        v-model:expanded="expanded"
        orientation="vertical"
        :collapsed="isCollapsed"
        :tooltip="isCollapsed"
        :items="items"
      />
    </template>
  </Sidebar>
</template>

Collapse modes

Use icon when compact controls remain usable. Use offcanvas when the complete desktop panel should leave the layout.

<Sidebar v-model:collapsed="collapsed" collapsible="icon" />
<Sidebar v-model:collapsed="hidden" collapsible="offcanvas" />
<Sidebar :collapsible="false" />

In icon mode, slot content remains mounted and interactive. Use the slot's collapsed value to hide labels or replace content. Off-canvas content becomes inert and aria-hidden when collapsed.

Mobile dialog

breakpoint controls when the persistent sidebar becomes a modal drawer. mobile can override media-query detection for container-based layouts or tests.

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>

<template>
  <button :aria-expanded="open" @click="open = true">Open navigation</button>

  <Sidebar
    v-model:open="open"
    breakpoint="(max-width: 64rem)"
    side="left"
    aria-label="Main navigation"
  >
    <nav>...</nav>
  </Sidebar>
</template>

Mobile mode traps focus, locks body scrolling, makes the outside tree inert, closes on Escape or backdrop interaction, restores focus, and supports directional swipe dismissal. Activating an unmodified same-window link closes the sidebar by default.

Resizing

Enable the generated separator with resizable. Size uses pixels and supports controlled or uncontrolled state.

<Sidebar
  v-model:size="size"
  resizable
  :default-size="256"
  :min-size="192"
  :max-size="480"
  :resize-step="8"
>
  <template #resize-handle>
    <span aria-hidden="true" />
  </template>
</Sidebar>

The resize handle supports pointer, pen, touch, and keyboard input. Double-click resets to defaultSize.

Right sidebar

Placement also changes pointer and keyboard resize direction.

<Sidebar side="right" collapsible="icon" resizable aria-label="Inspector">
  <template #header>Inspector</template>
  Properties
</Sidebar>

Keyboard shortcut

Global shortcuts are opt-in to avoid application conflicts. keyboardShortcut="b" uses Command+B on macOS and Ctrl+B elsewhere.

<Sidebar keyboard-shortcut="b" collapsible="icon" />

Shortcuts are ignored while focus is inside an input, textarea, select, or editable element.

Custom behavior with useSidebar

Pass a component ref when controls live outside a sidebar. Each composable instance controls only the referenced sidebar, so an application can manage multiple sidebars independently.

<script setup lang="ts">
import type { SidebarController } from "akaza-ui";
import { Sidebar, useSidebar } from "akaza-ui";
import { useTemplateRef } from "vue";

const sidebarRef = useTemplateRef<SidebarController>("sidebar");
const sidebar = useSidebar(sidebarRef);
</script>

<template>
  <button type="button" @click="sidebar.toggle">Toggle navigation</button>
  <Sidebar ref="sidebar" collapsible="icon">...</Sidebar>
</template>

For state owned outside the component, useSidebar({ open, collapsed, breakpoint }) remains available. Persistence and route watching remain application concerns.

useSidebar

The composable has component-ref and controlled-state modes. See useSidebar for both signatures, options, returned state, event-safe actions, multiple-sidebar examples, and SSR behavior.

API Reference

Models

Props

Slots

SidebarSlotProps exposes open, collapsed, isMobile, state, size, openMobile, closeMobile, toggleMobile, expand, collapse, toggleCollapsed, toggle, and resetSize. On mobile, collapsed is always false.

Emits

Exposed methods

Exposed values

Prefer useSidebar(sidebarRef) when consuming these values outside the component.

UI Options

Styling Hooks

Width and motion can also be configured through --akaza-sidebar-size, --akaza-sidebar-collapsed-size, --akaza-sidebar-mobile-size, --akaza-sidebar-transition-duration, and --akaza-sidebar-transition-easing.

Plain class applies to the single root. Use ui for the panel, regions, resize handle, and teleported mobile parts.

Keyboard

Pointer, pen, and touch input can resize the desktop separator. Mobile mode supports backdrop and swipe dismissal. Desktop mode remains non-modal and never traps focus.