@mks2508/sidebar-headless

Headless sidebar component for React with advanced animations, keyboard navigation, and full WAI-ARIA accessibility.

Features

• 🎨 Headless Architecture - Complete control over styling and behavior
• ⌨️ Keyboard Navigation - Full arrow key, Home/End support
• ♿ WAI-ARIA Compliant - Full accessibility out of the box
• 🎭 Advanced Animations - Fluid hover indicators, glassmorphism effects, 3D transforms
• 🎯 TypeScript First - Full type safety with comprehensive declarations
• 🪶 Lightweight - Minimal dependencies (only clsx + tailwind-merge)
• 🎨 Dark/Light Mode - Automatic theme support via CSS tokens
• 🔧 Highly Configurable - Extensive customization options

Installation

npm install @mks2508/sidebar-headless
# or
yarn add @mks2508/sidebar-headless
# or
pnpm add @mks2508/sidebar-headless
# or
bun add @mks2508/sidebar-headless

Peer Dependencies

This package requires React 18+:

npm install react react-dom

Optional Dependencies

For advanced liquid glass effects (optional):

npm install @liquid-svg-glass/core @liquid-svg-glass/react

Quick Start

import {
  Sidebar,
  SidebarNav,
  SidebarToggle,
  SidebarContent,
  SidebarItem,
  SidebarIconLibrary
} from '@mks2508/sidebar-headless'
import '@mks2508/sidebar-headless/styles.css'

function App() {
  return (
    <Sidebar defaultOpen={true}>
      <SidebarNav>
        <SidebarToggle iconLibrary={SidebarIconLibrary.LUCIDE} />
        <SidebarContent>
          <SidebarItem href="/" icon={<HomeIcon />} label="Home" />
          <SidebarItem href="/settings" icon={<SettingsIcon />} label="Settings" />
        </SidebarContent>
      </SidebarNav>
    </Sidebar>
  )
}

Core Components

Sidebar (Root Provider)

The main container that provides context to all child components.

<Sidebar
  defaultOpen={true}
  collapseMode="hide"
  layoutBehaviour="floating"
>
  {/* ... */}
</Sidebar>

SidebarNav

Navigation container with event management.

<SidebarNav>
  <SidebarToggle />
  <SidebarContent>
    {/* items */}
  </SidebarContent>
</SidebarNav>

SidebarItem

Individual navigation item with optional sub-content.

<SidebarItem
  href="/dashboard"
  icon={<DashboardIcon />}
  label="Dashboard"
>
  <SidebarSubContent title="Dashboard">
    <SidebarSubLink href="/analytics">Analytics</SidebarSubLink>
    <SidebarSubLink href="/reports">Reports</SidebarSubLink>
  </SidebarSubContent>
</SidebarItem>

Configuration Options

Collapse Modes

import { SidebarCollapseMode } from '@mks2508/sidebar-headless'

// Collapse to icon-only width
<Sidebar collapseMode={SidebarCollapseMode.COLLAPSE} />

// Hide completely
<Sidebar collapseMode={SidebarCollapseMode.HIDE} />

Layout Behaviours

import { SidebarLayoutBehaviour } from '@mks2508/sidebar-headless'

// Floating sidebar (doesn't push content)
<Sidebar layoutBehaviour={SidebarLayoutBehaviour.FLOATING} />

// Inline sidebar (pushes content)
<Sidebar layoutBehaviour={SidebarLayoutBehaviour.INLINE} />

Custom Dimensions

<Sidebar
  dimensions={{
    collapsedWidth: "4rem",
    expandedWidth: "18rem",
    indicatorHeight: "3rem",
    tooltipDistance: "16px"
  }}
/>

Advanced Features

Fluid Indicators

Enable glassmorphism-style hover indicators:

<Sidebar
  enableFluidIndicator={true}
  liquidGlass={{
    enableLiquidGlassV2: true,
    enableChromaticAberration: true
  }}
/>

Keyboard Navigation

Built-in keyboard shortcuts:

• Arrow Up/Down: Navigate between items
• Home: Jump to first item
• End: Jump to last item
• Enter: Activate focused item

Render Props

Access sidebar state via render props:

<Sidebar>
  {({ open, collapsed }) => (
    <div>
      <SidebarNav />
      <p>Sidebar is {open ? 'open' : 'closed'}</p>
    </div>
  )}
</Sidebar>

Styling

The sidebar uses shadcn-style CSS tokens for theming:

:root {
  --sidebar: oklch(98% 0 0);
  --sidebar-foreground: oklch(20% 0 0);
  --sidebar-primary: oklch(55% 0.2 250);
  --sidebar-accent: oklch(95% 0.01 250);
  --sidebar-border: oklch(90% 0.01 250);
  --sidebar-ring: oklch(55% 0.2 250);
}

.dark {
  --sidebar: oklch(17% 0 0);
  --sidebar-foreground: oklch(90% 0 0);
  /* ... */
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  SidebarProps,
  SidebarItemProps,
  SidebarContextValue
} from '@mks2508/sidebar-headless'

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Modern browsers with ES2020 support

License

MIT © MKS2508

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• Report Issues