ElvixUsername
Username claim widget with availability check, reserved-word ban, and validation rules baked in. Per-app membership, debounced live check.
"use client";import { ElvixUsername } from "@elvix.is/sdk/react";export function UsernamePane() {return (<ElvixUsernameonSuccess={(username) => {// Saved to the per-app membership. The SDK has already// transitioned to its in-frame done pane; the host decides// whether to advance onboarding now or wait for dismissal.console.log("claimed", username);}}onFail={(error) => {console.warn("username claim failed", error);}}/>);}
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
appId | string | optional | provider clientId | App scope. Falls back to the surrounding `ElvixProvider` clientId. |
appName | string | optional | provider appName | Display name used in copy. Falls back to the provider context. |
current | string | null | optional | membership value | Override the seeded value. Defaults to the username on the current per-app membership. |
methodUsername | boolean | optional | true | When false, the SDK renders a disabled pane explaining the feature is off and points the user at support. |
supportUrl | string | null | optional | provider value | Preferred contact route used by the disabled pane. |
supportEmail | string | null | optional | null | Mailto fallback used by the disabled pane when no supportUrl is set. |
onSuccess | (username: string) => void | optional | (none) | Fires after a successful claim and BEFORE the in-frame done pane. If the callback navigates or unmounts the SDK, the done pane is skipped (host wins). |
onFail | (error: string) => void | optional | (none) | Fires alongside the in-frame error pane. Notification-side hook only. |
onResult | (result: ElvixUsernameResult) => void | optional | (none) | Terminal callback for every attempt (success and failure). Mirrors the Spine ResponseDto shape. |
Username is per-app, not per-identity. Two apps can have a user with the same username pointing at different humans. Centralised identity fields (name, avatar, region) live on `ElvixIdentityForm` and the dedicated per-field components.
When the host app has username sign-in disabled (methodUsername=false), the widget renders a read-only pane and routes the user to supportUrl or supportEmail. Wire at least one of them on the provider so the disabled state is not a dead end.
Related
ElvixIdentityForm
Hosted profile editor: name, locale, timezone, pronouns, contact. Plugs straight into the elvix User record. In-frame edit → confirm → done lifecycle.
ReadAvatar
Centralized avatars, rendered by user id. `ElvixUserAvatar` shows ANY user’s photo from their id alone (no session, no membership) with a custom/OAuth/initials fallback and live cross-app updates. `ElvixAvatar` is the editable wizard that writes the user’s one global photo.
Read