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"
  className?: string
}

interface SidebarMenuButtonProps {
  asChild?: boolean
  isActive?: boolean
  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 top-level menu item uses size-4 (16px) icons, text-sm font-semibold, h-10 gap-2 px-2 rounded-md spacing (40px fixed height), and the active/hover state tokens listed in the States section. Icons are passed bare (no size/fill/className) — the button owns icon size ([&>svg]:size-4) and color (icons inherit currentColor from the button text).
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>
    <SidebarHeader>
      <Logo />
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          {/* Repeat SidebarMenuItem for each nav item the product needs */}
          <SidebarMenuItem>
            <SidebarMenuButton isActive={…}>
              <Icon className="size-4" />
              <span>Label</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      {/* Optional: notification card stack */}
      <SidebarMenuButton>
        <LogOut className="size-4" />
        <span>Log Out</span>
      </SidebarMenuButton>
    </SidebarFooter>
  </Sidebar>
</SidebarProvider>

SidebarHeader (Logo)

The header displays the TimelyCare brand wordmark.

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 navigates the user back to the home page and resets the Header breadcrumbs to "Home". This provides a consistent "go home" affordance.

<SidebarHeader>
  <button onClick={() => navigate("/")} className="h-16 flex items-center px-6">
    <Logo variant="default" width={120} height={44} />
  </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.

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
}

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).

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>
      <LogOut className="size-4" />
      <span>Log Out</span>
    </SidebarMenuButton>
  </div>
</SidebarFooter>

Common Patterns

Basic Navigation

<SidebarProvider>
  <Sidebar>
    <SidebarHeader>
      <Logo />
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton isActive>
              <Home className="size-4" />
              <span>Dashboard</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarMenuButton>
        <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>
    <SidebarHeader><Logo /></SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton>
              <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>
        <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
• Nav-group expanders use aria-expanded

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: July 22, 2026