useCapxulCreateOrg
Mutation hook for creating an organization — claims a handle, seeds roles from a template, and makes the creator its Owner.
Creates an organization: claims its globally-unique handle, seeds the
initial role set from a template, and returns the new org with you as its
Owner. The new org appears in
useCapxulOrgs automatically.
Import
import { useCapxulCreateOrg } from "@capxul/sdk-react";Usage
"use client";
import { useState } from "react";
import { useCapxulCreateOrg } from "@capxul/sdk-react";
function CreateOrgForm({ onCreated }: { onCreated: (orgId: string) => void }) {
const createOrg = useCapxulCreateOrg();
const [name, setName] = useState("");
const [handle, setHandle] = useState("");
return (
<form
onSubmit={async (event) => {
event.preventDefault();
const org = await createOrg.mutateAsync({
name,
handle,
template: "Solo",
});
onCreated(org.id);
}}
>
<input
required
placeholder="Acme Inc."
value={name}
onChange={(event) => setName(event.target.value)}
/>
<input
required
placeholder="acme"
value={handle}
onChange={(event) => setHandle(event.target.value)}
/>
<button type="submit" disabled={createOrg.isPending}>
{createOrg.isPending ? "Creating…" : "Create organization"}
</button>
{createOrg.error ? <p>{createOrg.error.message}</p> : null}
</form>
);
}Parameters
The hook itself takes no parameters. The mutation takes a CreateOrgInput:
| Field | Type | Description |
|---|---|---|
name | string | The org's display name. |
handle | string | The org's handle — normalized (^[a-z0-9-]{3,32}$) and globally unique; claimed at creation. |
template | OrgTemplate | "Solo" — the one supported shape. Any other value is refused with WRONG_STATE. |
country | string | undefined | Optional country, stored as provided. |
Return type
import { type UseCapxulCreateOrgReturn } from "@capxul/sdk-react";
// UseMutationResult<OrgView, CapxulError, CreateOrgInput>On success, data is the created OrgView — see
useCapxulOrgs for the field
list. Your role in the new org is "Owner", and its treasury starts at
zero.
The hook returns TanStack Query's UseMutationResult. The most-used fields:
| Field | Description |
|---|---|
mutate | Fire the mutation (fire-and-forget; pair with onSuccess/onError callbacks). |
mutateAsync | Fire the mutation and get a Promise of the result. Rejects with a CapxulError on failure. |
data | The mutation result (typed per hook, shown above). undefined until the first success. |
error | A CapxulError when the last attempt failed, otherwise null. |
isPending | true while the mutation is in flight. Use it to disable submit buttons. |
reset | Clear the mutation state (data, error) back to idle. |
Mutations do not retry by default. The full field list is in the
TanStack Query useMutation reference;
see also the TanStack Query integration guide.
Client-backed mutation hooks are safe to render while CapxulProvider
bootstraps. If one is fired before bootstrap finishes, mutateAsync rejects
with a CapxulError whose code is WRONG_STATE; applications do not need to
hide their route tree behind useCapxul(). Every shipped mutation hook is
client-backed — alpha.23 removed the one client-free hook
(useCapxulSwitchActingEntity, a documented no-op).
Cache behavior
On success this mutation invalidates the org list (["capxul", "orgs"]), so
useCapxulOrgs refetches and the
new org shows up without manual wiring.
Errors
Failures surface as a CapxulError on
error / thrown from mutateAsync — for example when the handle does not
match the required shape or is already claimed.
Client method
This hook wraps client.createOrg(input) on the core SDK.