Collapsible Sidebar Navigation with Alpine.js

1. Why a collapsible sidebar navigation matters for UX

A sidebar navigation takes up valuable horizontal space on large screens that not every user needs at all times. Anyone working extensively with forms, tables, or charts wants to temporarily shrink the sidebar to enlarge the working area. This is exactly where the collapsible sidebar navigation pattern comes in: instead of a rigid layout, the user decides how much space the navigation gets to occupy.

The problem intensifies on smaller screens. A sidebar navigation that stays permanently visible on desktop would push the entire content off screen on a tablet or smartphone. A robust sidebar pattern therefore needs two distinct behaviors: a collapsible, content shifting layout on large screens, and an overlay that sits on top of the content on small screens. Alpine.js suits this pattern particularly well because the entire state lives inside a single, declarative component, with no additional library needed for layout logic.

The following sections build a complete sidebar navigation component: from the base structure, through browser persistence, responsive switching between overlay and push layout, nested submenus, up to accessible keyboard operation. Each section builds on the previous one and delivers working code.

2. Base structure with x-data: width, state, and toggle

The core of every sidebar navigation built with Alpine.js is a single boolean that decides whether the sidebar is collapsed or expanded. That boolean is defined inside an x-data block sitting on the wrapping container, so both the toggle button and the sidebar itself can access it. The sidebar width is not controlled through x-show, but through a dynamic class, so a CSS transition can smoothly animate the width change.

It matters to name the state semantically collapsed instead of open when the sidebar navigation is expanded by default. This makes the template considerably easier to read, since x-bind:class expressions otherwise quickly end up doubly negated and hard to follow. The toggle button itself needs no separate x-data, it simply calls collapsed = !collapsed and reads the same state for its icon.

// Sidebar navigation base structure with Alpine.js
document.addEventListener('alpine:init', () => {
  Alpine.data('sidebarNav', () => ({
    collapsed: false,

    toggle() {
      this.collapsed = !this.collapsed;
    },

    // Width class depends on collapsed state
    get widthClass() {
      return this.collapsed ? 'w-16' : 'w-64';
    }
  }));
});

<div x-data="sidebarNav" class="flex h-screen">
  <aside
    class="flex-shrink-0 transition-all duration-300 ease-in-out bg-slate-900 text-white overflow-hidden"
    :class="widthClass"
  >
    <button @click="toggle()" class="p-4" :aria-expanded="!collapsed">
      <span x-show="!collapsed">Navigation</span>
      <span x-show="collapsed">≡</span>
    </button>
    <nav class="px-2" x-show="!collapsed" x-transition.opacity>
      <a href="/dashboard" class="block px-3 py-2 rounded-lg hover:bg-white/10">Dashboard</a>
      <a href="/orders" class="block px-3 py-2 rounded-lg hover:bg-white/10">Orders</a>
      <a href="/settings" class="block px-3 py-2 rounded-lg hover:bg-white/10">Settings</a>
    </nav>
  </aside>
  <main class="flex-1 overflow-auto p-8">
    <!-- Page content pushed by the sidebar navigation width -->
  </main>
</div>

3. Persisting state with localStorage across page loads

Without persistence, a sidebar navigation resets to its default state on every page change, which becomes annoying over time, especially in classic server rendered applications such as Magento backends, where every page is a full reload. The solution is simple: the collapsed state is written to localStorage on every change and read back when the component initializes.

Alpine offers either the official Alpine.persist plugin, or, when no extra file should be loaded, a manual implementation using init() and $watch. The manual approach has the advantage of not requiring a plugin, which is often preferred in restrictive CSP environments as commonly found in Hyva Themes. It matters to parse the stored value defensively, since localStorage only stores strings, and a malformed or stale value must never lead to a broken layout.

// Sidebar navigation with manual localStorage persistence
Alpine.data('sidebarNav', () => ({
  collapsed: false,

  init() {
    const stored = localStorage.getItem('sidebarCollapsed');
    this.collapsed = stored === 'true';

    // Persist every change automatically
    this.$watch('collapsed', (value) => {
      localStorage.setItem('sidebarCollapsed', value);
    });
  },

  toggle() {
    this.collapsed = !this.collapsed;
  }
}));

4. Responsive behavior: overlay on mobile, push on desktop

A well built sidebar navigation behaves differently on desktop than on a phone. On large screens, the sidebar shifts the main content, since there is enough room for both. On small screens that would be unacceptable, so the sidebar must appear as an overlay above the content there, and produce a semi transparent backdrop on open that closes the sidebar when clicked.

Switching between the two modes can be solved entirely through Tailwind breakpoints, without Alpine needing to know which device it runs on at all. The sidebar gets fixed positioning below lg, and relative positioning from lg upward. In addition, the mobile variant needs an x-data flag for the overlay backdrop, which closes the sidebar via @click, plus an escape key handler doing the same.

<div x-data="sidebarNav" @keydown.escape.window="mobileOpen = false">
  <!-- Mobile overlay backdrop, only visible when open on small screens -->
  <div
    x-show="mobileOpen"
    x-transition.opacity
    @click="mobileOpen = false"
    class="fixed inset-0 bg-black/50 z-30 lg:hidden"
  ></div>

  <aside
    class="fixed lg:relative inset-y-0 left-0 z-40 transition-all duration-300 bg-slate-900 text-white"
    :class="{
      'w-64': !collapsed,
      'w-16': collapsed,
      '-translate-x-full lg:translate-x-0': !mobileOpen
    }"
  >
    <!-- Sidebar navigation content -->
  </aside>
