Sidebar

Helix adoption: When building a new product, always use the Helix master sidebar pattern described below — do not build from raw shadcn/ui <Sidebar> primitives. The master defines the required anatomy, sizing, and styling. Products supply their own nav items, icons, and optional features.

Import

import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarTrigger,
} from "@timelycare/helix-ui"

Props

interface SidebarProps {
  side?: "left" | "right"
  variant?: "sidebar" | "floating" | "inset"
  collapsible?: "offcanvas" | "icon" | "none"
  className?: string
}

interface SidebarMenuButtonProps {
  asChild?: boolean
  isActive?: boolean
  tooltip?: string | TooltipContentProps
  variant?: "default" | "outline"
  size?: "default" | "sm" | "lg"
}

Structure

Note: The TimelyCare sidebar uses a flat navigation without SidebarGroupLabel headings. All menu items sit in a single SidebarGroup with no subheadings. SidebarGroupLabel is available but not used in any current product sidebar.

Master Sidebar (Use This)

The master sidebar is the required starting point for every Helix product. It defines the structural scaffold and styling rules — not a fixed set of menu items. Do not build sidebars from raw shadcn/ui primitives; use this pattern so that every product gets consistent sizing, spacing, states, and footer behavior out of the box.

Non-negotiable aspects

1. Menu item sizing and styles — Every menu item uses size-4 (16px) icons, text-sm font-medium, h-10 gap-2 px-2 rounded-md spacing (40px fixed height), and the active/hover state tokens listed in the States section. In collapsed mode, each item renders as a size-10 (40×40px) square button with the icon centered. The expanded h-10 and collapsed size-10 ensure icons stay at the same vertical position during the expand/collapse transition.
2. Log Out button in the footer — Every Helix sidebar places a visible LogOut icon + text button in SidebarFooter. Do not use the default shadcn avatar/dropdown menu pattern.
3. Optional notification card stack — The footer supports 1–3 stacked notification cards above Log Out. These are opt-in per product — omit them if the product does not need them.

What the master does NOT prescribe

• A fixed number of menu items — add as many or as few as the product requires.
• Mandatory notification cards — include them only when the product needs promotional or feature-awareness cards.
• Specific icons or labels — each product chooses its own Lucide icons and nav labels.

Master scaffold

<SidebarProvider>
  <Sidebar collapsible="icon">
    <SidebarHeader>
      <Logo /> {/* Brand wordmark (expanded) / icon mark (collapsed) */}
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          {/* Repeat SidebarMenuItem for each nav item the product needs */}
          <SidebarMenuItem>
            <SidebarMenuButton isActive={…} tooltip="Label">
              <Icon className="size-4" />
              <span>Label</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      {/* Optional: notification card stack */}
      <SidebarMenuButton tooltip="Log Out">
        <LogOut className="size-4" />
        <span>Log Out</span>
      </SidebarMenuButton>
    </SidebarFooter>
  </Sidebar>
</SidebarProvider>

Collapsed State (Icon Rail)

The sidebar supports a collapsible="icon" mode that collapses to a 48px icon-only rail.

Collapse Trigger

Collapse is controlled externally via a SidebarTrigger (PanelLeft icon) in the page header — not inside the sidebar itself. The header component provides the toggle; the sidebar only responds to state.

// In the page Header component:
<SidebarTrigger>
  <Button variant="ghost" size="icon" className="size-7">
    <PanelLeft className="size-4" />
  </Button>
</SidebarTrigger>

SidebarHeader (Logo)

The header displays the TimelyCare brand wordmark in expanded state and collapses to an icon mark placeholder.

import { Logo } from "@timelycare/helix-ui"

The default variant (TC-logo_2C.svg) is used across all product platforms — member, campus, provider, and admin all share the same TimelyCare wordmark.

Logo click resets navigation

Clicking the logo (in either expanded or collapsed state) navigates the user back to the home page and resets the Header breadcrumbs to "Home". This provides a consistent "go home" affordance regardless of sidebar state.

<SidebarHeader>
  <button onClick={() => navigate("/")} className="h-16 flex items-center px-6">
    {/* Expanded: TimelyCare wordmark */}
    <Logo variant="default" width={120} height={44} />
    {/* Collapsed: icon mark placeholder */}
  </button>
</SidebarHeader>

Menu Button

Sub-Menu

Accordion behavior

Only one collapsible sub-menu group can be expanded at a time. When the user opens a new group, the previously open group closes automatically. All sub-menus start closed by default — even if a child item is the active route, the sub-menu must be explicitly opened by the user or programmatically opened on navigation.

Selection promotion on accordion close

When the user closes an accordion that contains the currently selected sub-menu item:

1. The parent menu item inherits the selected state (shows as active).
2. The child selection is saved internally.
3. If the user re-opens that same accordion without selecting anything else in between, the saved child item is restored as the active selection and the parent returns to default state.
4. If the user selects a different item before re-opening, the saved child is discarded.

Collapsed state + collapsible items

When the sidebar is in collapsed (icon rail) mode and the user clicks a menu item that has sub-menu children:

1. The sidebar automatically expands back to the default/open state.
2. The clicked item's accordion opens to reveal its sub-menu items.
3. The user can then select the specific sub-menu item they want.

This ensures sub-menu navigation is always accessible since sub-menus are not shown in the collapsed state.

const [openGroup, setOpenGroup] = useState<string | null>(null)
const [savedChildId, setSavedChildId] = useState<string | null>(null)

