useOrganization()
The useOrganization()
hook retrieves attributes of the currently active organization.
Parameters
useOrganization()
accepts a single object with the following optional properties:
- Name
-
domains?
- Type
true | { initialPage: number; pageSize: number; } & { enrollmentMode: "manual_invitation" | "automatic_invitation" | "automatic_suggestion"; } & { infinite: boolean; keepPreviousData: boolean; }
- 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.
- Name
-
invitations?
- Type
true | { initialPage: number; pageSize: number; } & { status: ("expired" | "revoked" | "pending" | "accepted")[]; } & { infinite: boolean; keepPreviousData: boolean; }
- 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 | { initialPage: number; pageSize: number; } & { status: "expired" | "revoked" | "pending" | "accepted"; } & { infinite: boolean; keepPreviousData: boolean; }
- 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 | { initialPage: number; pageSize: number; } & { query: string; role: string[]; } & { infinite: boolean; keepPreviousData: boolean; }
- Description
If set to
true
, all default properties will be used.
Otherwise, accepts an object with the following optional properties:role
: An array ofOrganizationCustomRoleKey
.query
: A string that filters the memberships by the provided string.- Any of the properties described in Shared properties.
- Name
-
subscriptions?
- Type
true | { initialPage: number; pageSize: number; } & object & { orgId: string; } & { infinite: boolean; keepPreviousData: boolean; }
- Description
If set to
true
, all default properties will be used.
Otherwise, accepts an object with the following optional properties:orgId
: A string that filters the subscriptions by the provided organization ID.- Any of the properties described in Shared properties.
Shared properties
Optional properties that are shared across the invitations
, membershipRequests
, memberships
, and domains
properties.
- 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 tofalse
.
- Name
keepPreviousData?
- Type
boolean
- Description
If
true
, the previous data will be kept in the cache until new data is fetched. Defaults tofalse
.
- Name
-
domains
- Type
null | PaginatedResourcesWithDefault<OrganizationDomainResource> | PaginatedResources<OrganizationDomainResource, T["membershipRequests"] extends { infinite: true; } ? true : false>
- Description
Includes a paginated list of the organization's domains.
- Name
-
invitations
- Type
null | PaginatedResourcesWithDefault<OrganizationInvitationResource> | PaginatedResources<OrganizationInvitationResource, T["invitations"] extends { infinite: true; } ? true : false>
- Description
Includes a paginated list of the organization's invitations.
- Name
-
membership
- Type
undefined | null | OrganizationMembershipResource
- Description
The current organization membership.
- Name
-
membershipRequests
- Type
null | PaginatedResourcesWithDefault<OrganizationMembershipRequestResource> | PaginatedResources<OrganizationMembershipRequestResource, T["membershipRequests"] extends { infinite: true; } ? true : false>
- Description
Includes a paginated list of the organization's membership requests.
- Name
-
memberships
- Type
null | PaginatedResourcesWithDefault<OrganizationMembershipResource> | PaginatedResources<OrganizationMembershipResource, T["memberships"] extends { infinite: true; } ? true : false>
- Description
Includes a paginated list of the organization's memberships.
- Name
-
organization
- Type
undefined | null | OrganizationResource
- Description
The currently active organization.
- Name
-
subscriptions
- Type
null | PaginatedResourcesWithDefault<__experimental_CommerceSubscriptionResource> | PaginatedResources<__experimental_CommerceSubscriptionResource, T["subscriptions"] extends { infinite: true; } ? true : false>
- Description
Includes a paginated list of the organization's subscriptions.
- Name
-
data
- Type
T[]
- Description
An array that contains the fetched data. For example, for the
memberships
attribute, data will be an array ofOrganizationMembership
objects.
- Name
-
setData
- Type
Infinite
extendstrue
?CacheSetter
<(undefined | ClerkPaginatedResponse<T>)[]
> :CacheSetter
<undefined | ClerkPaginatedResponse<T>
>- Description
A function that allows you to set the data manually.
Examples
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} <
{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>
)
}
'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} <
{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>
)
}
'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} <
{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.
Feedback
Last updated on