Docs

<OrganizationSwitcher /> component

Clerk's <OrganizationSwitcher /> component is used to enable the ability to switch between available organizations the user may be part of in your application.

The <OrganizationSwitcher /> component is used to enable the ability to switch between available organizations the user may be part of in your application.

<OrganizationSwitcher /> properties

All props below are optional.

  • Name
    afterCreateOrganizationUrl
    Type
    string
    Description

    Full URL or path to navigate to after creating a new organization.

  • Name
    appearance
    Type
    Appearance | undefined
    Description

    Optional object to style your components. Will only affect Clerk Components and not Account Portal pages.

  • Name
    createOrganizationUrl
    Type
    string
    Description

    Full URL or path where the <CreateOrganization /> component is mounted.

  • Name
    organizationProfileUrl
    Type
    string
    Description

    Full URL or path where the <OrganizationProfile /> component is mounted.

  • Name
    createOrganizationMode
    Type
    'modal' | 'navigation'
    Description

    Controls whether clicking the "Create organization" button will cause the <CreateOrganization /> component to open as a modal, or if the browser will navigate to the createOrganizationUrl where <CreateOrganization /> is mounted as a page.
    Defaults to: 'modal'.

  • Name
    organizationProfileMode
    Type
    'modal' | 'navigation'
    Description

    Controls whether clicking the Manage organization button will cause the <OrganizationProfile /> component to open as a modal, or if the browser will navigate to the organizationProfileUrl where <OrganizationProfile /> is mounted as a page.
    Defaults to: 'modal'.

  • Name
    afterLeaveOrganizationUrl
    Type
    string
    Description

    Full URL or path to navigate to after the user leaves the currently active organization.

  • Name
    afterSelectOrganizationUrl
    Type
    string
    Description

    Full URL or path to navigate to after a successful organization switch.

  • Name
    hidePersonal
    Type
    boolean
    Description

    By default, users can switch between organizations and their personal workspace. This option controls whether <OrganizationSwitcher /> will include the user's personal workspace in the organization list. Setting this to true will hide the personal workspace entry, and allow users to switch only between organizations.
    Defaults to: false.

  • Name
    defaultOpen
    Type
    boolean
    Description

    Controls the default state of the <OrganizationSwitcher /> component.

  • Name
    organizationProfileProps
    Type
    object
    Description

    Specify options for the underlying <OrganizationProfile /> component.
    For example: {appearance: {...}}

Usage with frameworks

/app/organization-switcher/[[...organization-switcher]]/page.tsx
import { OrganizationSwitcher } from "@clerk/nextjs";

export default function OrganizationSwitcherPage() {
  return (
    <div>
      <OrganizationSwitcher />
    </div>
  );
}
/pages/organization-switcher/[[...index]].tsx
import { OrganizationSwitcher } from "@clerk/nextjs";

export default function OrganizationSwitcherPage() {
  return (
    <div>
      <OrganizationSwitcher />
    </div>
  );
}
organization-switcher.tsx
import { OrganizationSwitcher } from "@clerk/clerk-react";

export default function OrganizationSwitcherPage() {
  return (
    <div>
      <OrganizationSwitcher />
    </div>
  );
}
/pages/organization-switcher/$.tsx
import { OrganizationSwitcher } from "@clerk/remix";

export default function OrganizationSwitcherPage() {
  return (
    <div>
      <OrganizationSwitcher />
    </div>
  );
}

Usage with JavaScript

The following methods available on an instance of the Clerk class are used to render and control the <OrganizationSwitcher /> component:

The following examples assume that you have followed the quickstart in order to add Clerk to your JavaScript application.

mountOrganizationSwitcher()

Render the <OrganizationSwitcher /> component to an HTML <div> element.

function mountOrganizationSwitcher(node: HTMLDivElement, props?: OrganizationSwitcherProps): void;

mountOrganizationSwitcher() params

  • Name
    node
    Type
    HTMLDivElement
    Description

    The <div> element used to render in the <OrganizationSwitcher /> component

  • Name
    props?
    Type
    OrganizationSwitcherProps
    Description

    The properties to pass to the <OrganizationSwitcher /> component

mountOrganizationSwitcher() usage

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

document.getElementById("app").innerHTML = `
  <div id="organization-switcher"></div>
`;

const orgSwitcherDiv =
  document.getElementById("organization-switcher");

clerk.mountOrganizationSwitcher(orgSwitcherDiv);
index.html
<!-- Add a <div id="organization-switcher"> element to your HTML -->
<div id="organization-switcher"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener("load", async function () {
    await Clerk.load();

    const orgSwitcherDiv =
      document.getElementById('organization-switcher');

    Clerk.mountOrganizationSwitcher(orgSwitcherDiv);
  });
</script>

unmountOrganizationSwitcher()

Unmount and run cleanup on an existing <OrganizationSwitcher /> component instance.

function unmountOrganizationSwitcher(node: HTMLDivElement): void;

unmountOrganizationSwitcher() params

  • Name
    node
    Type
    HTMLDivElement
    Description

    The container <div> element with a rendered <OrganizationSwitcher /> component instance

unmountOrganizationSwitcher() usage

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

document.getElementById('app').innerHTML = `
  <div id="organization-switcher"></div>
`

const orgSwitcherDiv =
  document.getElementById('organization-switcher');

clerk.mountOrganizationSwitcher(orgSwitcherDiv);

// ...

clerk.unmountOrganizationSwitcher(orgSwitcherDiv);
index.html
<!-- Add a <div id="organization-switcher"> element to your HTML -->
<div id="organization-switcher"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener("load", async function () {
    await Clerk.load();

    const orgSwitcherDiv =
      document.getElementById('organization-switcher');

    Clerk.mountOrganizationSwitcher(orgSwitcherDiv);

    // ...

    Clerk.unmountOrganizationSwitcher(orgSwitcherDiv);
  });
</script>

Customization

To learn about how to customize Clerk components, see the customization documentation.

Feedback

What did you think of this content?
Edit this page on GitHub