Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

useOrganization()

The useOrganization() hook gives you access to the current active organization attributes.

const { isLoaded, organization, membership, invitations, memberships, membershipRequests, domains, } = useOrganization();

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.

Usage

Make sure you've followed the installation guide for Clerk React before running the snippets below.

In the following example, useOrganization() is used to map over the memberships of the current active organization and present membership attributes. In addition, buttons support navigating through the paginated response.

Note that your component must be a descendant of <ClerkProvider/>.

Expanding and paginating attributes

To keep network usage to a minimum, we require developers to opt-in by specifying which resource they need to fetch and paginate through.

const { invitations } = useOrganization(); // invitations.data will never be populated // Use default values to fetch invitations const { invitations } = useOrganization({ invitations: true }); // Override 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

import { useOrganization } from "@clerk/nextjs"; export default function MemberList() { const { memberships } = useOrganization({ memberships: { infinite: true, keepPreviousData: true, }, }); if (!memberships) { // 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} onClick={memberships.fetchNext} > Load more </button> </div> ); }

Simple pagination

import { useOrganization } from "@clerk/nextjs"; export default function MemberList() { const { memberships } = useOrganization({ memberships: { keepPreviousData: true, }, }); if (!memberships) { // 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 a demo application utilising the hook and the organizations feature, take a look at our organizations demo repository.

Parameters

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

PropertiesDescription
invitations?CommonPaginatedParams and OrganizationInvitationStatus[]
membershipRequests?CommonPaginatedParams and OrganizationInvitationStatus
memberships?CommonPaginatedParams and MembershipRole?
domains?CommonPaginatedParams and OrganizationEnrollmentMode

CommonPaginatedParams

CommonPaginatedParams can be either true or an object with the properties described below. If set to true, all of the default values will be used.

PropertiesDescription
initialPage?A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page. Defaults to 1.
pageSize?A number that indicates the maximum number of results that should be returned for a specific page. Defaults to 10.
keepPreviousData?If true, it will persist the cached data until the new data has been fetched. Defaults to false.
infinite?If true, the new downloaded data will be appended to the list with the existing data. Ideal for infinite lists. Defaults to false.

OrganizationInvitationStatus

type OrganizationInvitationStatus = "pending" | "accepted" | "revoked";

MembershipRole

type MembershipRole = "admin" | "org:member";

OrganizationEnrollmentMode

type OrganizationEnrollmentMode = "manual_invitation" | "automatic_invitation" | "automatic_suggestion";

Returns

The memberships, membershipRequests, and domains are returned as paginated lists.

VariablesDescription
isLoadedA boolean is set to false until Clerk loads and initializes. Once Clerk loads, isLoaded will be set to true.
organizationThe current active organization.
membershipThe current organization membership.
invitationsAPI for fetching paginated resources.
membershipsAPI for fetching paginated resources.
membershipRequestsAPI for fetching paginated resources.
domainsAPI for fetching paginated resources.

PaginatedResources

VariablesDescription
dataAn array that contains the fetched data.
countThe total count of data that exist remotely.
isLoadingA boolean that is true if there is an ongoing request and there is no fetched data.
isFetchingA boolean that is true if there is an ongoing request or a revalidation.
isErrorA boolean that indicates the request failed.
pageA number that indicates the current page.
pageCountA number that indicates the total amount of pages. It is calculated based on count , initialPage , and pageSize
fetchPageA function that triggers a specific page to be loaded.
fetchPreviousA helper function that triggers the previous page to be loaded. This is the same as fetchPage(page=> Math.max(0, page - 1))
fetchNextA helper function that triggers the previous page to be loaded. This is the same as fetchPage(page=> Math.max(0, page + 1))
hasNextPageA boolean that indicates if there are available pages to be fetched.
hasPreviousPageA boolean that indicates if there are available pages to be fetched.

What did you think of this content?

Clerk © 2023