</div>

5. Nested submenus inside the sidebar navigation

As soon as a sidebar navigation holds more than a flat list of links, it needs submenus that are themselves collapsible. The obvious pattern: every menu item with children gets its own small x-data object with a boolean for the expanded state, nested inside the parent sidebar component. Alpine allows arbitrarily deep nesting of x-data, each level has access to the parent level's data through scope inheritance.

A detail often overlooked: when the sidebar itself is collapsed, submenus should not all automatically pop open at once when the sidebar expands again. It is worth adding a $watch on the parent sidebar's collapsed state that resets all open submenus on collapse, so the sidebar navigation starts in a tidy state whenever it expands again.

<nav x-data="{ activeSubmenu: null }">
  <template x-for="item in menuItems" :key="item.id">
    <div>
      <button
        @click="item.children ? (activeSubmenu = activeSubmenu === item.id ? null : item.id) : null"
        class="flex items-center justify-between w-full px-3 py-2 rounded-lg hover:bg-white/10"
      >
        <span x-text="item.label"></span>
        <span x-show="item.children" x-text="activeSubmenu === item.id ? '−' : '+'"></span>
      </button>
      <div x-show="item.children && activeSubmenu === item.id" x-collapse class="pl-4">
        <template x-for="child in item.children || []" :key="child.id">
          <a :href="child.url" class="block px-3 py-1.5 text-sm text-white/70 hover:text-white" x-text="child.label"></a>
        </template>
      </div>
    </div>
  </template>
</nav>

6. Keyboard and screen readers: using aria-expanded correctly

A sidebar navigation that only works visually excludes keyboard users and screen reader users. The toggle button absolutely needs aria-expanded, reflecting the current state, plus a meaningful aria-label, since a plain hamburger icon without text is meaningless to a screen reader. Alpine binds these attributes without friction through :aria-expanded, which automatically switches between the boolean values.

For keyboard users, the sidebar navigation should additionally be closable via Escape when shown as an overlay, and focus should jump automatically to the first focusable element inside the sidebar when it opens. On close, focus returns to the toggle button, so keyboard navigation never lands in empty space. This focus logic can be implemented in a few lines with $nextTick and $refs, without an external accessibility library.

<button
  @click="toggle()"
  :aria-expanded="!collapsed"
  aria-label="Expand or collapse the sidebar navigation"
  aria-controls="main-sidebar"
  class="p-3 rounded-lg hover:bg-white/10"
>
  <svg class="w-5 h-5" aria-hidden="true"><!-- icon --></svg>
</button>

<aside id="main-sidebar" role="navigation" aria-label="Main navigation">
  <!-- Sidebar navigation content -->
</aside>

7. Transitions, performance, and the width transition problem

A technical detail many developers overlook on their first sidebar navigation build: CSS transitions on width are among the most expensive animations of all, because they force a layout reflow of the entire document on every frame. On a simple sidebar with little content this barely shows, but on complex dashboards with many charts it can visibly stutter.

The more performant alternative is to animate a transform: translateX value instead of width, and control the actual width through a fixed CSS variable that is only recalculated at layout switch time itself. For most sidebar implementations, a plain width transition is good enough though, as long as will-change: width is not set permanently, since that reserves graphics memory unnecessarily. Alpine's x-transition directives reliably handle opacity transitions for text content, while the width itself runs through a plain CSS class with transition-all duration-300.

8. Integration in Hyva and Magento layout XML

In a Hyva theme, the sidebar navigation component can live as a standalone template under Magento_Theme::page/js/ and be wired in through layout XML for admin adjacent custom modules or customer account dashboards. It matters to expose the Alpine.data('sidebarNav', …) call inside a <script> block through $hyvaCsp->registerInlineScript(), so the Content Security Policy does not block the inline code.

For multi language shops, the toggle button's aria-label should be translated through __() instead of being hardcoded. The menu entries themselves can be passed as JSON from a view model into x-data, so the sidebar navigation structure is maintained centrally in PHP code, and the Alpine template stays responsible for rendering and interaction only, fully in the spirit of separating data from presentation.

9. Sidebar navigation patterns compared

There are several established variants for building a sidebar navigation, each with different tradeoffs regarding space usage, accessibility, and implementation effort. The following table compares the most common approaches.

For most dashboard and admin use cases, combining icon only collapse on desktop with a full overlay on mobile is the most robust compromise, since it works without relying on hover and functions on every input device. The icon only variant additionally needs tooltips, which can be shown via x-data with a short delay, without loading a separate tooltip library.

10. Summary

A collapsible sidebar navigation built with Alpine.js only needs, at its core, a boolean for the collapsed state, a dynamic class for the width, and a second boolean for the mobile overlay mode. Persistence through localStorage ensures the user does not have to reapply their setting on every page load. Nested submenus can be modeled with local x-data per menu item, without complicating the parent component.

Accessibility is not an optional extra, it belongs in the sidebar navigation structure from the start: aria-expanded, meaningful aria-label text, and working keyboard support turn a purely visual component into one accessible to every user. Anyone who keeps the width transition performant and cleanly integrates the structure into Hyva layout XML ends up with a sidebar navigation that works reliably across dashboards and admin areas, without loading a single extra JavaScript library.

11. FAQ: Sidebar Navigation with Alpine.js