useOrganization()
The useOrganization()
hook is used to retrieve attributes of the currently active organization.
useOrganization()
parameters
useOrganization()
accepts a single object with the following optional properties:
Properties | Description |
---|---|
invitations? | true or an object with status: OrganizationInvitationStatus or any of the properties described in Shared properties. If set to true , all default properties will be used. |
membershipRequests? | true or an object with status: OrganizationInvitationStatus or any of the properties described in Shared properties. If set to true , all default properties will be used. |
memberships? | true or an object with role: OrganizationCustomRoleKey[] or any of the properties described in Shared properties. If set to true , all default properties will be used. |
domains? | true or an object with enrollmentMode: OrganizationEnrollmentMode or any of the properties described in Shared properties. If set to true , all default properties will be used. |
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.
Shared properties
Properties that are shared across the invitations
, membershipRequests
, memberships
, and domains
properties.
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
useOrganization()
accepts status
as a property for the invitations
and membershipRequests
parameters.
status
is a string that can be one of the following:
type OrganizationInvitationStatus = "pending" | "accepted" | "revoked";
OrganizationCustomRoleKey
useOrganization
accepts role
as a property for the memberships
parameter.
role
is a string that represents the user's role in the organization. Clerk provides the default roles org:admin
and org:member
. However, you can create custom roles as well.
OrganizationEnrollmentMode
useOrganization()
accepts enrollmentMode
as a property for the domains
paramater.
enrollmentMode
is a string that can be one of the following:
type OrganizationEnrollmentMode = "manual_invitation" | "automatic_invitation" | "automatic_suggestion";
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.
useOrganization()
returns
Name | Type | Description |
---|---|---|
isLoaded | boolean | A boolean that is set to false until Clerk loads and initializes. |
organization | Organization | The currently active organization. |
membership | OrganizationMembership | The current organization membership. |
memberships | PaginatedResources | Includes a paginated list of the organization's memberships. |
invitations | PaginatedResources | Includes a paginated list of the organization's invitations. |
membershipRequests | PaginatedResources | Includes a paginated list of the organization's membership requests. |
domains | PaginatedResources | Includes a paginated list of the organization's domains. |
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 next page to be loaded. This is the same as fetchPage(page=> Math.min(pageCount, 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. |
revalidate | A function that triggers a revalidation of the current page. |
setData | A function that allows you to set the data manually. |
How to use the useOrganization()
hook
Expanding and paginating 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. So 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} < {membership.publicUserData.identifier}> :: {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} < {membership.publicUserData.identifier}> :: {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(opens in a new tab).
Last updated on February 27, 2024