SynqDocs
Guides

Usernames

Let people choose a username at your brand, checked as they type, with free ones offered when theirs is taken.

A person can have one username at each brand: 3 to 64 lowercase letters, digits, dots, dashes and underscores, starting and ending with a letter or digit. Usernames are per brand, so the same name can belong to different people at two brands. A provider's handle becomes the username of an account that has none, when it is free, as the person signs up or adds that provider (adding ways to sign in).

Checking one

GET /me/v1/usernames/{username} on the brand's issuer answers whether the person could take it (available), why not (reason: format or taken), and, when it's taken, up to three suggestions: names like it, with a short number, that nobody at the brand has at the moment of the answer. Nothing is held for them, so saving one can still answer username_taken. Their own username counts as available.

From their wallet's name

Someone who signs in with a wallet may already have a name on Solana: a Seeker ID, such as ana.skr, which Solana Mobile's Seeker sets up with the phone. Synq offers it first when they pick a username, never as theirs until they choose it.

GET /me/v1/username-suggestions answers up to three suggestions, each a username with the on-chain name and the wallet it came from. A name is offered as its label and as itself (ana, then ana.skr), each only where it is a username nobody at the brand has. Synq reads the name the wallet chose for itself (its AllDomains main domain), on Solana's mainnet, from its own servers. It counts only while that wallet still owns the name. Nothing is held, and a name that changes hands later costs nothing, since it was only ever offered.

Say Acme Guild's members sign in with their Seekers. A new member whose phone's name is kai.skr opens Acme Guild's profile: the username field offers kai and kai.skr before they type. A member whose kai someone else took is offered kai.skr, then the names like what they typed.

It's on for every brand. Turn it off with wallet_name_usernames set to false, or the dashboard's Suggest wallet names as usernames in a brand's settings.

From React

useUsernameField() from @synqauth/react is the whole field: it starts from their username, lowercases what they type, holds it to the format on the spot, checks it 300ms after typing stops, drops answers for an older draft, and saves.

  • draft and setDraft(value): what's in the field; a suggestion they tap goes to setDraft too, and is checked again.
  • status: idle, checking, available, taken, format (it isn't a username) or same (it's theirs already).
  • code and message: what to say, by code: same, available, taken, or the format rule it breaks (too_short, too_long, characters, edges). The words are messages.usernameCodes on <SynqProvider messages>, in your app's language.
  • suggestions: the free ones to offer. Before they type, while they have no username, their wallets' names; when the one typed is taken, those first, then names like it.
  • save(): makes the draft their username, and saving while it does.

Acme Guild asks new members to pick a name for the guild's leaderboard:

GuildName.tsx
import { useUsernameField } from '@synqauth/react'

export function GuildName() {
  const field = useUsernameField()
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        void field.save()
      }}
    >
      <label>
        Your name in the guild
        <input value={field.draft} onChange={(event) => field.setDraft(event.target.value)} />
      </label>
      {field.message && <p role="status">{field.message}</p>}
      {field.suggestions.map((name) => (
        <button key={name} type="button" onClick={() => field.setDraft(name)}>
          @{name}
        </button>
      ))}
      <button type="submit" disabled={field.status !== 'available' || field.saving}>
        Save
      </button>
    </form>
  )
}

On this page