useCapxulLabelAddressBookEntry
Mutation hook that renames an address-book entry in an actor's contact list.
Sets the display label of an address-book entry for an
actor scope. Labels are per-actor: renaming a
contact in an org's address book does not touch the same counterparty in your
personal one. List entries with
useCapxulAddressBook.
Import
import { capxulAccountScope, useCapxulLabelAddressBookEntry } from "@capxul/sdk-react";Usage
"use client";
import { useState } from "react";
import {
capxulAccountScope,
useCapxulLabelAddressBookEntry,
} from "@capxul/sdk-react";
function RenameContactForm({ entryId }: { entryId: string }) {
const labelEntry = useCapxulLabelAddressBookEntry(capxulAccountScope);
const [label, setLabel] = useState("");
return (
<form
onSubmit={async (event) => {
event.preventDefault();
await labelEntry.mutateAsync({ entryId, label });
}}
>
<input
required
value={label}
onChange={(event) => setLabel(event.target.value)}
placeholder="e.g. Studio landlord"
/>
<button type="submit" disabled={labelEntry.isPending}>
{labelEntry.isPending ? "Saving…" : "Rename"}
</button>
{labelEntry.error ? <p>{labelEntry.error.message}</p> : null}
</form>
);
}To rename an entry in an organization's address book, scope the hook with
capxulOrgScope(orgId) instead.
Parameters
actor
CapxulActorScope | undefined — defaults to capxulAccountScope
Which actor's address book to write to. An explicit undefined also falls
back to the personal scope — gate org-scoped controls on the org id being
loaded. See Actor scopes.
Mutation input
The mutation takes an AddressBookLabelInput:
Prop
Type
Return type
import { type UseCapxulLabelAddressBookEntryReturn } from "@capxul/sdk-react";
// UseMutationResult<AddressBookEntry, CapxulError, AddressBookLabelInput>On success, data is the updated AddressBookEntry carrying the new
label.
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, for the acting scope only, the address book list and this entry's detail query.
Errors
Failures surface as a CapxulError on
error / thrown from mutateAsync — for example when the id is not a valid
address-book entry id.
Client method
This hook wraps client.account.addressBook.label(input) for
the personal scope, or
client.org(orgId).addressBook.label(input) for an org
scope.