@clerk/shared/dist/react/hooks/useOrganizationList.d.ts

Internal package utils used by the Clerk SDKs

import { OrganizationSuggestionResource } from "../../types/organizationSuggestion.js";
import { UserOrganizationInvitationResource } from "../../types/userOrganizationInvitation.js";
import { GetUserOrganizationInvitationsParams, GetUserOrganizationMembershipParams, GetUserOrganizationSuggestionsParams } from "../../types/user.js";
import { OrganizationResource } from "../../types/organization.js";
import { OrganizationMembershipResource } from "../../types/organizationMembership.js";
import { CreateOrganizationParams, SetActive } from "../../types/clerk.js";
import { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from "../types.js";

//#region src/react/hooks/useOrganizationList.d.ts
/**
 * @interface
 */
type UseOrganizationListParams = {
  /**
   * If set to `true`, all default properties will be used.<br />
   * Otherwise, accepts an object with the following optional properties:
   *
   * <ul>
   *  <li>Any of the properties described in [Shared properties](#shared-properties).</li>
   * </ul>
   */
  userMemberships?: true | PaginatedHookConfig<GetUserOrganizationMembershipParams>;
  /**
   * If set to `true`, all default properties will be used.<br />
   * Otherwise, accepts an object with the following optional properties:
   *
   * <ul>
   *  <li>`status`: A string that filters the invitations by the provided status.</li>
   *  <li>Any of the properties described in [Shared properties](#shared-properties).</li>
   * </ul>
   */
  userInvitations?: true | PaginatedHookConfig<GetUserOrganizationInvitationsParams>;
  /**
   * If set to `true`, all default properties will be used.<br />
   * Otherwise, accepts an object with the following optional properties:
   *
   * <ul>
   *  <li>`status`: A string that filters the suggestions by the provided status.</li>
   *  <li>Any of the properties described in [Shared properties](#shared-properties).</li>
   * </ul>
   */
  userSuggestions?: true | PaginatedHookConfig<GetUserOrganizationSuggestionsParams>;
};
/**
 * @interface
 */
type UseOrganizationListReturn<T extends UseOrganizationListParams> = {
  /**
   * Indicates whether Clerk has loaded the current authentication state and there is an authenticated user. Initially `false`, becomes `true` once Clerk loads with a user, and can revert to `false` while auth state is updating (e.g., when switching organizations via [`setActive()`](https://clerk.com/docs/reference/objects/clerk#set-active)).
   */
  isLoaded: false;
  /**
   * A function that returns a `Promise` which resolves to the newly created `Organization`.
   */
  createOrganization: undefined;
  /**
   * A function that sets the active session and/or Organization.
   */
  setActive: undefined;
  /**
   * Returns `PaginatedResources` which includes a list of the user's Organization memberships.
   */
  userMemberships: PaginatedResourcesWithDefault<OrganizationMembershipResource>;
  /**
   * Returns `PaginatedResources` which includes a list of the user's Organization invitations.
   */
  userInvitations: PaginatedResourcesWithDefault<UserOrganizationInvitationResource>;
  /**
   * Returns `PaginatedResources` which includes a list of suggestions for Organizations that the user can join.
   */
  userSuggestions: PaginatedResourcesWithDefault<OrganizationSuggestionResource>;
} | {
  isLoaded: boolean;
  createOrganization: (CreateOrganizationParams: CreateOrganizationParams) => Promise<OrganizationResource>;
  setActive: SetActive;
  userMemberships: PaginatedResources<OrganizationMembershipResource, T['userMemberships'] extends {
    infinite: true;
  } ? true : false>;
  userInvitations: PaginatedResources<UserOrganizationInvitationResource, T['userInvitations'] extends {
    infinite: true;
  } ? true : false>;
  userSuggestions: PaginatedResources<OrganizationSuggestionResource, T['userSuggestions'] extends {
    infinite: true;
  } ? true : false>;
};
/**
 * 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.
 *
 * @example
 * ### 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.
 *
 * ```tsx
 * // 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,
 *   },
 * })
 * ```
 *
 * @example
 * ### 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.
 *
 * ```tsx {{ filename: 'src/components/JoinedOrganizations.tsx' }}
 * import { useOrganizationList } from '@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
 * ```
 *
 * @example
 * ### 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.
 *
 * ```tsx {{ filename: 'src/components/UserInvitationsTable.tsx' }}
 * import { useOrganizationList } from '@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
 * ```
 */
declare function useOrganizationList<T extends UseOrganizationListParams>(params?: T): UseOrganizationListReturn<T>;
//#endregion
export { useOrganizationList };