# Workspace sidebar

> A product sidebar with a workspace switcher, live search, draggable favorites, and inline projects.

- Page: https://ui.xzero.co.uk/components/blocks/workspace-sidebar

## Variant: Workspace

A product sidebar with a workspace switcher, live search, draggable favorites, and inline projects.

- Access: Xzero Pro
- Registry id: `workspace-sidebar`
- Source file: `registry/blocks/workspace-sidebar/workspace-sidebar.tsx`
- Built from: Search field, Avatar, Animated counter, Text morph, Button
- Keywords: react sidebar, workspace switcher, collapsible sidebar, app sidebar navigation, icon rail sidebar, linear style sidebar, draggable favorites

Use this as the main navigation of a multi-workspace app. Load workspaces, favorites, and projects from your API, route through onNavigate, and persist order and new projects; creation in the preview is simulated.

### When to use

- The main navigation of a multi-workspace app.
- Sidebars with draggable favorites and inline project creation.
- Navigation that should collapse to an icon rail with the [ shortcut.

### When not to use

- Use sidebar-rail when you need the whole app shell with a mobile sheet.
- Use docs-sidebar for documentation trees.
- Use inbox-sidebar for mail folders and labels.

## Installation

Register both Xzero UI namespaces in your project's components.json:

```json
{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}
```

```bash
npx shadcn@4.23.0 add @xzero-ui-pro/workspace-sidebar
```

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

### Usage

```tsx
import { WorkspaceSidebar } from "@/components/xzero/blocks/workspace-sidebar/workspace-sidebar";
import { useRouter } from "next/navigation";

export function AppNav() {
  const router = useRouter();

  return (
    <WorkspaceSidebar
      onNavigate={({ workspace, id }) => router.push(`/${workspace}/${id}`)}
      onCollapsedChange={(collapsed) => localStorage.setItem("rail", String(collapsed))}
    />
  );
}
```

### API reference

#### WorkspaceSidebar

A product sidebar with a workspace switcher, live search, draggable favorites, inline project creation, and a collapsible icon rail. Workspaces, favorites, and projects are sample data.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Extra class on the root element. |
| `onNavigate` | `(target: { workspace: string; id: string; name: string }) => void` | – | Called when a favorite or project is opened. Connect it to your router. |
| `defaultCollapsed` | `boolean` | `false` | Start as the narrow icon rail. |
| `onCollapsedChange` | `(collapsed: boolean) => void` | – | Called when the sidebar collapses or expands, from the toggle or the [ shortcut. |

### Keyboard interactions

| Keys | Action |
| --- | --- |
| [ | Toggles the icon rail when focus is not in a text field, menu, or dialog. |
| Alt+Arrow Up / Down | Moves the focused favorite up or down. |
| Escape | Clears the search, or cancels a new project name. |

### Accessibility

- The workspace switcher is a Radix dropdown menu with full menu keyboard support.
- Favorites can be reordered by keyboard as well as by drag.
- The rail shortcut ignores inputs, menus, and dialogs so typing is never hijacked.

### Motion

- The sidebar width springs between full and rail, and favorites reorder with layout animation.
- New projects slide in and counts roll with the animated counter.
- Reduced motion is applied after hydration and makes width and reorder changes instant.

### Responsive behavior

- The open width is the --full custom property, 272px by default, and the rail is 64px.
- It has no mobile sheet; below 380px it only shortens to 660px, so pair it with drawer on phones.
- Favorites drag on the y axis with Reorder, and Alt+Arrow keys reorder without a pointer.

### Performance

- Width springs through one motion value, so collapsing does not re-render the lists.
- Lists are not virtualized; keep favorites and projects to a sidebar's worth of rows.

### Notes for AI

- Use as the main navigation of a multi-workspace app.
- Load workspaces, favorites, and projects from your API, route through onNavigate, and persist favorite order and new projects yourself.
- Composes Xzero search-field, avatar, animated-counter, text-morph, and button.

### Related

- [Sidebar: App rail](https://ui.xzero.co.uk/components/blocks/workspace-sidebar/markdown): An app shell whose sidebar folds into an icon rail and slides in as a sheet on phones.
- [Sidebar: Inbox](https://ui.xzero.co.uk/components/blocks/workspace-sidebar/markdown): A mail sidebar whose Compose button grows into a composer and whose folders take dropped mail.
- [Sidebar: Docs](https://ui.xzero.co.uk/components/blocks/workspace-sidebar/markdown): A docs layout with a live filtering nav tree, version switcher, and a gliding on this page outline.
- [Search field](https://ui.xzero.co.uk/components/search-field/markdown): A recognizable search entry point with clear affordances.
- [Reorderable list](https://ui.xzero.co.uk/components/reorderable-list/markdown): Organize items with direct drag and drop.