Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Navigation

Sidebar

A responsive app sidebar with collapsible groups and a mobile drawer.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Overview

Workspace

Select a destination from the sidebar to continue.

Install

Run in your project
bunx --bun @getweini/cli@latest add sidebar

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Dashboard

Your dashboard content.

Projects

Your projects content.

Vue
<script setup lang="ts">
import { ref, useId } from 'vue'
import Sidebar from './components/ui/sidebar/Sidebar.vue'
import SidebarContent from './components/ui/sidebar/SidebarContent.vue'
import SidebarGroup from './components/ui/sidebar/SidebarGroup.vue'
import SidebarGroupLabel from './components/ui/sidebar/SidebarGroupLabel.vue'
import SidebarHeader from './components/ui/sidebar/SidebarHeader.vue'
import SidebarInset from './components/ui/sidebar/SidebarInset.vue'
import SidebarMenu from './components/ui/sidebar/SidebarMenu.vue'
import SidebarMenuButton from './components/ui/sidebar/SidebarMenuButton.vue'
import SidebarMenuItem from './components/ui/sidebar/SidebarMenuItem.vue'
import SidebarProvider from './components/ui/sidebar/SidebarProvider.vue'
import SidebarTrigger from './components/ui/sidebar/SidebarTrigger.vue'

const id = useId()
const current = ref('dashboard')
</script>

<template>
  <SidebarProvider>
    <Sidebar>
      <SidebarHeader>
        Atlas&nbsp;<SidebarTrigger aria-label="Toggle navigation">Menu</SidebarTrigger>
      </SidebarHeader>
      <SidebarContent aria-label="Workspace navigation">
        <SidebarGroup>
          <SidebarGroupLabel>Workspace</SidebarGroupLabel>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton
                :href="`#${id}-dashboard`"
                :active="current === 'dashboard'"
                @click="current = 'dashboard'"
              >
                Dashboard
              </SidebarMenuButton>
            </SidebarMenuItem>
            <SidebarMenuItem>
              <SidebarMenuButton
                :href="`#${id}-projects`"
                :active="current === 'projects'"
                @click="current = 'projects'"
              >
                Projects
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroup>
      </SidebarContent>
    </Sidebar>
    <SidebarInset>
      <div class="space-y-6">
        <section :id="`${id}-dashboard`">
          <h2>Dashboard</h2>
          <p>Your dashboard content.</p>
        </section>
        <section :id="`${id}-projects`">
          <h2>Projects</h2>
          <p>Your projects content.</p>
        </section>
      </div>
    </SidebarInset>
  </SidebarProvider>
</template>

A parent without href opens its child links when you click anywhere on the row. If the parent navigates, add SidebarMenuSubTrigger for a separate expand button. Mark the current child page to open its group automatically. Set the mobile breakpoint and save collapsed state in your application.

When to use it

Workspace shell

Keep project-level navigation beside the main page content.

Nested section

Expand a section to reveal related routes, with the active child visible.

More examples

Workspace navigation

The provider owns state for the sidebar and inset.

Workspace navigation
<script setup lang="ts">
import { ref, useId } from 'vue'
import Sidebar from './components/ui/sidebar/Sidebar.vue'
import SidebarContent from './components/ui/sidebar/SidebarContent.vue'
import SidebarGroup from './components/ui/sidebar/SidebarGroup.vue'
import SidebarGroupLabel from './components/ui/sidebar/SidebarGroupLabel.vue'
import SidebarHeader from './components/ui/sidebar/SidebarHeader.vue'
import SidebarInset from './components/ui/sidebar/SidebarInset.vue'
import SidebarMenu from './components/ui/sidebar/SidebarMenu.vue'
import SidebarMenuButton from './components/ui/sidebar/SidebarMenuButton.vue'
import SidebarMenuItem from './components/ui/sidebar/SidebarMenuItem.vue'
import SidebarProvider from './components/ui/sidebar/SidebarProvider.vue'
import SidebarTrigger from './components/ui/sidebar/SidebarTrigger.vue'

const id = useId()
const current = ref('dashboard')
</script>

