Skip to main content
Docs

useOrganizationList()

The useOrganizationList() hook provides access to the current user's Organization memberships, invitations, and suggestions. It also includes methods for creating new Organizations and managing the .

Parameters

useOrganizationList() accepts a single object with the following properties:

  • Name
    userInvitations?
    Type
    true | { initialPage?: number; pageSize?: number; } & { status?: "expired" | "pending" | "accepted" | "revoked"; } & { 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
    userMemberships?
    Type
    true | { initialPage?: number; pageSize?: number; } & object & { infinite?: boolean; keepPreviousData?: boolean; }
    Description

    If set to true, all default properties will be used.
    Otherwise, accepts an object with the following optional properties:

  • Name
    userSuggestions?
    Type
    true | { initialPage?: number; pageSize?: number; } & { status?: "pending" | "accepted" | ("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 suggestions by the provided status.
    • Any of the properties described in Shared properties.

Warning

By default, the userMemberships, userInvitations, and userSuggestions attributes are not populated. To fetch and paginate the data, you must pass true or an object with the desired properties.

Shared properties

Optional properties that are shared across the userMemberships, userInvitations, and userSuggestions properties.

  • Name
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

  • 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 to false.

  • Name
    keepPreviousData?
    Type
    boolean
    Description

    If true, the previous data will be kept in the cache until new data is fetched. Defaults to false.

Returns

CreateOrganizationParams

  • Name
    name
    Type
    string
    Description

    The name of the Organization.

  • Name
    slug?
    Type
    string
    Description

    The slug of the Organization.

PaginatedResources

  • Name
    count
    Type
    number
    Description

    The total count of data that exist remotely.

  • Name
    data
    Type
    T[]
    Description

    An array that contains the fetched data. For example, for the memberships attribute, data will be an array of OrganizationMembershipJavaScript Icon objects.

  • Name
    error
    Type
    null | ClerkAPIResponseError
    Description

    Clerk's API response error object.

  • Name
    fetchNext
    Type
    () => void
    Description

    A function that triggers the next page to be loaded. This is the same as fetchPage(page => Math.min(pageCount, page + 1)).

  • Name
    fetchPage
    Type
    ValueOrSetter<number>
    Description

    A function that triggers a specific page to be loaded.

  • Name
    fetchPrevious
    Type
    () => void
    Description

    A function that triggers the previous page to be loaded. This is the same as fetchPage(page => Math.max(0, page - 1)).

  • Name
    hasNextPage
    Type
    boolean
    Description

    A boolean that indicates if there are available pages to be fetched.

  • Name
    hasPreviousPage
    Type
    boolean
    Description

    A boolean that indicates if there are available pages to be fetched.

  • Name
    isError
    Type
    boolean
    Description

    A boolean that indicates the request failed.

  • Name
    isFetching
    Type
    boolean
    Description

    A boolean that is true if there is an ongoing request or a revalidation.

  • Name
    isLoading
    Type
    boolean
    Description

    A boolean that is true if there is an ongoing request and there is no fetched data.

  • Name
    page
    Type
    number
    Description

    The current page.

  • Name
    pageCount
    Type
    number
    Description

    The total amount of pages. It is calculated based on count, initialPage, and pageSize.

  • Name
    revalidate
    Type
    () => Promise<void>
    Description

    A function that triggers a revalidation of the current page.

  • Name
    setData
    Type
    Infinite extends true ? CacheSetter<(undefined | ClerkPaginatedResponseJavaScript Icon<T>)[]> : CacheSetter<undefined | ClerkPaginatedResponseJavaScript Icon<T>>
    Description

    A function that allows you to set the data manually.

To see the different Organization features integrated into one application, take a look at our Organizations demo repository.

Examples

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 userMemberships, userInvitations, and userSuggestions attributes are not populated. You must pass true or an object with the desired properties to fetch and paginate the data.

// userMemberships.data will never be populated
const { userMemberships } = useOrganizationList()

// Use default values to fetch userMemberships, such as initialPage = 1 and pageSize = 10
const { userMemberships } = useOrganizationList({
  userMemberships: true,
})

// Pass your own values to fetch userMemberships
const { userMemberships } = useOrganizationList({
  userMemberships: {
    pageSize: 20,
    initialPage: 2, // skips the first page
  },
})

// Aggregate pages in order to render an infinite list
const { userMemberships } = useOrganizationList({
  userMemberships: {
    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 userMemberships attribute will be populated with the first page of the user's Organization 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.

components/JoinedOrganizations.tsx
import { useOrganizationList } from '@clerk/chrome-extension'

export function JoinedOrganizations() {
  const { isLoaded, setActive, userMemberships } = useOrganizationList({
    userMemberships: {
      infinite: true,
    },
  })

  // Handle loading state
  if (!isLoaded) return <div>Loading...</div>

  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>
    </>
  )
}

Simple pagination

The following example demonstrates how to use the fetchPrevious and fetchNext helper functions to paginate through the data. The userInvitations attribute will be populated with the first page of invitations. 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 invitations.

Notice the difference between this example's pagination and the infinite pagination example above.

components/UserInvitationsTable.tsx
import { useOrganizationList } from '@clerk/chrome-extension'

export function UserInvitationsTable() {
  const { isLoaded, userInvitations } = useOrganizationList({
    userInvitations: {
      infinite: true,
      keepPreviousData: true,
    },
  })

  // Handle loading state
  if (!isLoaded || userInvitations.isLoading) return <div>Loading...</div>

  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>
    </>
  )
}

Next steps

Build a custom Organization switcher

Learn how to build a custom flow for switching between Organizations.

Create Organizations

Learn how to build a custom flow for creating Organizations.

Manage a user's Organization invitations

Learn how to build a custom flow for managing a user's Organization invitations.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub