Parameters
Shared properties
Returns
CreateOrganizationParams
PaginatedResources
Examples

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

Parameters

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

Name
userInvitations?
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
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:

Any of the properties described in Shared 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

Name
createOrganization
Type
undefined | (CreateOrganizationParams) => Promise<OrganizationResource>
Description
A function that returns a Promise which resolves to the newly created Organization.
Name
isLoaded
Type
boolean
Description
A boolean that indicates whether Clerk has completed initialization. Initially false, becomes true once Clerk loads.
Name
setActive
Type
undefined | (setActiveParams) => Promise<void>
Description
A function that sets the active session and/or organization.
Name
userInvitations
Type
PaginatedResourcesWithDefault<UserOrganizationInvitationResource> | PaginatedResources<UserOrganizationInvitationResource, T["userInvitations"] extends { infinite: true; } ? true : false>
Description
Returns PaginatedResources which includes a list of the user's organization invitations.
Name
userMemberships
Type
PaginatedResourcesWithDefault<OrganizationMembershipResource> | PaginatedResources<OrganizationMembershipResource, T["userMemberships"] extends { infinite: true; } ? true : false>
Description
Returns PaginatedResources which includes a list of the user's organization memberships.
Name
userSuggestions
Type
PaginatedResourcesWithDefault<OrganizationSuggestionResource> | PaginatedResources<OrganizationSuggestionResource, T["userSuggestions"] extends { infinite: true; } ? true : false>
Description
Returns PaginatedResources which includes a list of suggestions for organizations that the user can join.

`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 OrganizationMembership 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 | ClerkPaginatedResponse<T>)[]> : CacheSetter<undefined | ClerkPaginatedResponse<T>>
Description
A function that allows you to set the data manually.

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.

React

Next.js

src/components/JoinedOrganizations.tsx

import { useOrganizationList } from '@clerk/clerk-react'
import React from 'react'

const JoinedOrganizations = () => {
  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 JoinedOrganizations

components/JoinedOrganizations.tsx

'use client'

import { useOrganizationList } from '@clerk/nextjs'

export const JoinedOrganizations = () => {
  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>
    </>
  )
}

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.

React

Next.js

src/components/UserInvitationsTable.tsx

import { useOrganizationList } from '@clerk/clerk-react'
import React from 'react'

const UserInvitationsTable = () => {
  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 UserInvitationsTable

components/UserInvitationsTable.tsx

'use client'

import { useOrganizationList } from '@clerk/nextjs'

export const UserInvitationsTable = () => {
  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>
    </>
  )
}

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

Edit this page on GitHub

Last updated on Apr 22, 2025

useOrganizationList()

Feedback

`useOrganizationList()`