Docs

<OrganizationSwitcher /> component

The <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 allows a user to switch between their account types - their personal account and their joined organizations. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations.

This component will show notifications to the user if they have organization invitations or suggestions. Admins will be able to see notifications for requests to join an organization.

If you would like to learn how to hide a user's personal account in order to enforce an organization-centric application, see the dedicated guide.

<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: {...}}

  • Name
    hideSlug
    Type
    boolean
    Description

    Hides the optional slug field in the organization creation screen.

Usage with frameworks

app/organization-switcher/[[...organization-switcher]]/page.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>
  )
}
/pages/organization-switcher.astro
---
import { OrganizationSwitcher } from '@clerk/astro/components'
---

<OrganizationSwitcher />

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 clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(clerkPubKey)
await clerk.load()

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

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

clerk.mountOrganizationSwitcher(orgSwitcherDiv)

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 clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(clerkPubKey)
await clerk.load()

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

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

clerk.mountOrganizationSwitcher(orgSwitcherDiv)

// ...

clerk.unmountOrganizationSwitcher(orgSwitcherDiv)

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

Last updated on