Skip to main content
Docs
Dashboard

useOrganization()

The useOrganization() hook retrieves attributes of the currently active organization.

Parameters

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

  • Name
    invitations
    Type
    true | { status?: 'pending' | 'accepted' | 'revoked' } & { SharedProperties }
    Description

    If set to true, all default properties will be used.

    Otherwise, accepts an object with the following optional properties:

    • status: A string that filters the invitations by the provided status.
    • Any of the properties described in Shared properties.
  • Name
    membershipRequests
    Type
    true | { status?: 'pending' | 'accepted' | 'revoked' } & { SharedProperties }
    Description

    If set to true, all default properties will be used. Otherwise, accepts an object with the following optional properties:

    • status: A string that filters the membership requests by the provided status.
    • Any of the properties described in Shared properties.
  • Name
    memberships
    Type
    true | { role?: OrganizationCustomRoleKey[]; query?: string } & { SharedProperties }
    Description

    If set to true, all default properties will be used.

    Otherwise, accepts an object with the following optional properties:

  • Name
    domains
    Type
    true | { enrollmentMode?: 'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion' } & { SharedProperties }
    Description

    If set to true, all default properties will be used.

    Otherwise, accepts an object with the following optional properties:

    • enrollmentMode: A string that filters the domains by the provided enrollment mode.
    • Any of the properties described in Shared properties.

Warning

By default, the memberships, invitations, membershipRequests, and domains attributes aren't populated. To fetch and paginate the data, you must pass true or an object with the desired properties.

Shared properties

Optional properties that are shared across the invitations, membershipRequests, memberships, and domains properties.

  • Name
    initialPage
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

  • Name
    keepPreviousData
    Type
    boolean
    Description

    If true, the previous data will be kept in the cache until new data is fetched. Defaults to false.

  • Name
    infinite
    Type
    boolean
    Description

    If true, newly fetched data will be appended to the existing list rather than replacing it. Useful for implementing infinite scroll functionality. Defaults to false.

Note

These attributes are updating automatically and will re-render their respective components whenever you set a different organization using the setActive({ organization }) method or update any of the memberships or invitations. No need for you to manage updating anything manually.

Returns

PaginatedResources

  • Name
    data
    Type
    T[]
    Description

    An array that contains the fetched data. For example, for the memberships attribute, data will be an array of OrganizationMembership objects.

  • Name
    count
    Type
    number
    Description

    The total count of data that exist remotely.

  • Name
    isLoading
    Type
    boolean
    Description

    A boolean that is true if there is an ongoing request and there is no fetched data.

  • Name
    isFetching
    Type
    boolean
    Description

    A boolean that is true if there is an ongoing request or a revalidation.

  • Name
    isError
    Type
    boolean
    Description

    A boolean that indicates the request failed.

  • Name
    page
    Type
    number
    Description

    The current page.

  • Name
    pageCount
    Type
    number
    Description

    The total amount of pages. It is calculated based on count, initialPage, and pageSize.

  • Name
    fetchPage
    Type
    (page: number) => void
    Description

    A function that triggers a specific page to be loaded.

  • Name
    fetchPrevious
    Type
    () => void
    Description

    A function that triggers the previous page to be loaded. This is the same as fetchPage(page => Math.max(0, page - 1)).

  • Name
    fetchNext
    Type
    () => void
    Description

    A function that triggers the next page to be loaded. This is the same as fetchPage(page => Math.min(pageCount, page + 1)).

  • Name
    hasNextPage
    Type
    boolean
    Description

    A boolean that indicates if there are available pages to be fetched.

  • Name
    hasPreviousPage
    Type
    boolean
    Description

    A boolean that indicates if there are available pages to be fetched.

  • Name
    revalidate
    Type
    () => void
    Description

    A function that triggers a revalidation of the current page.

  • Name
    setData
    Type
    (data: any[]) => void
    Description

    A function that allows you to set the data manually.

How to use the useOrganization() hook

Expand and paginate attributes

To keep network usage to a minimum, developers are required to opt-in by specifying which resource they need to fetch and paginate through. By default, the memberships, invitations, membershipRequests, and domains attributes are not populated. You must pass true or an object with the desired properties to fetch and paginate the data.

// invitations.data will never be populated.
const { invitations } = useOrganization()

// Use default values to fetch invitations, such as initialPage = 1 and pageSize = 10
const { invitations } = useOrganization({
  invitations: true,
})

// Pass your own values to fetch invitations
const { invitations } = useOrganization({
  invitations: {
    pageSize: 20,
    initialPage: 2, // skips the first page
  },
})

