Sidebar

A collapsible navigation panel that displays items with support for icons, badges, sections, role-based filtering, and tooltips in collapsed state.

Import#

import { Sidebar } from "asheeui";

Usage#

Basic sidebar with flat items#

import { Sidebar } from "asheeui";

const items = [
	{ id: "dashboard", label: "Dashboard" },
	{ id: "users", label: "Users" },
	{ id: "settings", label: "Settings" },
];

export default function Basic() {
	return <Sidebar items={items} title="Navigation" className="w-64" />;
}

Sidebar with sections#

Examples#

Variant#

Size#

Radius#

Item radius#

With sections#

With active item#

Collapsed state#

With back button#

Active item styling#

With badges#

With tooltips (collapsed)#

Role-based filtering#

With footer#

Disabled items#

Custom styling#

With custom link component#

Props#

* Falls back through Global Configuration if not set. See below.

SidebarSection#

SidebarItem#

Global Configuration#

Sidebar reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <Sidebar />
2. Component config: components.sidebar in your ashee.config
3. Theme default: defaultVariant / defaultColor / defaultRadius in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    sidebar: {
      size: "md",
      variant: "default",
      radius: "none",
      itemRadius: "md",
      itemVariant: "ghost",
      activeItemVariant: "solid",
      activeItemColor: "primary",
      showTooltips: true,
      tooltipPlacement: "right",
      collapsible: true,
      defaultCollapsed: false,
      showCollapseButton: true,
    },
  },
};

Built-in fallbacks#

{
  size: "md",
  variant: "default",
  radius: "none",
  itemRadius: "md",
  itemVariant: "ghost",
  activeItemVariant: "solid",
  activeItemColor: "primary",
  showTooltips: true,
  tooltipPlacement: "right",
  tooltipVariant: "solid",
  tooltipColor: "secondary",
  animated: true,
  collapsible: true,
  defaultCollapsed: false,
  showCollapseButton: true,
}

Accessibility#

• Uses native <aside> and <nav> elements for proper semantics
• Implements focus-visible rings for keyboard navigation
• Disabled items prevent interaction and are properly announced
• Tooltips include proper ARIA attributes
• Collapsed state preserves navigation functionality
• Items remain keyboard accessible when collapsed

Notes#

• Items Prop: The items prop accepts either a flat array of SidebarItem or an array of SidebarSection. Flat items are automatically wrapped in a single section.
• Sections: Use sections to group related items with optional section labels.
• Role-based Filtering: Items and sections can be filtered based on the current user's role via the userRole prop and roles arrays.
• Collapsed State: When collapsed, the sidebar shows only icons and tooltips for better space efficiency.
• Tooltips: Tooltips are automatically shown for items when the sidebar is collapsed and showTooltips is enabled.
• Back Button: The back button is displayed in the header when onBack is provided.
• Active Item: The active item is highlighted using the activeItemVariant, activeItemColor, and itemVariant props.
• Custom Link Component: You can replace the default <a> tag with any routing-library link component (e.g., Next.js Link, TanStack Router Link) using the linkComponent prop. Additional props can be passed via linkProps. All styles, interactions, and tooltips are preserved.