useOrganizationList() parameters
useOrganizationList() returns
How to use the useOrganizationList() hook

`useOrganizationList()`

The useOrganizationList() hook allows you to retrieve the organization memberships, invitations, or suggestions for an active user. It also provides methods for creating an organization and setting the active organization.

`useOrganizationList()` parameters

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

Name
userMemberships
Description
true or an object with any of the properties described in Shared properties. If set to true, all default properties will be used.
Name
userInvitations
Description
true or an object with status: OrganizationInvitationStatus or any of the properties described in Shared properties. If set to true, all default properties will be used.
Name
userSuggestions
Description
true or an object with status: OrganizationSuggestionsStatus | OrganizationSuggestionStatus[] or any of the properties described in Shared properties. If set to true, all default properties will be used.

Warning

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.

Shared properties

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

Name
initialPage?
Description
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.
Name
pageSize?
Description
A number that indicates the maximum number of results that should be returned for a specific page. Defaults to 10.
Name
keepPreviousData?
Description
If true, it will persist the cached data until the new data has been fetched. Defaults to false.
Name
infinite?
Description
If true, the new downloaded data will be appended to the list with the existing data. Ideal for infinite lists. Defaults to false.

`OrganizationInvitationStatus`

useOrganizationList() accepts status as a property for the userInvitations parameter.

status is a string that can be one of the following:

type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked'

`OrganizationSuggestionsStatus`

useOrganizationList() accepts status as a property for the userSuggestions parameter.

status can be a string that can be one of the following, or an array of the following:

type OrganizationSuggestionStatus = 'pending' | 'accepted'

`useOrganizationList()` returns

Name
isLoaded
Type
boolean
Description
A boolean is set to false until Clerk loads and initializes. Once Clerk loads, isLoaded will be set to true.
Name
createOrganization()
Type
(params: CreateOrganizationParams) => Promise<OrganizationResource>
Description
A function that returns a Promise which resolves to the newly created Organization.
Name
setActive()
Type
(params: SetActiveParams) => Promise<void>
Description
A function that sets the active session and/or organization.
Name
userMemberships
Type
PaginatedResources
Description
Returns PaginatedResources which includes a list of the user's organization memberships.
Name
userInvitations
Type
PaginatedResources
Description
Returns PaginatedResources which includes a list of the user's organization invitations.
Name
userSuggestions
Type
PaginatedResources
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.

`SetActiveParams`

Name
session
Type
Session | string | null
Description
The session resource or session ID (string version) to be set as active. If null, the current session is deleted.
Name
organization
Type
Organization | string | null
Description
The organization resource or organization ID/slug (string version) to be set as active in the current session. If null, the currently active organization is removed as active.
Name
beforeEmit?
Type
(session?: Session | null) => void | Promise<any>
Description
Callback run just before the active session and/or organization is set to the passed object. Can be used to hook up for pre-navigation actions.

`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.min(pageCount, 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.
`revalidate`	A function that triggers a revalidation of the current page.
`setData`	A function that allows you to set the data manually.

How to use the `useOrganizationList()` hook

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.

app/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

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.

app/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

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 Aug 23, 2024

useOrganizationList()

Feedback

`useOrganizationList()`