useOrganizationCreationDefaults()

The useOrganizationCreationDefaults() hook retrieves the organization creation defaults for the current user. This includes a suggested organization name based on your application's default naming rules, and an advisory if an organization with that name or domain already exists.

Parameters

useOrganizationCreationDefaults() accepts a single object with the following optional properties:

Name
enabled?
Type
boolean
Description
If true, a request will be triggered when the hook is mounted. Defaults to true.
Name
keepPreviousData?
Type
boolean
Description
If true, the previous data will be kept in the cache until new data is fetched. Defaults to true.

Returns

Name
data
Type
undefined | null | OrganizationCreationDefaultsResource
Description
The organization creation defaults resource, undefined before the first fetch, or null if not available.
Name
error
Type
null | ClerkAPIResponseError
Description
Any error that occurred during the data fetch, or null if no error occurred.
Name
isFetching
Type
boolean
Description
A boolean that indicates whether any request is still in flight, including background updates.
Name
isLoading
Type
boolean
Description
A boolean that indicates whether the initial data is still being fetched.

`OrganizationCreationDefaultsResource`

Name
form
Type
object
Description
An object containing the suggested form values:

name - The suggested organization name.

slug - The suggested organization slug.

logo - The suggested organization logo URL, or null.

blurHash - The blur hash for the logo, or null.
Name
advisory
Type
object | null
Description
An advisory object if there's a potential issue with the suggested organization, or null if no issues. Contains:

code - The advisory type. Currently only 'organization_already_exists'.

severity - The severity level. Currently only 'warning'.

meta - Additional metadata, such as organization_name and organization_domain for existing organizations.

Examples

Basic usage

The following example demonstrates how to use the useOrganizationCreationDefaults() hook to pre-populate an organization creation form with suggested values.

app/components/CreateOrganization.tsx

'use client'

import { useOrganizationCreationDefaults, useOrganizationList } from '@clerk/nextjs'
import { FormEventHandler, useEffect, useState } from 'react'

export default function CreateOrganization() {
  const { createOrganization } = useOrganizationList()
  const { data: defaults, isLoading } = useOrganizationCreationDefaults()
  const [organizationName, setOrganizationName] = useState('')

  // Pre-populate the form with suggested organization name
  useEffect(() => {
    if (defaults?.form.name) {
      setOrganizationName(defaults.form.name)
    }
  }, [defaults?.form.name])

  if (isLoading) return <div>Loading...</div>

  const handleSubmit: FormEventHandler<HTMLFormElement> = async (e) => {
    e.preventDefault()
    await createOrganization?.({ name: organizationName })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={organizationName}
        onChange={(e) => setOrganizationName(e.target.value)}
        placeholder="Organization name"
      />
      <button type="submit">Create organization</button>
    </form>
  )
}

Display advisory warnings

The following example demonstrates how to use the advisory property to display a warning when an organization with the suggested name or domain already exists.

app/components/CreateOrganization.tsx

'use client'

import { useOrganizationCreationDefaults, useOrganizationList } from '@clerk/nextjs'
import { FormEventHandler, useEffect, useState } from 'react'

export default function CreateOrganization() {
  const { isLoaded, createOrganization, setActive } = useOrganizationList()
  const { data: defaults, isLoading: isLoadingDefaults } = useOrganizationCreationDefaults()
  const [organizationName, setOrganizationName] = useState('')

  // Pre-populate the form with suggested organization name
  useEffect(() => {
    if (defaults?.form.name) {
      setOrganizationName(defaults.form.name)
    }
  }, [defaults?.form.name])

  if (!isLoaded || isLoadingDefaults) return <p>Loading...</p>

  // Check if an organization with this name/domain already exists
  const advisory = defaults?.advisory
  const showWarning = advisory?.code === 'organization_already_exists'
  const existingOrgName = advisory?.meta?.organization_name
  const existingOrgDomain = advisory?.meta?.organization_domain

  const handleSubmit: FormEventHandler<HTMLFormElement> = async (e) => {
    e.preventDefault()
    try {
      const newOrganization = await createOrganization?.({ name: organizationName })
      // Set the created Organization as the Active Organization
      if (newOrganization) setActive({ organization: newOrganization.id })
    } catch (err) {
      // See https://clerk.com/docs/guides/development/custom-flows/error-handling
      // for more info on error handling
      console.error(JSON.stringify(err, null, 2))
    }
    setOrganizationName('')
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={organizationName}
        onChange={(e) => setOrganizationName(e.currentTarget.value)}
        placeholder="Organization name"
      />
      {showWarning && (
        <p style={{ color: 'orange' }}>
          An organization "{existingOrgName}" already exists for the domain "{existingOrgDomain}".
        </p>
      )}
      <button type="submit">Create organization</button>
    </form>
  )
}

Edit on GitHub

useOrganizationCreationDefaults()

Parameters

Returns

`OrganizationCreationDefaultsResource`

Examples

Basic usage

Display advisory warnings

Next steps

Build a custom flow for creating Organizations

Configure default naming rules

useOrganizationCreationDefaults()

Feedback