Skip to content

Sidebar

Build grouped application navigation with desktop and mobile layouts.

Demos

Mode
Design
Size
Variant

Usage

The soft design is the sidebar used in these docs. Pass an items array; Sidebar composes Akaza's responsive panel and vertical navigation. Use labels to group links, and add children for expandable navigation. Rows use the docs' active fill and sliding hover effect.

vue
<script setup lang="ts">
import { ref } from 'vue'
import { Sidebar, type SidebarItem } from '~/components/ui/sidebar'

const current = ref('/projects')
const items: SidebarItem[] = [
  { type: 'label', label: 'Workspace' },
  { label: 'Projects', href: '/projects' },
  { label: 'Activity', href: '/activity' },
  { type: 'label', label: 'Settings' },
  { label: 'Profile', href: '/settings/profile' },
]
</script>

<template>
  <Sidebar v-model="current" :items="items" variant="soft" aria-label="Workspace">
    <template #header>Workspace</template>
    <template #footer>Igris Labs</template>
  </Sidebar>
</template>

Use to for router destinations and href for anchors. Set as to your link component when needed, for example NuxtLink. type: 'label' creates a category heading, type: 'separator' adds a divider, and children creates expandable navigation. Labels and separators cannot be selected. Pass Vue components as icons, or use #item-leading to render icon names from your own data.

At the default sm size, rows are 30px tall on 34px spacing with 8px corners, a neutral active fill, and the shared sliding hover effect. The navigation header appears in the mobile panel. #header and #footer receive the sidebar controller actions, including closeMobile. Providing the default slot replaces generated navigation with your own body.

Set navigation-label when the navigation landmark needs a different name from the sidebar. Override navigation styles through ui.navigation; component defaults still come from ui.config.ts.

Designs

Use design="standard" for the existing row highlight or design="line" for a vertical selection marker. The line design keeps rows unfilled and moves a 1.5px marker beside the current item. Markers sit 6px inside each row end. Hover changes text emphasis without moving the selection marker; collapsed group labels never receive a marker. Nested links keep the same indentation and sizing.

vue
import tailwindcss from '@tailwindcss/vite'

export default defineNuxtConfig({
  modules: ['akaza-ui/nuxt', '@nuxt/fonts', '@nuxtjs/color-mode'],
  css: ['~/assets/main.css'],
  colorMode: { classSuffix: '', preference: 'system', fallback: 'light' },
  vite: { plugins: [tailwindcss()] },
})

Switch designs without changing items, models, slots, or the mobile controller. Set components.sidebar.design in ui.config.ts to change the default.

design="rail" adds a faint track through each group’s children, like the table of contents. Tracks stop at category labels and group gaps. A lighter marker follows hover or keyboard focus while the active marker stays on the selected item. Collapsible group labels use a light hover fill instead of a rail.

Grouping modes

The default mode="ungrouped" renders category labels above their items. Use mode="grouped" to turn each root category label and its following items into a collapsible group. Pass the same items array for either mode. Existing nested children stay inside their category.

Groups start expanded. Set defaultExpanded: false on a label to start its group closed, and give labels stable, unique value fields, especially when their text repeats. Groups retain their open state when you switch modes. Links before the first category stay at the root.

vue
<Sidebar design="rail" mode="grouped" variant="soft" :items="items" v-model="current" />
PropTypeDefaultDescription
itemSizexs, sm, md, lg, xlsmRow size; also scales text, padding, icons, and corners.
itemsSidebarItem[]—Labels, links, separators, and nested children.
navigationLabelstringariaLabel or NavigationAccessible name for generated navigation.

Navigation forwards the cancelable select(item, details) and value-change(value, details) events. Canceling selection preserves the current item. For router-driven sidebars, pass the current route as model-value.

Exposed values

ValueTypeDescription
openValuebooleanCurrent mobile visibility.
collapsedValuebooleanCurrent desktop collapse value.
sizeValuenumberCurrent expanded width in pixels.
isMobilebooleanCurrent responsive mode.
stateSidebarStateCurrent open, closed, expanded, or collapsed state.

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

Installation

Complete the shared installation. Copy Sidebar.vue and index.ts into app/components/ui/sidebar/. Also copy the required components: Navigation Menu.

API

Variants and defaults

PropValuesDefault
modeungrouped, groupedungrouped
designstandard, line, railstandard
variantdefault, muted, soft, subtledefault