const handleToggleGroup = (group: string) => {
  if (openGroup === group) {
    // Closing — promote parent if a child is selected
    if (selectedId?.startsWith(group + "/")) {
      setSavedChildId(selectedId)
      setSelectedId(group)
    }
    setOpenGroup(null)
  } else {
    // Opening — restore saved child if it belongs to this group
    if (savedChildId?.startsWith(group + "/")) {
      setSelectedId(savedChildId)
      setSavedChildId(null)
    }
    setOpenGroup(group)
  }
}

const handleSelect = (id: string) => {
  setSelectedId(id)
  setSavedChildId(null) // Clear saved child on any new selection
}

const handleExpandGroup = (group: string) => {
  setIsCollapsed(false)
  setOpenGroup(group)
}

Badge (Notification Count)

<SidebarMenuButton>
  <Mail className="size-4" />
  <span>Messages</span>
  <SidebarMenuBadge>8</SidebarMenuBadge>
</SidebarMenuButton>

States

Selection behavior: Nothing is selected by default. Selection is driven by user interaction (click/navigation). The isActive prop on SidebarMenuButton controls the active visual state.

Parent vs child selection visibility

When a sub-menu child is selected:

• Accordion open: Only the child shows active. The parent menu item returns to default state.
• Accordion closed: The parent inherits the active state (child is not visible).
• Collapsed sidebar: The parent icon shows active (children are never visible in collapsed mode).

Sub-menu item states

Sub-menu items follow the same hover and selected styles as top-level menu items (hover uses sidebar-accent-hover + sidebar-accent-hover-foreground, selected uses sidebar-accent + sidebar-accent-foreground):

Notification Card Stack (Footer)

An optional stack of overlapping notification cards in the SidebarFooter, positioned above the Log Out button.

Footer alignment: The SidebarFooter has p-2. The nav content area has an additional inner p-2 wrapper. To keep the Log Out button icon-aligned with nav items, wrap it in a px-2 container (matching the nav's inner padding). The notification card stack also uses a px-2 wrapper.

<SidebarFooter className="p-2">
  {/* Optional notification card stack — px-2 aligns with nav items */}
  <div className="px-2">
    <SidebarCard
      headerText="New Feature!"
      description="Check out our new Breathwork Tool in Self-Care"
      showImage
    />
  </div>
  {/* Log Out — px-2 wrapper aligns icon with nav items above */}
  <div className="px-2">
    <SidebarMenuButton tooltip="Log Out">
      <LogOut className="size-4" />
      <span>Log Out</span>
    </SidebarMenuButton>
  </div>
</SidebarFooter>

Common Patterns

Basic Navigation

<SidebarProvider>
  <Sidebar collapsible="icon">
    <SidebarHeader>
      <Logo />
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton isActive tooltip="Dashboard">
              <Home className="size-4" />
              <span>Dashboard</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarMenuButton tooltip="Log Out">
        <LogOut className="size-4" />
        <span>Log Out</span>
      </SidebarMenuButton>
    </SidebarFooter>
  </Sidebar>
</SidebarProvider>

Collapsible with Sub-menu (Accordion)

// openGroup state is managed at the sidebar level (see Accordion behavior above)
<Collapsible
  open={openGroup === "visits"}
  onOpenChange={() => handleToggleGroup("visits")}
>
  <SidebarMenuItem>
    <CollapsibleTrigger asChild>
      <SidebarMenuButton>
        <Calendar className="size-4" />
        <span>Visits</span>
        <ChevronDown className="ml-auto size-4 transition-transform group-data-[state=open]:rotate-180" />
      </SidebarMenuButton>
    </CollapsibleTrigger>
    <CollapsibleContent>
      <SidebarMenuSub>
        <SidebarMenuSubItem>
          <SidebarMenuSubButton isActive={selectedId === "visits/in-progress"}>
            In Progress
          </SidebarMenuSubButton>
        </SidebarMenuSubItem>
        <SidebarMenuSubItem>
          <SidebarMenuSubButton>Scheduled</SidebarMenuSubButton>
        </SidebarMenuSubItem>
      </SidebarMenuSub>
    </CollapsibleContent>
  </SidebarMenuItem>
</Collapsible>

With Badge and Notification Cards

<SidebarProvider>
  <Sidebar collapsible="icon">
    <SidebarHeader><Logo /></SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton tooltip="Messages">
              <Mail className="size-4" />
              <span>Messages</span>
              <SidebarMenuBadge>8</SidebarMenuBadge>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarCard headerText="New Feature!" description="Try our Breathwork Tool" showImage />
      <SidebarMenuButton tooltip="Log Out">
        <LogOut className="size-4" />
        <span>Log Out</span>
      </SidebarMenuButton>
    </SidebarFooter>
  </Sidebar>
</SidebarProvider>

Product Variants (Reference Only)

The following are concrete implementations of the master sidebar for existing TimelyCare products. They are included as reference — use the master scaffold above as your starting point, not these product-specific configurations.

Four TimelyCare products use the sidebar with different navigation structures. All share the same component and styling — only the menu items, icons, and footer content differ.

Member (timelyCare)

Admin (timelyAdmin)

Campus (timelyCampus)

Provider (timelyProvider)

Accessibility

• Custom component using Radix Sheet for mobile overlay
• Use <nav> landmark element with aria-label="Main navigation"
• Keyboard: Tab through nav items, Escape to close mobile sidebar
• Mobile sidebar: focus trapped via Sheet component
• Collapsible sections use aria-expanded
• Collapsed tooltips provide text labels for screen readers

Gotchas

See Also

• Related Components: Navigation Menu (top navigation), Header (app header with SidebarTrigger and breadcrumbs), Breadcrumb (breadcrumb primitives), Card (notification card styling)
• Accessibility: Navigation Accessibility — Sidebar landmark patterns

Last updated: February 27, 2026