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

useSidebar has two overloads. Pass a Sidebar component ref to control one rendered instance, or pass an options object when the application owns the state.

function useSidebar(target: SidebarTarget): UseSidebarTargetReturn;
function useSidebar(options?: UseSidebarOptions): UseSidebarReturn;

Component ref mode

Use this mode for external controls, multiple sidebars, or access to the rendered sidebar's responsive and size state.

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

const primaryRef = useTemplateRef<SidebarController>("primary");
const inspectorRef = useTemplateRef<SidebarController>("inspector");

const primary = useSidebar(primaryRef);
const inspector = useSidebar(inspectorRef);
</script>

<template>
  <button type="button" @click="primary.toggle()">Toggle navigation</button>
  <button type="button" @click="inspector.toggle()">Toggle inspector</button>

  <Sidebar ref="primary" collapsible="icon">...</Sidebar>
  <Sidebar ref="inspector" side="right" collapsible="offcanvas">...</Sidebar>
</template>

Each controller delegates only to its referenced instance. Calls made before that instance mounts are ignored.

Controlled state mode

Use this mode when state must exist before the component mounts or must be shared with storage, routing, or other application logic. Pass the same refs to Sidebar models.

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

const open = ref(false);
const collapsed = ref(false);
const { isMobile, state, toggle } = useSidebar({
  open,
  collapsed,
  breakpoint: "(max-width: 767px)",
});
</script>

<template>
  <button type="button" @click="toggle">Toggle sidebar</button>
  <output>{{ state }}</output>

  <Sidebar
    v-model:open="open"
    v-model:collapsed="collapsed"
    :mobile="isMobile"
    collapsible="icon"
  >
    ...
  </Sidebar>
</template>

This mode updates the supplied refs directly. The composable does not emit component events; the connected Sidebar models receive the resulting values.

Options

These options apply to controlled state mode.

Return value

When no mobile override is supplied, controlled mode uses matchMedia through VueUse. During SSR it starts in desktop mode and updates after hydration. Supply an SSR-safe mobile value when initial responsive markup must be deterministic.

Component ref mode delegates through Sidebar events. open-change, collapsed-change, and size-change listeners can still cancel changes.

Exported types

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.