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

Properties	Description
`userMemberships`	`CommonPaginatedParams`
`userInvitations`	`CommonPaginatedParams` and `status` which describes the status of an invitation, defaults to `pending`.
`userSuggestions`	`CommonPaginatedParams` 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.

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

Returns

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

Last updated on November 21, 2023