Components
ElvixUsername

ElvixUsername

Username claim widget with availability check, reserved-word ban, and validation rules baked in. Per-app membership, debounced live check.

Pick a name other people on this app can use to find you.

  • 4 to 30 characters
  • lowercase letters, digits, dot, underscore
  • start with a letter, end with a letter or digit
  • no two specials in a row, no reserved words
app/account/username-pane.tsx
"use client";
import { ElvixUsername } from "@elvix.is/sdk/react";
export function UsernamePane() {
return (
<ElvixUsername
onSuccess={(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

PropTypeRequiredDefaultDescription
appIdstringoptionalprovider clientIdApp scope. Falls back to the surrounding `ElvixProvider` clientId.
appNamestringoptionalprovider appNameDisplay name used in copy. Falls back to the provider context.
currentstring | nulloptionalmembership valueOverride the seeded value. Defaults to the username on the current per-app membership.
methodUsernamebooleanoptionaltrueWhen false, the SDK renders a disabled pane explaining the feature is off and points the user at support.
supportUrlstring | nulloptionalprovider valuePreferred contact route used by the disabled pane.
supportEmailstring | nulloptionalnullMailto fallback used by the disabled pane when no supportUrl is set.
onSuccess(username: string) => voidoptional(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) => voidoptional(none)Fires alongside the in-frame error pane. Notification-side hook only.
onResult(result: ElvixUsernameResult) => voidoptional(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