`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:

Properties	Description
`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.

Properties	Description
`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.

Variables	Description
`isLoaded`	A boolean is set to `false` until Clerk loads and initializes. Once Clerk loads, `isLoaded` will be set to `true`.
`organization`	The current active organization.
`membership`	The current organization membership.
`invitations`	API for fetching paginated resources.
`memberships`	API for fetching paginated resources.
`membershipRequests`	API for fetching paginated resources.
`domains`	API for fetching paginated resources.

`PaginatedResources`

Variables	Description
`data`	An array that contains the fetched data.
`count`	The total count of data that exist remotely.
`isLoading`	A boolean that is `true` if there is an ongoing request and there is no fetched data.
`isFetching`	A boolean that is `true` if there is an ongoing request or a revalidation.
`isError`	A boolean that indicates the request failed.
`page`	A number that indicates the current page.
`pageCount`	A number that indicates the total amount of pages. It is calculated based on `count` , `initialPage` , and `pageSize`
`fetchPage`	A function that triggers a specific page to be loaded.
`fetchPrevious`	A helper function that triggers the previous page to be loaded. This is the same as `fetchPage(page=> Math.max(0, page - 1))`
`fetchNext`	A helper function that triggers the previous page to be loaded. This is the same as `fetchPage(page=> Math.max(0, page + 1))`
`hasNextPage`	A boolean that indicates if there are available pages to be fetched.
`hasPreviousPage`	A boolean that indicates if there are available pages to be fetched.