Organization Switcher Widget

A widget for switching between organizations in your application.

Add the <OrganizationSwitcher /> widget so users can switch between organizations in your app. No special permissions are required – users can switch between any organizations they have access to. If an organization requires SSO or MFA, the user will be redirected to reauthorize with the new organization.

Switching Organizations

Integrate with the Organization Switcher widget using one of several approaches depending on your library choice. If you are using the authkit-js or authkit-react libraries, use the useAuth hook to get the current organization and pass it to the widget.

JavaScript

 import { useAuth } from '@workos-inc/authkit-react';
import { OrganizationSwitcher, WorkOsWidgets } from '@workos-inc/widgets';
import { CreateOrganization } from '~/app/components/CreateOrganization';

export function OrganizationSwitcherWrapper() {
  const { getAccessToken, switchToOrganization } = useAuth();

  return (
    <WorkOsWidgets>
      <OrganizationSwitcher
        authToken={getAccessToken}
        switchToOrganization={switchToOrganization}
      />
    </WorkOsWidgets>
  );
}

If you are using one of the backend SDKs, build the organization switcher action in the backend and pass it as a prop to the widget. See the Switching Organizations guide for setting up the backend actions.

JavaScript

 import { useAuth } from '@workos-inc/authkit-react';
import { OrganizationSwitcher, WorkOsWidgets } from '@workos-inc/widgets';
import { redirect } from 'next/navigation';

// authToken is a widget token that was fetched in your backend. See the
// "Tokens" section of this guide for details on how to generate the token
export function OrganizationSwitcher({ authToken }) {
  const handleOrganizationSwitch = async (organizationId, pathname) => {
    try {
      // this is some API endpoint defined in your backend that would
      // call the WorkOS APIs to switch the organization or return a redirect URL
      // if the user needs to reauthorize with the new organization
      const response = await fetch('/api/organizations/switch', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ organizationId }),
      });

      if (!response.ok) {
        throw new Error('Failed to switch organization');
      }

      // if the backend returns a redirect URL to reauthorize the user, redirect the user to the new organization
      const { redirectUrl } = await response.json();
      if (redirectUrl) {
        redirect(redirectUrl);
      }

      revalidatePath(pathname);
      redirect(pathname);
    } catch (error) {
      console.error('Error switching organization:', error);
      // Handle error (show toast, etc.)
    }
  };

  return (
    <WorkOsWidgets>
      <OrganizationSwitcher
        authToken={authToken}
        switchToOrganization={handleOrganizationSwitch}
      />
    </WorkOsWidgets>
  );
}

Creating Organizations

Pass children components to the widget to redirect the user to create an organization or to show a modal with a form. Use this to integrate with your existing organization creation flow that uses the WorkOS APIs.

JavaScript

 import { useAuth } from '@workos-inc/authkit-react';
import { OrganizationSwitcher, WorkOsWidgets } from '@workos-inc/widgets';
import { CreateOrganization } from '~/app/components/CreateOrganization';

export function OrganizationSwitcherWrapper() {
  const { getAccessToken, switchToOrganization } = useAuth();

  return (
    <WorkOsWidgets>
      <OrganizationSwitcher
        authToken={getAccessToken}
        switchToOrganization={switchToOrganization}
      >
        <CreateOrganization />
      </OrganizationSwitcher>
    </WorkOsWidgets>
  );
}

API Reference

Prop	Type	Default	Required
`authToken`	`AuthToken`	No default value	Required
`switchToOrganization`	`function`	No default value	Required
`organizationLabel`	`string \| null`	`"Organizations"`	Not required