`useWorkspaceList()` hook

useWorkspaceList() is the broad workspace-management hook built on top of useWorkspaceMemberships(). It derives the workspace list from the current user’s workspace memberships, then layers workspace-level management actions on top of that list: members, roles, invitations, updates, and deletion.

Usage

The following example shows a basic usage of useWorkspaceList().

export default function WorkspacePicker() {  const { workspaces, loading } = useWorkspaceList();  if (loading) {    return <p>Loading workspaces…</p>;  }  return (    <ul>      {workspaces.map((workspace) => (        <li key={workspace.id}>{workspace.name}</li>      ))}    </ul>  );}

Return value

The hook returns the following fields and methods.

›

workspaces: WorkspaceWithOrganization[];

Workspaces derived from the current user’s workspace memberships.

›

[].id?: string | undefined;

Workspace identifier.

›

[].name?: string | undefined;

Workspace name.

›

[].image_url?: string | undefined;

Workspace image URL.

›

[].description?: string | undefined;

Workspace description.

›

[].member_count?: number | undefined;

Workspace member count.

›

[].enforce_2fa?: boolean | undefined;

Whether the workspace enforces 2FA.

›

[].enable_ip_restriction?: boolean | undefined;

Whether the workspace uses IP restrictions.

›

[].organization?: Organization | undefined;

Parent organization attached to the workspace entry.

›

id?: string | undefined;

Organization identifier.

›

name?: string | undefined;

Organization name.

›

[].eligibility_restriction?: { type: "none" | "ip_not_allowed" | "mfa_required" | "ip_and_mfa_required"; message: string } | undefined | undefined;

Eligibility restriction attached to the workspace membership when one exists.

›

loading: boolean;

Whether the workspace memberships query is still loading.

›

error: Error | null;

Underlying workspace-memberships query error.

›

refetch: () => Promise<void>;

Revalidates the underlying workspace memberships query.

›

createWorkspace: (organizationId: string, name: string, image?: File, description?: string) => Promise<{ workspace: Workspace; membership: WorkspaceMembership }>;

Creates a new workspace under one organization and refreshes the workspace list.

›

updateWorkspace: (workspace: Workspace, data: { name?: string; description?: string; image?: File; enforce_2fa?: boolean; enable_ip_restriction?: boolean; whitelisted_ips?: string[] }) => Promise<unknown>;

Updates one workspace and refreshes the list.

›

deleteWorkspace: (workspace: Workspace) => Promise<unknown>;

Deletes one workspace, clears token cache, and refreshes the list.

›

leaveWorkspace: (id: string, userId: string) => Promise<void>;

Leaves one workspace as one specific user and refreshes the list.

›

getWorkspaceMembers: (workspace: Workspace, params?: { page: number; limit: number; search?: string }) => Promise<PaginatedResponse<WorkspaceMembership[]>>;

Loads members for a workspace, optionally with pagination and search.

›

removeWorkspaceMember: (workspace: Workspace, memberId: string) => Promise<unknown>;

Removes one member from a workspace and refreshes the list.

›

getWorkspaceRoles: (workspace: Workspace) => Promise<WorkspaceRole[]>;

Loads roles for a workspace.

›

createWorkspaceRole: (workspace: Workspace, name: string, permissions: string[]) => Promise<WorkspaceRole>;

Creates a custom workspace role.

›

deleteWorkspaceRole: (workspace: Workspace, role: WorkspaceRole) => Promise<unknown>;

Deletes one workspace role.

›

addWorkspaceMemberRole: (workspace: Workspace, membershipId: string, roleId: string) => Promise<unknown>;

Adds one role to a workspace membership.

›

removeWorkspaceMemberRole: (workspace: Workspace, membershipId: string, roleId: string) => Promise<unknown>;

Removes one role from a workspace membership.

›

getWorkspaceInvitations: (workspace: WorkspaceWithOrganization) => Promise<any[]>;

Loads invitations for a workspace through the parent organization invitation surface.

›

createWorkspaceInvitation: (workspace: WorkspaceWithOrganization, email: string, workspaceRoleId?: string) => Promise<unknown>;

Creates a workspace invitation through the parent organization invitation surface.

›

discardWorkspaceInvitation: (workspace: WorkspaceWithOrganization, invitationId: string) => Promise<unknown>;

Discards a workspace invitation through the parent organization invitation surface.

›

resendWorkspaceInvitation: (workspace: WorkspaceWithOrganization, invitationId: string) => Promise<unknown>;

Resends a workspace invitation through the parent organization invitation surface.

How it works

This hook does not fetch a dedicated workspace list endpoint. It derives workspaces from useWorkspaceMemberships(), so the list only contains workspaces the current user is actually a member of.

Each workspace entry is enriched with its parent organization and any eligibility restriction from the workspace membership. That is why the list type is WorkspaceWithOrganization[] instead of plain Workspace[].

Workspace invitations are handled through the organization invitation surface in the current implementation. That is why the invitation helpers require a WorkspaceWithOrganization rather than only a workspace ID.

The hook mixes read helpers and mutation helpers. It is appropriate for workspace-management UI, but broader than what you want for a simple current-workspace read.

When to use it

Examples

Render the workspace list

export default function WorkspaceList() {  const { workspaces, loading } = useWorkspaceList();  if (loading) {    return <p>Loading workspaces…</p>;  }  return (    <ul>      {workspaces.map((workspace) => (        <li key={workspace.id}>{workspace.name}</li>      ))}    </ul>  );}

Create a workspace inside one organization

export default function CreateWorkspaceButton() {  const { createWorkspace } = useWorkspaceList();  async function create() {    await createWorkspace('org_123', 'Operations');  }  return <button onClick={create}>Create workspace</button>;}

Load workspace members

export default function LoadWorkspaceMembers() {  const { workspaces, getWorkspaceMembers } = useWorkspaceList();  async function load() {    const workspace = workspaces[0];    if (!workspace) {      return;    }    const result = await getWorkspaceMembers(workspace, {      page: 1,      limit: 20,    });    console.log(result.items);  }  return <button onClick={load}>Load workspace members</button>;}

useWorkspaceList() hook