BuildBaseBuildBase

Workspace Switcher

Drop-in workspace selector with search, create, and switch built in.

WorkspaceSwitcher is a render-prop component. You provide the trigger UI, and BuildBase handles the dropdown with search, create, and switch functionality.

import { useSaaSWorkspaces, WorkspaceSwitcher } from '@buildbase/sdk/react';

function Navbar() {
  const { currentWorkspace } = useSaaSWorkspaces();

  return (
    <nav className="flex h-14 items-center justify-between border-b px-4">
      <div className="flex items-center gap-3">
        <Logo />
        <WorkspaceSwitcher
          trigger={(isLoading, workspace) => (
            <button className="flex items-center gap-2 rounded-md px-3 py-1.5 hover:bg-gray-100">
              <span className="font-medium">
                {isLoading
                  ? 'Loading...'
                  : (workspace?.name ?? 'Select workspace')}
              </span>
              <ChevronDownIcon className="h-4 w-4 text-gray-500" />
            </button>
          )}
        />
      </div>
      <UserMenu />
    </nav>
  );
}

Tip

The WorkspaceSwitcher includes create, search, and switch functionality built in. You only need to provide the trigger button.

Props

PropTypeDescription
trigger(isLoading: boolean, currentWorkspace: IWorkspace | null) => ReactNodeRender function for the trigger element. First param is loading state, second is the active workspace or null.

How the trigger works

The trigger prop receives two arguments: a boolean isLoading flag and the current workspace object (or null if none is selected). Return any React element — a button, a styled div, an icon. The switcher dropdown attaches to whatever you render.

import { WorkspaceSwitcher } from '@buildbase/sdk/react';

function MinimalSwitcher() {
  return (
    <WorkspaceSwitcher
      trigger={(isLoading, workspace) => (
        <button>
          {isLoading ? 'Loading...' : (workspace?.name ?? 'No workspace')}
        </button>
      )}
    />
  );
}

What's built in

The WorkspaceSwitcher dropdown includes:

  • Search across all workspaces
  • Create a new workspace (users type a name and it's created instantly)
  • Switch between workspaces in one click

Reacting to workspace changes

WorkspaceSwitcher has no change callback. To run code when the user switches workspace, use the onWorkspaceChange callback in the provider's auth.callbacks. It receives { workspace, user, role } and fires before the switch — the switch proceeds only when the returned promise resolves, and rejecting aborts it.

import { ApiVersion, SaaSOSProvider } from '@buildbase/sdk/react';

function AppProvider({ children }) {
  return (
    <SaaSOSProvider
      serverUrl="https://your-server.com"
      version={ApiVersion.V1}
      orgId="your-org-id"
      auth={{
        clientId: 'your-client-id',
        redirectUrl: 'http://localhost:3000/callback',
        callbacks: {
          // ...getSession, handleAuthentication, onSignOut
          onWorkspaceChange: async ({ workspace, user, role }) => {
            // Runs before the switch completes. Throw to abort the switch.
            console.log(
              `${user?.name} switching to ${workspace.name} as ${role}`
            );
          },
        },
      }}
    >
      {children}
    </SaaSOSProvider>
  );
}

It also fires when the workspace is restored from storage on page refresh. For the required callbacks (getSession, handleAuthentication, onSignOut), see Installation.

Next Steps

  • Managing Members — Invite users, assign roles, and manage workspace membership.