Sidebar

A full-height source list sidebar with sections, symbols and selection.

@cupertinoui-pro/mac-sidebarCupertinoUI Pro

Installation

pnpm dlx shadcn@latest add @cupertinoui-pro/mac-sidebar

Part of CupertinoUI Pro: the CLI installs it with your license key, once the @cupertinoui-pro registry is in components.json.

Usage

import {
  MacSidebar,
  MacSidebarContent,
  MacSidebarEmpty,
  MacSidebarHeader,
  MacSidebarItem,
  MacSidebarSearch,
  MacSidebarSection,
  MacSidebarSectionLabel,
} from "@/components/ui/mac-sidebar"

<MacSidebar>
  <MacSidebarHeader>
    <WindowControls />
  </MacSidebarHeader>
  <MacSidebarSearch />
  <MacSidebarContent>
    <MacSidebarSection>
      <MacSidebarSectionLabel>Favorites</MacSidebarSectionLabel>
      <MacSidebarItem active>
        <ClockIcon /> Recents
      </MacSidebarItem>
    </MacSidebarSection>
    <MacSidebarEmpty />
  </MacSidebarContent>
</MacSidebar>
It is called MacSidebar so it can live next to shadcn's application-level Sidebar component.
Items are matched by their text, ignoring case and accents. Badges are left out. Pass value to match on different text, keywords to add more terms, or filter on MacSidebar to replace the matching.

Examples

Add a MacSidebarSearch and the items filter as you type. Sections with no matching items hide with their label, and MacSidebarEmpty shows when nothing matches. Escape clears the search; the down arrow moves to the first result.

API Reference

Every part forwards the props of the underlying element. The props below are the ones CupertinoUI adds or changes.

MacSidebar

A full-height, translucent source list. It holds the search text for the items inside it.

PropTypeDescription
defaultSearchValuestring
Default: ""
The initial search text.
searchValuestringThe search text, when you control it.
onSearchValueChange(value: string) => voidCalled when the search text changes.
filter(text: string, query: string) => booleanDecides whether an item matches. The default ignores case and accents.
classNamestringExtra classes, merged with the component's own.

MacSidebarHeader

The 52pt strip level with the toolbar, for the window controls.

PropTypeDescription
classNamestringExtra classes, merged with the component's own.

MacSidebarSearch

A filled search field wired to the sidebar. Accepts the props of SearchField.

PropTypeDescription
placeholderstring
Default: "Search"
The placeholder text.
classNamestringExtra classes, merged with the component's own.

MacSidebarItem

PropTypeDescription
activeboolean
Default: false
Marks the selected item.
valuestringText to match instead of the item's own text.
keywordsstring[]More terms the item matches, e.g. the settings inside a pane.
renderReactElementRender a link or another element with the item's styles.
classNamestringExtra classes, merged with the component's own.

MacSidebarItemBadge

Trailing content: a count or a small button.

PropTypeDescription
classNamestringExtra classes, merged with the component's own.

MacSidebarEmpty

Shown in place of the items when the search matches nothing.

PropTypeDescription
childrenReactNode
Default: "No Results"
The message.
classNamestringExtra classes, merged with the component's own.