<template>
  <SidebarProvider>
    <Sidebar>
      <SidebarHeader>
        Atlas&nbsp;<SidebarTrigger aria-label="Toggle navigation">Menu</SidebarTrigger>
      </SidebarHeader>
      <SidebarContent aria-label="Workspace navigation">
        <SidebarGroup>
          <SidebarGroupLabel>Workspace</SidebarGroupLabel>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton
                :href="`#${id}-dashboard`"
                :active="current === 'dashboard'"
                @click="current = 'dashboard'"
              >
                Dashboard
              </SidebarMenuButton>
            </SidebarMenuItem>
            <SidebarMenuItem>
              <SidebarMenuButton
                :href="`#${id}-projects`"
                :active="current === 'projects'"
                @click="current = 'projects'"
              >
                Projects
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroup>
      </SidebarContent>
    </Sidebar>
    <SidebarInset>
      <div class="space-y-6">
        <section :id="`${id}-dashboard`">
          <h2>Dashboard</h2>
          <p>Your dashboard content.</p>
        </section>
        <section :id="`${id}-projects`">
          <h2>Projects</h2>
          <p>Your projects content.</p>
        </section>
      </div>
    </SidebarInset>
  </SidebarProvider>
</template>

Expandable settings

A parent without href opens its child links from the whole row.

Expandable settings
<script setup lang="ts">
import { ref, useId } from 'vue'
import Sidebar from './components/ui/sidebar/Sidebar.vue'
import SidebarContent from './components/ui/sidebar/SidebarContent.vue'
import SidebarGroup from './components/ui/sidebar/SidebarGroup.vue'
import SidebarGroupLabel from './components/ui/sidebar/SidebarGroupLabel.vue'
import SidebarInset from './components/ui/sidebar/SidebarInset.vue'
import SidebarMenu from './components/ui/sidebar/SidebarMenu.vue'
import SidebarMenuButton from './components/ui/sidebar/SidebarMenuButton.vue'
import SidebarMenuItem from './components/ui/sidebar/SidebarMenuItem.vue'
import SidebarMenuSub from './components/ui/sidebar/SidebarMenuSub.vue'
import SidebarProvider from './components/ui/sidebar/SidebarProvider.vue'

const id = useId()
const current = ref('profile')
</script>

<template>
  <SidebarProvider>
    <Sidebar>
      <SidebarContent aria-label="Settings navigation">
        <SidebarGroup>
          <SidebarGroupLabel>Settings</SidebarGroupLabel>
          <SidebarMenu>
            <SidebarMenuItem default-open>
              <SidebarMenuButton>Account</SidebarMenuButton>
              <SidebarMenuSub>
                <SidebarMenuItem>
                  <SidebarMenuButton
                    :href="`#${id}-profile`"
                    :active="current === 'profile'"
                    @click="current = 'profile'"
                  >
                    Profile
                  </SidebarMenuButton>
                </SidebarMenuItem>
                <SidebarMenuItem>
                  <SidebarMenuButton
                    :href="`#${id}-security`"
                    :active="current === 'security'"
                    @click="current = 'security'"
                  >
                    Security
                  </SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenuSub>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroup>
      </SidebarContent>
    </Sidebar>
    <SidebarInset>
      <div class="space-y-6">
        <section :id="`${id}-profile`">
          <h2>Profile</h2>
          <p>Your profile content.</p>
        </section>
        <section :id="`${id}-security`">
          <h2>Security</h2>
          <p>Your security content.</p>
        </section>
      </div>
    </SidebarInset>
  </SidebarProvider>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Sidebar

Complete API for Sidebar
NameType or signatureDefaultWhat it does
sidepropSidebarSide | undefined"left"Choose the side on which this content appears.
collapsiblepropSidebarCollapsible | undefined"icon"Allow this panel to collapse.
defaultslot{}OptionalContent shown inside Sidebar.

SidebarContent

Complete API for SidebarContent
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarContent.

SidebarFooter

Complete API for SidebarFooter
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarFooter.

SidebarGroup

Complete API for SidebarGroup
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarGroup.

SidebarGroupLabel

Complete API for SidebarGroupLabel
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside SidebarGroupLabel.

SidebarHeader

Complete API for SidebarHeader
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarHeader.

SidebarInset

Complete API for SidebarInset
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarInset.

SidebarMenu

Complete API for SidebarMenu
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside SidebarMenu.

SidebarMenuButton

