Skip to main content
Docs

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
import { useOrganizationCreationDefaults, useOrganizationList } from '@clerk/react-router'
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/CreateOrganizationWithWarning.tsx
import { useOrganizationCreationDefaults, useOrganizationList } from '@clerk/react-router'
import { FormEventHandler, useEffect, useState } from 'react'

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

  useEffect(() => {
    if (defaults?.form.name) {
      setOrganizationName(defaults.form.name)
    }
  }, [defaults?.form.name])

  if (!isLoaded || isLoading) return <div>Loading...</div>

  // 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))
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={organizationName}
        onChange={(e) => setOrganizationName(e.target.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>
  )
}

Next steps

Build a custom flow for creating Organizations

Learn how to build a custom flow for creating Organizations.

Configure default naming rules

Learn how to configure default naming rules for your Organizations.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub