useEmailAddresses

useEmailAddresses() lists the signed-in user’s email addresses and exposes helpers to add a new address, re-send its verification email, promote a verified address to primary, or remove a non-primary one. It tracks loading state and the in-flight action id so you can disable the right row.

Email is a first-class identity: a user can collect several addresses. Any verified address can sign in; exactly one is the primary (the address shown as the account’s main contact). Changing your email is no longer a single mutable field: it’s add → verify → set-primary.

When to use it

• Build an “email addresses” screen (the prebuilt <UserProfile> Profile section already wraps this).

Usage

import { useEmailAddresses } from '@torii-js/torii-react';

function EmailAddresses() {
  const {
    emailAddresses,
    addEmailAddress,
    setPrimary,
    removeEmailAddress,
    resendVerification,
    pendingActionId,
  } = useEmailAddresses();

  return (
    <>
      <button onClick={() => addEmailAddress('new@example.com')}>Add email</button>
      <ul>
        {emailAddresses.map((a) => (
          <li key={a.id}>
            {a.email}
            {a.primary && ' (primary)'}
            {!a.verified && (
              <button
                disabled={pendingActionId === a.id}
                onClick={() => resendVerification(a.id)}
              >
                Resend verification
              </button>
            )}
            {a.verified && !a.primary && (
              <button disabled={pendingActionId === a.id} onClick={() => setPrimary(a.id)}>
                Make primary
              </button>
            )}
            {!a.primary && (
              <button disabled={pendingActionId === a.id} onClick={() => removeEmailAddress(a.id)}>
                Remove
              </button>
            )}
          </li>
        ))}
      </ul>
    </>
  );
}

Returns

Name	Type	Description
emailAddresses	EmailAddress[]	The user’s email addresses. Empty while loading or when signed out. Each carries id, email, verified, primary.
isLoading	boolean	true while the list is being fetched.
error	ToriiError | null	Message from the last operation, or null.
refresh	() => Promise<void>	Re-fetch the list from the server.
addEmailAddress	(email: string) => Promise<MutationResult<void>>	Add a new address. The server sends a verification email; the address starts unverified. Resolves a MutationResult; check .ok.
setPrimary	(addressId: string) => Promise<MutationResult<void>>	Promote a verified address to primary. Resolves a MutationResult; check .ok.
removeEmailAddress	(addressId: string) => Promise<MutationResult<void>>	Remove a non-primary address by id. Resolves a MutationResult; check .ok.
resendVerification	(addressId: string) => Promise<MutationResult<void>>	Re-send the verification email for an unverified address. Resolves a MutationResult; check .ok.
pendingActionId	string | null	Id of the address with a setPrimary / removeEmailAddress / resendVerification action in flight, else null.

Notes

• Add → verify → set-primary. A newly added address is unverified and cannot be primary or used to sign in until the user clicks the verification link. Only a verified address can be promoted via setPrimary.
• Primary is protected: you cannot remove the primary address. Promote another verified address to primary first, then remove the old one.
• Any verified address can sign in. The primary address is the account’s main contact; sign-in accepts any verified address on the account.

TypeScript

import type { UseEmailAddressesReturn, EmailAddress } from '@torii-js/torii-react';