Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

useOrganizationList()

The useOrganizationList hook allows you to retrieve the memberships, invitations, or suggestions for an active user. This hook also gives you the ability to create an organization and set the active organization.

Usage

The useOrganizationList hook requires developers to opt-in by specifying which resource they need to fetch and paginate through. It is ideal for infinite lists or tables.

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

Infinite list of joined organizations

pages/joined-organizations.tsx
import { useOrganizationList } from "@clerk/nextjs"; import React from "react"; const JoinedOrganizationList = () => { const { isLoaded, setActive, userMemberships } = useOrganizationList({ userMemberships: { infinite: true, }, }); if (!isLoaded) { return <>Loading</>; } return ( <> <ul> {userMemberships.data?.map((mem) => ( <li key={mem.id}> <span>{mem.organization.name}</span> <button onClick={() => setActive({ organization: mem.organization.id })} > Select </button> </li> ))} </ul> <button disabled={!userMemberships.hasNextPage} onClick={() => userMemberships.fetchNext()} > Load more </button> </> ); }; export default JoinedOrganizationList;
joined-organizations.tsx
import { useOrganizationList } from "@clerk/clerk-react"; import React from "react"; const JoinedOrganizationList = () => { const { isLoaded, setActive, userMemberships } = useOrganizationList({ userMemberships: { infinite: true, }, }); if (!isLoaded) { return <>Loading</>; } return ( <> <ul> {userMemberships.data?.map((mem) => ( <li key={mem.id}> <span>{mem.organization.name}</span> <button onClick={() => setActive({ organization: mem.organization.id })} > Select </button> </li> ))} </ul> <button disabled={!userMemberships.hasNextPage} onClick={() => userMemberships.fetchNext()} > Load more </button> </> ); }; export default JoinedOrganizationList;

Table of invitations

pages/joined-organizations.tsx
import { useOrganizationList } from "@clerk/nextjs"; import React from "react"; const InvitationsTable = () => { const { isLoaded, userInvitations } = useOrganizationList({ userInvitations: { infinite: true, keepPreviousData: true, }, }); if (!isLoaded || userInvitations.isLoading) { return <>Loading</>; } return ( <> <table> <thead> <tr> <th>Email</th> <th>Org name</th> </tr> </thead> <tbody> {userInvitations.data?.map((inv) => ( <tr key={inv.id}> <th>{inv.emailAddress}</th> <th>{inv.publicOrganizationData.name}</th> </tr> ))} </tbody> </table> <button disabled={!userInvitations.hasPreviousPage} onClick={userInvitations.fetchPrevious} > Prev </button> <button disabled={!userInvitations.hasNextPage} onClick={userInvitations.fetchNext} > Next </button> </> ); }; export default InvitationsTable;
joined-organizations.tsx
import { useOrganizationList } from "@clerk/nextjs"; import React from "react"; const InvitationsTable = () => { const { isLoaded, userInvitations } = useOrganizationList({ userInvitations: { infinite: true, keepPreviousData: true, }, }); if (!isLoaded || userInvitations.isLoading) { return <>Loading</>; } return ( <> <table> <thead> <tr> <th>Email</th> <th>Org name</th> </tr> </thead> <tbody> {userInvitations.data?.map((inv) => ( <tr key={inv.id}> <th>{inv.emailAddress}</th> <th>{inv.publicOrganizationData.name}</th> </tr> ))} </tbody> </table> <button disabled={!userInvitations.hasPreviousPage} onClick={userInvitations.fetchPrevious} > Prev </button> <button disabled={!userInvitations.hasNextPage} onClick={userInvitations.fetchNext} > Next </button> </> ); }; export default InvitationsTable;

Parameters

useOrganizationList accepts a single object with the following properties:

PropertiesDescription
userMembershipsCommonPaginatedParams
userInvitationsCommonPaginatedParams and status which describes the status of an invitation, defaults to pending.
userSuggestionsCommonPaginatedParams and status which describes the status of a suggestion, defaults to pending.

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
initialPageA 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.
pageSizeA number that indicates the maximum number of results that should be returned for a specific page. Defaults to 10.
keepPreviousDataIf true, it will persist the cached data until the new data has been fetched. Defaults to false.
infiniteIf true, the new downloaded data will be appended to the list with the existing data. Ideal for infinite lists. Defaults to false.

Returns

The userMemberships, userInvitations, and userSuggestions 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.
createOrganizationA function that returns a promise that resolves to the newly created Organization. It accepts a name and a slug
setActiveA function that sets the active organization. It accepts either the organization object or the organization id.
userMembershipsAPI for fetching paginated resources.
userInvitationsAPI for fetching paginated resources.
userSuggestionsAPI 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 next 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