// Aggregate pages in order to render an infinite list
const { invitations } = useOrganization({
  invitations: {
    infinite: true,
  },
})

Infinite pagination

The following example demonstrates how to use the infinite property to fetch and append new data to the existing list. The memberships attribute will be populated with the first page of the organization's memberships. When the "Load more" button is clicked, the fetchNext helper function will be called to append the next page of memberships to the list.

import { useOrganization } from '@clerk/clerk-react'

export default function MemberList() {
  const { memberships } = useOrganization({
    memberships: {
      infinite: true, // Append new data to the existing list
      keepPreviousData: true, // Persist the cached data until the new data has been fetched
    },
  })

  if (!memberships) {
    // Handle loading state
    return null
  }

  return (
    <div>
      <h2>Organization members</h2>
      <ul>
        {memberships.data?.map((membership) => (
          <li key={membership.id}>
            {membership.publicUserData.firstName} {membership.publicUserData.lastName} &lt;
            {membership.publicUserData.identifier}&gt; :: {membership.role}
          </li>
        ))}
      </ul>

      <button
        disabled={!memberships.hasNextPage} // Disable the button if there are no more available pages to be fetched
        onClick={memberships.fetchNext}
      >
        Load more
      </button>
    </div>
  )
}
app/users/page.tsx
'use client'

import { useOrganization } from '@clerk/nextjs'

export default function MemberListPage() {
  const { memberships } = useOrganization({
    memberships: {
      infinite: true, // Append new data to the existing list
      keepPreviousData: true, // Persist the cached data until the new data has been fetched
    },
  })

  if (!memberships) {
    // Handle loading state
    return null
  }

  return (
    <div>
      <h2>Organization members</h2>
      <ul>
        {memberships.data?.map((membership) => (
          <li key={membership.id}>
            {membership.publicUserData.firstName} {membership.publicUserData.lastName} &lt;
            {membership.publicUserData.identifier}&gt; :: {membership.role}
          </li>
        ))}
      </ul>

      <button
        disabled={!memberships.hasNextPage} // Disable the button if there are no more available pages to be fetched
        onClick={memberships.fetchNext}
      >
        Load more
      </button>
    </div>
  )
}

Simple pagination

The following example demonstrates how to use the fetchPrevious and fetchNext helper functions to paginate through the data. The memberships attribute will be populated with the first page of the organization's memberships. When the "Previous page" or "Next page" button is clicked, the fetchPrevious or fetchNext helper function will be called to fetch the previous or next page of memberships.

Notice the difference between this example's pagination and the infinite pagination example above.

import { useOrganization } from '@clerk/clerk-react'

export default function MemberList() {
  const { memberships } = useOrganization({
    memberships: {
      keepPreviousData: true, // Persist the cached data until the new data has been fetched
    },
  })

  if (!memberships) {
    // Handle loading state
    return null
  }

  return (
    <div>
      <h2>Organization members</h2>
      <ul>
        {memberships.data?.map((membership) => (
          <li key={membership.id}>
            {membership.publicUserData.firstName} {membership.publicUserData.lastName} &lt;
            {membership.publicUserData.identifier}&gt; :: {membership.role}
          </li>
        ))}
      </ul>

      <button disabled={!memberships.hasPreviousPage} onClick={memberships.fetchPrevious}>
        Previous page
      </button>

      <button disabled={!memberships.hasNextPage} onClick={memberships.fetchNext}>
        Next page
      </button>
    </div>
  )
}
app/users/page.tsx
'use client'

import { useOrganization } from '@clerk/nextjs'

export default function MemberListPage() {
  const { memberships } = useOrganization({
    memberships: {
      keepPreviousData: true, // Persist the cached data until the new data has been fetched
    },
  })

  if (!memberships) {
    // Handle loading state
    return null
  }

  return (
    <div>
      <h2>Organization members</h2>
      <ul>
        {memberships.data?.map((membership) => (
          <li key={membership.id}>
            {membership.publicUserData.firstName} {membership.publicUserData.lastName} &lt;
            {membership.publicUserData.identifier}&gt; :: {membership.role}
          </li>
        ))}
      </ul>

      <button disabled={!memberships.hasPreviousPage} onClick={memberships.fetchPrevious}>
        Previous page
      </button>

      <button disabled={!memberships.hasNextPage} onClick={memberships.fetchNext}>
        Next page
      </button>
    </div>
  )
}

To see the different organization features integrated into one application, take a look at our organizations demo repository.

Feedback

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

Last updated on