Workspace Switcher React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Workspace Switcher is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import WorkspaceSwitcher from @/components/ui/workspace-switcher.

"use client"

import { Settings, UserPlus } from "lucide-react"
import { WorkspaceSwitcher, type Workspace } from "@/components/ui/workspace-switcher"

const workspaces: Workspace[] = [
  { id: "emma", name: "Emma Carter", logo: "/avatars/emma.jpg", plan: "Free", group: "Personal" },
  { id: "north-studio", name: "North Studio LLC", plan: "Pro", description: "12 members · New York", group: "Teams" },
  { id: "summit", name: "Summit Logistics", plan: "Business", description: "48 members · Boston", group: "Teams" },
]

export function SidebarHeader({ onSwitch }: { onSwitch: (id: string) => Promise<void> }) {
  return (
    <WorkspaceSwitcher
      workspaces={workspaces}
      defaultValue="north-studio"
      onValueChange={(id) => onSwitch(id)}
      shortcuts
      onCreate={() => console.log("new workspace")}
      createLabel="Create workspace"
      actions={[
        { label: "Workspace settings", icon: <Settings />, href: "/settings" },
        { label: "Invite members", icon: <UserPlus />, onSelect: () => console.log("invite") },
      ]}
      searchPlaceholder="Search workspaces"
      emptyText="No workspaces found"
      sheetTitle="Switch workspace"
    />
  )
}

Props

• workspacesdefault "[{ id: "personal", name: "Personal", plan: "Free", description: "Just you", group: "Personal" }, { id: "acme", name: "Acme Inc", plan: "Pro", description: "12 members", group: "Teams" }, { id: "northwind", name: "Northwind", plan: "Business", description: "48 members", group: "Teams" }]"
  Workspace[]

  The workspaces: { id, name, logo?: string (image url) | ReactNode (an icon on a color from the name), description?, plan?, group?, disabled?, keywords? }. Without a logo (or when the image fails) the initials show on a color from the name, legal forms left out (North Studio LLC reads NS). The logo alone is exported as WorkspaceLogo ({ workspace, size, radius, variant }) for your own rows.

• value
  string

  The current workspace id (controlled). An id that is not in the list shows the placeholder.

• defaultValuedefault ""
  string

  The starting workspace id while uncontrolled. Empty: the first enabled workspace; an unknown id shows the placeholder.

• onValueChange
  (id: string, workspace: Workspace) => (void | Promise<unknown>)

  Fires on a pick or a Mod+1…9 switch. Return a promise and the row shows a spinner while the list stays open; the switch commits when it resolves (a rejection keeps the current workspace).

• variantdefault "card"
  "card" | "compact" | "icon"

  card: logo, name, plan / description and an up-down chevron filling the width (sidebar headers; logo only in a collapsed sidebar). compact: logo, name and a chevron (top bars). icon: the logo alone with a tooltip (rails).

• sizedefault "md"
  "sm" | "md" | "lg"

  card and icon: 40 / 48 / 56px with a 24 / 32 / 40px logo. compact: 32 / 40 / 48px, like the buttons next to it in a top bar. 44px targets on touch.

• logoRadiusdefault "md"
  "sm" | "md" | "full"

  Logo corners, proportional to its size: organization logos are rounded squares, full makes circles.

• logoVariantdefault "solid"
  "solid" | "soft"

  The look of logos without an image: solid white initials on a color from the name, or a soft tint with deep initials.

• metadefault "auto"
  "auto" | "plan" | "description" | "none"

  The card's second line: the plan and the description joined with a dot (auto), one of them, or nothing.

• searchdefault "auto"
  "auto" | "always" | "never"

  The search row on top of the list. auto: above 6 workspaces. On touch screens it waits for a tap so the keyboard does not cover the list (unless always).

• searchPlaceholderdefault "Find a workspace"
  string

  The search row's placeholder.

• emptyTextdefault "No workspaces found"
  string

  Shown when the search matches nothing.

• groupBydefault true
  boolean

  Groups rows under their workspace.group label, in the order the groups first appear.

• shortcutsdefault false
  boolean

  Binds Mod+1 … Mod+9 to the first nine enabled workspaces while mounted (Slack, Linear), shows the hints in the rows and announces the switch.

• onCreate
  () => void

  Shows the Create workspace row under the list.

• createLabeldefault "Create workspace"
  string

  The create row's label.

• actions
  MenuItemEntry[]

  More footer rows, in dropdown-menu's item format: { label, icon, shortcut, badge, href, onSelect, tone, disabled, keepOpen }. href rows render through NavLink; shortcuts run while it is open.

• placeholderdefault "Select a workspace"
  string

  The trigger's text while no workspace is selected.

• contentWidthdefault 288
  number

  The list's width in px; never narrower than the trigger, never wider than the screen.

• maxHeightdefault 460
  number

  The list's maximum height in px, capped by the room on screen; the list scrolls and the footer stays.

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the list opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  Alignment against the trigger.

• sideOffsetdefault 8
  number

  Gap between the trigger and the list, in px.

• open
  boolean

  Controlled open state; pair it with onOpenChange.

• defaultOpendefault false
  boolean

  Starts open (uncontrolled).

• onOpenChange
  (open: boolean) => void

  Fires when the list or the sheet opens or closes.

• disableddefault false
  boolean

  Dims the trigger and keeps it closed.

• responsivedefault true
  boolean

  Below 768px the list becomes a bottom sheet. Off: the popover on every screen.

• sheetTitledefault "Switch workspace"
  string

  The phone sheet's title, and the list's accessible name.

• shortcutdefault ""
  string

  A key combo in mod+k notation that opens and closes it from anywhere (e.g. mod+o); the trigger gets aria-keyshortcuts. Empty binds nothing.

• triggerLabeldefault "(name) => "Workspace: " + name"
  (name: string) => string

  The icon trigger's accessible name and tooltip.

• switchingLabeldefault "Switching"
  string

  What screen readers hear for the row spinner while a switch loads.

• container
  HTMLElement | null

  Portal target for the list and the sheet (default document.body).

• classNames
  Partial<Record<"trigger" | "logo" | "name" | "meta" | "chevron" | "content" | "search" | "list" | "option" | "optionLogo" | "optionName" | "optionDescription" | "optionPlan" | "optionShortcut" | "empty" | "footer" | "create" | "action", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the trigger, merged last. Other props (id, aria-*, data-*, handlers) are spread onto it.

Parts

FAQ

Used in

More React navigation components