Complete API for SidebarMenuButton
NameType or signatureDefaultWhat it does
hrefpropstring | undefinedNot setURL to navigate to when this link is activated.
asprop"button" | Component | "a" | undefinedNot setChoose the HTML element or Vue component used for this control.
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
activepropboolean | undefinedfalseMark this item as the current active item.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
typeprop"button" | "submit" | "reset" | undefined"button"Choose the native HTML control type or action behavior.
defaultslot(props: { active: boolean; collapsed: boolean; }) => unknownRequiredContent shown inside SidebarMenuButton.
iconslot((props: { active: boolean; collapsed: boolean; }) => unknown) | undefinedOptionalContent for the icon area of SidebarMenuButton.

SidebarMenuItem

Complete API for SidebarMenuItem
NameType or signatureDefaultWhat it does
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedfalseStarting open state when the parent does not control open.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
update:openevent[open: boolean]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot{}OptionalContent shown inside SidebarMenuItem.

SidebarMenuSub

Complete API for SidebarMenuSub
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside SidebarMenuSub.

SidebarMenuSubTrigger

Complete API for SidebarMenuSubTrigger
NameType or signatureDefaultWhat it does
labelpropstringRequiredVisible or accessible name for this item.

SidebarProvider

Complete API for SidebarProvider
NameType or signatureDefaultWhat it does
collapsedmodelboolean | undefinedNot setCurrent collapsed state of this panel.
defaultCollapsedpropboolean | undefinedfalseStarting collapsed state when the parent does not control it.
mobileOpenmodelboolean | undefinedNot setCurrent mobile open value. Use the matching v-model binding to update it.
defaultMobileOpenpropboolean | undefinedfalseStarting mobile open state when the parent does not control it.
mobilepropboolean | undefinedfalseUse the mobile presentation for this component.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
update:collapsedevent[collapsed: boolean]—Requests a new collapsed value from the parent.
collapsedChangeevent[collapsed: boolean]—Emitted after this value or state changes.
update:mobileOpenevent[open: boolean]—Requests a new mobile open value from the parent.
mobileOpenChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot(props: { collapsed: boolean; mobileOpen: boolean; mobile: boolean; toggle: () => void; }) => unknownRequiredContent shown inside SidebarProvider.
setCollapsedexposed(value: boolean) => void—Access set collapsed from a component template ref.
setMobileOpenexposed(value: boolean) => void—Access set mobile open from a component template ref.
toggleDesktopexposed() => void—Access toggle desktop from a component template ref.
toggleMobileexposed() => void—Access toggle mobile from a component template ref.

SidebarTrigger

Complete API for SidebarTrigger
NameType or signatureDefaultWhat it does
targetpropSidebarTriggerTarget | undefined"auto"Destination element or browsing context for this item.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
typeprop"button" | "submit" | "reset" | undefined"button"Choose the native HTML control type or action behavior.
defaultslot{ expanded: boolean; }OptionalContent shown inside SidebarTrigger.
Public type definitions
Public types
// packages/frameworks/vue/components/sidebar/types.ts
import type { Component } from 'vue'

export type SidebarSide = 'left' | 'right'
export type SidebarCollapsible = 'icon' | 'none'
export type SidebarTriggerTarget = 'auto' | 'desktop' | 'mobile'

export interface SidebarProviderProps {
  collapsed?: boolean
  defaultCollapsed?: boolean
  mobileOpen?: boolean
  defaultMobileOpen?: boolean
  mobile?: boolean
  disabled?: boolean
}

export interface SidebarProps {
  side?: SidebarSide
  collapsible?: SidebarCollapsible
}

export interface SidebarTriggerProps {
  target?: SidebarTriggerTarget
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
}

export interface SidebarMenuButtonProps {
  href?: string
  as?: 'button' | 'a' | Component
  asChild?: boolean
  link?: boolean
  active?: boolean
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
}

export interface SidebarMenuItemProps {
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
}

Implementation notes

  • Persist collapsed state in the application when it should survive navigation or reloads.
  • When a parent row also navigates, use SidebarMenuSubTrigger as its separate disclosure control.
  • The compact SidebarTrigger gives slight press feedback; menu rows keep their active styling.

Accessibility and localization

  • Name the sidebar content and provide a usable label for icon-only triggers; mark the current route active.

Source contract and editing guidance