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: "Startup",
        });
        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" \| "Startup" \| "Custom"` — seeds the initial role set.
`country`	`string \| undefined`	Optional country, stored as provided.
`roles`	`readonly RoleDefinition[] \| undefined`	The authored role set for `template: "Custom"`. See `useCapxulOrgRoles` for the `RoleDefinition` shape.

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.

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.