In the standard design, soft uses a neutral active fill and subtle adds a light inset border. The line and rail designs use their selection markers without either row treatment. These docs use standard with soft.

Use item-size to scale navigation rows. Set components.sidebar.itemSize in ui.config.ts for a component default; it falls back to defaults.size. Akaza's numeric v-model:size controls sidebar width.

Item sizeRow heightRow spacingTextIconRadiusHorizontal padding
xs26px30px12px12px5px8px
sm30px34px13px14px8px10px
md34px38px14px16px10px12px
lg38px42px14px18px12px14px
xl42px46px16px20px14px16px

Group headings use 8/12/16/20/24px top gaps for xs/sm/md/lg/xl. Child rows keep indentation without guide lines.

Models

ModelTypeDefaultDescription
v-modelstring | null—Selected navigation item value; falls back to its destination or label.
v-model:openbooleandefaultOpenMobile dialog visibility.
v-model:collapsedbooleandefaultCollapsedDesktop collapse state. Ignored when collapsible is false.
v-model:sizenumberdefaultSizeExpanded desktop width in pixels.

Props

PropTypeDefaultDescription
asComponent | string"aside"Desktop panel element.
side"left" | "right""left"Sidebar edge.
collapsiblefalse | "icon" | "offcanvas"falseDesktop collapse behavior.
defaultOpenbooleanfalseInitial uncontrolled mobile visibility.
defaultCollapsedbooleanfalseInitial uncontrolled desktop collapse state.
defaultSizenumber256Initial expanded width in pixels.
minSizenumber192Minimum resized width.
maxSizenumber480Maximum resized width.
collapsedSizenumber48Width in icon collapse mode.
mobileSizenumber288Mobile drawer width.
resizeStepnumber8Keyboard resize amount in pixels. Shift multiplies it by ten.
resizablebooleanfalseRender the accessible resize separator.
transitionbooleantrueEnable desktop width and off-canvas transitions.
mobilebooleanmedia queryForce mobile or desktop rendering.
breakpointstring"(max-width: 767px)"Media query used when mobile is omitted.
closeOnBackdropClickbooleantrueClose the mobile dialog on backdrop interaction.
closeOnNavigatebooleantrueClose mobile mode after activating a same-window link.
swipeToClosebooleantrueEnable directional mobile swipe dismissal.
teleportstring | false"body"Mobile drawer Teleport target.
keyboardShortcutstring | falsefalseCommand/Ctrl shortcut key for responsive toggle.
ariaLabelstring"Sidebar"Desktop landmark and mobile dialog accessible name.
resizeAriaLabelstring"Resize sidebar"Resize separator accessible name.
uiSidebarUi—Classes for named structural parts.

Slots

SlotScoped propsDescription
headerSidebarSlotPropsFixed header region.
defaultSidebarSlotPropsScrollable body region.
footerSidebarSlotPropsFixed footer region.
resize-handleSidebarSlotPropsContent inside the generated separator handle.

For generated navigation, use #item-leading, #item-label, or #item-trailing to customize rows. Each receives Akaza's NavigationMenuSlotProps, including item, isActive, isOpen, depth, collapsed, and toggle.

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

Events

EventPayloadDescription
open-change[open, details]Cancelable mobile visibility change.
collapsed-change[collapsed, details]Cancelable desktop collapse change.
size-change[size, details]Cancelable pointer, keyboard, or reset size change. Details include previousSize.

Exposed methods

MethodDescription
open / openMobileOpen mobile visibility. open is a concise alias.
close / closeMobileClose mobile visibility. close is a concise alias.
toggleMobileToggle mobile visibility regardless of responsive state.
toggleToggle mobile visibility or desktop collapse based on responsive state.
expand / collapseChange desktop collapse state.
toggleCollapsedToggle desktop collapse state.
resetSizeRestore defaultSize.

Keyboard

KeyBehavior
Arrow Left / Arrow RightResize by resizeStep; direction follows sidebar placement.
Shift + Arrow Left / Shift + Arrow RightResize by ten times resizeStep.
Home / EndResize to minimum or maximum width.
EscapeClose mobile mode and restore focus.
Tab / Shift + TabRemain inside the open mobile dialog.
Command/Ctrl + configured keyToggle current responsive state when keyboardShortcut is enabled.

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.