Profile

The Profile settings page: where a signed-in user changes their picture, display name and email, and the rules each follows.

Settings → Profile (/settings/profile) is the first page under Your account, and where /settings lands. It shows the signed-in user's own name; nobody else's is ever readable or writable there.

Profile settings with picture, name and email controls.Click to expand

Profile settings with picture, name and email controls.

The Picture

The Your picture card shows the current picture (or the initials) and a button to choose a PNG, JPEG or WebP file. A chosen file uploads at once to POST /api/uploads/user-avatar (Storage): the kit checks its bytes, shrinks it to at most 256 px, stores it as WebP under a name it makes (user-avatar/<your id>/<uuid>.webp) and only then points user.image at it; the previous file is deleted afterwards (a failed delete is left to the weekly sweep, never shown as an error; the order is proven in packages/storage/src/__tests__/replace.test.ts). Deleting the account purges the picture in the background (Deleting Your Account). The picture then shows on Profile, in the account menu and in members lists.

  • A wrong file type, an animated, unreadable or oversized (over 2 MB, or too many pixels) image shows an error below the picture (linked to the button for screen readers) and keeps the old one.
  • 10 uploads a minute per visitor, then the card asks to wait (Rate Limits).
  • The picture is public to anyone who has its URL (Images Are Public).
  • Only the server sets user.image: Better Auth's /update-user refuses an image from a browser. A picture from an OAuth sign-in is replaced by an upload, never deleted from the provider.
  • An admin impersonating the user may change the picture, as the name.

The Name

A name is trimmed and must be 1 to 80 characters, with no control characters, line separators or bidi overrides, and not only invisible characters. The same rule runs on sign-up and on every Better Auth endpoint that sets a name (Adding Plugins). Names are stored as plain text: React and the email templates escape them.

  • Saving shows "Your name was updated." and the account menu shows the new name.
  • An invalid name shows a field error and changes nothing.
  • Saving the same name does nothing.
  • 20 changes an hour per user, then the page asks to wait (Rate Limits).

An admin impersonating the user may change the name; account security changes stay refused.

The Email

The Your email card shows the current address and asks for a new one. Changing it takes two links:

  1. Approve, sent to the current address and naming the new one (Approve the new email, Emails). It opens /email-change (pages/email-change/), which shows the change; only its Approve button approves it, so a mail scanner opening the link does nothing. Approvals count toward 3 an hour per user.
  2. Confirm, sent to the new address once approved. Opening it moves the account, signs out every other session (the one that opened it stays signed in) and sends "Your email was changed" to the old address.

While a change is in progress the card shows Pending: new@address and which link it waits for, with Resend: it sends the approval to the current address again, or, once approved, the confirmation to the new one. Resending counts toward the hourly limits: an approval resend is a request (3 an hour), a confirmation resend is an approval (its own 3 an hour). It only resends while the account still has the address the change started from. A new request replaces the pending one; the pending line clears when the change completes or its link expires (30 minutes). It's kept in Better Auth's verification table (packages/better-auth/src/email-change-pending.ts), which Better Auth and the kit's cleanup prune.

A link that expired, or whose old address is no longer the account's, fails: the approval page says so, and a confirmation link lands on Profile with "That email change link has expired…". Nothing changes. A confirmation link opened again after the move (or first by a mail scanner) just lands on Profile.

  • Asking needs a sign-in from the last 10 minutes and is refused while impersonating (Sessions and Guards); past that, the card offers to sign in again and come back.
  • An address another account owns gets the same reply and the same approval email; approving it sends nothing to that address.
  • The current address, or an invalid one, shows a field error.
  • 3 requests an hour per user, then the card asks to wait (Rate Limits).
  • An unverified address can't be changed (Better Auth would skip the approval).

Files

FileOwnerWhat
apps/web/pages/(app)/settings/profile.tsx, profile.server.tsyouThe page, its loader and updateName action
apps/web/components/image-upload-form.tsxyouThe picture card, uploading through @kit/storage/client (answers as storage.errors messages)
apps/web/config/storage-kit-kinds.server.tskitThe user-avatar kind (merged with yours in storage.server.ts)
apps/web/components/profile-name-form.tsx, profile-email-form.tsx, pending-email-change.tsx, account-change-failure.tsxyouThe name and email forms, the pending line, the shared failure alert
apps/web/lib/profile.server.tskitupdateOwnName, requestEmailChange: through auth.api as the user
apps/web/pages/email-change/, apps/web/lib/email-change.server.tsyou, kitThe approval page; readApproval, approveEmailChange
packages/better-auth/src/profile-rules.tskitparseUserName, USER_NAME_MAX_LENGTH, error codes (browser-safe)
packages/better-auth/src/profile-policy.ts, name-change-limit.ts, email-change-policy.ts, email-change-link.ts, user-limit.tskitThe name rule, the per-user limits and the email change's links, as Better Auth hooks