Skip to main content

useOrganization hooks

Hooks for fetching organization details, looking up organizations by name, and retrieving organization roles. Built on SWR for caching and revalidation. These hooks are created via a factory function (createOrganizationHooks) that accepts an API adapter, then re-exported as standalone hooks via the core hooks provider.

Hooks​

HookDescription
useOrganizationFetches a single organization by ID and provides an update mutation.
useOrganizationByNameFetches a single organization by its name.
useOrganizationRolesFetches all roles associated with an organization.

useOrganization​

Fetches organization data by ID. Also exposes a mutation function to update the organization, with automatic cache invalidation on success.

Signature​

function useOrganization(id: string | null): UseOrganizationReturn

Parameters​

ParamTypeRequiredDescription
idstring | nullYesOrganization ID. Pass null to skip fetching.

Returns​

FieldTypeDescription
organizationOrganization | nullThe fetched organization, or null if not loaded.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.
updateOrganization(arg: Partial<Organization>) => Promise<Organization>Mutation trigger to update the organization.
isMutatingbooleanWhether an update mutation is in progress.
updateErrorError | undefinedError from the most recent update attempt.
updatedDataOrganization | undefinedData returned from the most recent successful update.

Example​

const { organization, isLoading, updateOrganization, isMutating } = useOrganization(orgId);

if (isLoading) return <Skeleton />;

const handleRename = async () => {
  await updateOrganization({ name: "New Name" });
};

On successful update, the hook invalidates both the ["organization", id] cache key and, if the name changed, the ["organizationByName", name] key.

useOrganizationByName​

Fetches organization data by name. Read-only — no mutation capability.

Signature​

function useOrganizationByName(name: string | null): UseOrganizationByNameReturn

Parameters​

ParamTypeRequiredDescription
namestring | nullYesOrganization name. Pass null to skip fetching.

Returns​

FieldTypeDescription
organizationOrganization | nullThe fetched organization, or null if not loaded.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.

Example​

const { organization, isLoading } = useOrganizationByName("acme-corp");

if (isLoading) return <Spinner />;
if (!organization) return <NotFound />;

useOrganizationRoles​

Fetches all roles defined for an organization.

Signature​

function useOrganizationRoles(orgId: string | null): UseOrganizationRolesReturn

Parameters​

ParamTypeRequiredDescription
orgIdstring | nullYesOrganization ID. Pass null to skip fetching.

Returns​

FieldTypeDescription
organizationRolesRole[]Array of roles for the organization. Empty array if not loaded.
isLoadingbooleanSWR loading state.
isErrorError | undefinedSWR error state.

Example​

const { organizationRoles, isLoading } = useOrganizationRoles(orgId);

if (isLoading) return <Skeleton />;

return (
  <ul>
    {organizationRoles.map((role) => (
      <li key={role.id}>{role.name}</li>
    ))}
  </ul>
);