SynqDocs
Guides

Avatars

Show the picture each person chose, and your own default avatar for everyone who hasn't chosen one.

Every app shows people somewhere: a menu in the corner, a profile page, a list of members. Synq keeps the picture each person chooses, and gives every person a seed your app draws its own default avatar from, so someone with no picture still looks like themselves, the same in every app of your brand.

A person's picture is only ever one they chose. Synq never writes a generated image into it: without a choice it is empty, and what shows instead is yours to decide.

Where a picture comes from

picture_source says, on the profile, the management API's users and the ID token:

picture_sourceThe picture is
noneNone. picture is null: show your own default avatar.
uploadOne the person uploaded.
linked:<provider>The picture of an account they signed in with, such as linked:telegram, copied into your brand's files.
urlA URL your app or your team set through the API (PATCH /me/v1/profile, or a user's picture in the management API).

An ID token or userinfo says only linked for a linked account's picture, unless the app also has the linked_accounts scope: which provider it came from would tell the app which accounts the person has elsewhere. The profile and the management API always name the provider.

Someone who signs up with Google, GitHub, X, Discord, Facebook, Telegram or Microsoft starts with that account's picture. Synq copies it into your brand's files on its media host, so picture never points at the provider: the provider never learns when your app shows it, and it never breaks when they move it. When the picture changes at the provider, their next sign-in with that account copies it again. Someone who signs up with a wallet, an email address or a passkey starts with none.

Where Synq keeps no pictures yet, the profile's picture_choices is false: a sign-up keeps the provider's own URL as its picture, and uploading or copying one answers storage_unavailable. Removing one works either way.

Every picture Synq keeps is checked and re-encoded as a WebP square of at most 256 × 256: PNG, JPEG, WebP and GIF are taken, SVG never.

Your own default

Each person has an avatar_seed: 22 characters, on their profile and, with the profile scope, in their ID token. It stays theirs for as long as their account lasts (a new email address or another wallet doesn't change it), it is different at every other brand, and nothing leads from it back to their sub. Draw anything from it: a pattern, a creature, a color.

Take Acme Guild, whose members sign in with Telegram or a Solana wallet. It draws each member without a picture as one of its own guild crests:

'use client'

import { defaultPick } from '@synqauth/js'
import { SynqProvider } from '@synqauth/react'

const CRESTS = ['fox', 'owl', 'wolf', 'stag', 'bear', 'hawk', 'boar', 'hare']

/** The member's crest: the same one in every Acme Guild app, picked by their seed. */
function crest(seed: string) {
  return `/crests/${defaultPick(seed, CRESTS)}.png`
}

export function Providers({ children }: { children: React.ReactNode }) {
  return <SynqProvider avatar={{ fallback: (seed) => crest(seed) }}>{children}</SynqProvider>
}

defaultPick picks by each crest's name, so the guild can add a crest without anyone else's changing: a ninth moves only about one member in nine, to it, and retiring one moves only the members who had it.

<SynqProvider avatar> sets it once, for every <Avatar>, <UserButton> and <AccountManager> under it. A component's own avatar prop overrides it. fallback answers an image's URL, or any element: an <svg> you draw from the seed, say.

<Avatar> shows, in order, the first there is:

  1. The person's picture, when its source is one of sources (all of them by default)
  2. Your fallback(seed, user)
  3. Your brand's own default for them (default_picture, below)
  4. Synq's own: Aura, a soft gradient, or Monogram, with their initials, when fallback is "monogram"

To show your own art even over a linked account's picture, and only pictures people uploaded to you, pass sources={['upload']}.

<Avatar user> draws anyone, not only who is signed in: an ID token's claims, or a user from the management API as it answers them (id, username), for a list of members. size is its width and height in pixels.

Without React, avatarOf(person) from @synqauth/js reads the same from any of those: the picture, its source, the seed, the initials and the brand's default. @synqauth/js draws Synq's two styles as SVG too: avatarSvg(seed), or avatarSvg(seed, { style: 'monogram', initials: initialsOf(person) }). In React Native, useAvatar() answers the same, with Synq's own as svg for react-native-svg's SvgXml.

A token issued before seeds existed has no avatar_seed: use sub in its place, as @synqauth/react does, until the person signs in again.

Letting people choose

AccountManager's profile shows the person's avatar with buttons to upload a picture, to use the picture of each account they linked ("Use my Telegram picture"), and to remove it. It offers only what your app shows (a linked account's picture only where sources takes it), and uploading or copying only where picture_choices is true. Build your own with useUser():

'use client'

import { Avatar, useLinkedAccounts, useUser } from '@synqauth/react'

export function PictureSettings() {
  const { profile, uploadPicture, setPictureFrom, removePicture } = useUser()
  const { data: accounts } = useLinkedAccounts()
  if (!profile) return null
  const telegram = accounts?.find(
    (account) => account.provider === 'telegram' && account.has_picture,
  )
  return (
    <>
      <Avatar size={80} />
      {profile.picture_choices && (
        <input
          type="file"
          accept="image/png,image/jpeg,image/webp,image/gif"
          onChange={(event) => {
            const file = event.target.files?.[0]
            if (file) void uploadPicture(file)
          }}
        />
      )}
      {profile.picture_choices && telegram && (
        <button type="button" onClick={() => void setPictureFrom(telegram.id)}>
          Use my Telegram picture
        </button>
      )}
      {profile.picture && (
        <button type="button" onClick={() => void removePicture()}>
          Remove picture
        </button>
      )}
    </>
  )
}

Each answers { data, error }, the profile as it is now. uploadPicture makes a large photo smaller in the browser first (at most 1024 pixels on its long side), then posts it to your route mount (<base>/account/picture), whose server sends it on: the bytes go from your server to Synq's storage, never through Synq's API, and Synq's storage needs no CORS rule for your site.

From the account API itself:

  1. Start an upload with the picture's content_type and exact content_length: at most 5 MiB and 8192 × 8192.
  2. PUT the bytes to the url it answers, with its headers and nothing of Synq's. The storage takes PUTs from Synq's own origins alone, so send them from your server.
  3. Choose it with { "file_id": … }. { "identity": … } uses a linked account's picture instead, where its identity has has_picture.

Remove it to show your default again. @synqauth/js's account client does all three: user.picture.upload(blob), .fromAccount(identityId) and .remove().

When it doesn't work:

  • file_rejected: the bytes aren't a picture Synq takes. reason says why.
  • picture_unavailable: the linked account had no picture at its last sign-in, its provider keeps pictures where Synq can't copy them from (Matrica), or Synq couldn't read it from the provider. Signing in with it again shows Synq its current picture.
  • upload_limit_reached: a person has at most 2 uploads waiting and 20 pictures kept.
  • rate_limited: a person uploads or copies at most 10 pictures an hour (rate limits).
  • storage_unavailable: pictures can't be uploaded or copied in this environment yet. Keep showing what the person has.

A set for your hosted pages

Your hosted pages show people too: the account chooser names who is signed in, with their avatar. Your app's code doesn't run there, so give your brand a set of its own default avatars instead: up to 24 images, on Pro and up (branding.default_avatars).

Acme Guild uploads its twelve crests as default_avatar files from the dashboard (the brand's Avatars page, several at once), or through the management API as for a logo: each is cut to a square around what draws the eye and kept at 256 × 256. Then each member without a picture sees one of them on the hosted pages, picked by their seed, and their profile and ID token name it as default_picture, so an app can show the same crest without drawing its own.

Each person keeps theirs as the set changes: an image you add goes to about one person in every n + 1 of a set of n, and only the people who had an image you remove (by its file's id) get another. Without a set, the hosted pages draw Synq's own: Aura, or Monogram with the theme's default_avatar_style (on the dashboard's Avatars page), to match what your apps draw. Synq's own styles are on every plan.

On a plan without the feature, uploading a default_avatar answers plan_feature_unavailable, naming the plan that has it. A brand that has a set and moves down keeps it: the theme lists it in default_avatars and names it in not_shown, the hosted pages draw Synq's own in its place, and default_picture is absent, until the plan has the feature again. Removing one works on any plan.

On this page