SynqDocs
Guides

Add an account panel

Drop one component into your header for sign-in, a first sign-in's welcome and the profile, in a popover on a laptop and a sheet on a phone.

<AccountPanel> from @synqauth/react is the account button at the top right of your app and the panel it opens. Signed out, it lists your brand's ways to sign in. Right after a first sign-in, it welcomes the person with the cards to set up their profile, once. After that, the same button opens their profile. It is a popover anchored under the button from 640px wide, and a bottom sheet below that.

The example below is Acme Guild, a community app on its own brand with a Solana wallet, Google, Telegram, X and emailed codes turned on. Its members pick a username, see their guild rank, keep several wallets and link Telegram for event reminders from the guild's bot.

Setting up

The panel uses the pieces the other guides set up:

  • @synqauth/nextjs with the account API on, and a first-party web app with own-UI sign-in on, so an emailed code and a wallet's signature finish in the panel.
  • Sign-in context on the app (sign_in_claims: true, Build your own sign-in panel), so the panel knows a first sign-in and marks the way this browser last used. Without it, every sign-in is greeted as a returning one, and nothing is marked.
  • <SynqWalletProvider> from @synqauth/solana/react inside <SynqProvider>, for a wallet's sign-in in the panel with one signature (Connected wallets). Without it, a wallet signs in on the hosted page.
'use client'

import { SynqProvider, type SynqSessionInfo } from '@synqauth/react'
import { SynqWalletProvider } from '@synqauth/solana/react'
import '@synqauth/react/styles.css'

export function Providers({
  session,
  children,
}: {
  session: SynqSessionInfo | null
  children: React.ReactNode
}) {
  return (
    <SynqProvider initialSession={session}>
      <SynqWalletProvider>{children}</SynqWalletProvider>
    </SynqProvider>
  )
}

The panel

'use client'

import { AccountPanel, useAccountPanelSection, useLink } from '@synqauth/react'

export function GuildHeader() {
  return (
    <header>
      <a href="/">Acme Guild</a>
      <AccountPanel
        methods={['wallet', 'google', 'telegram', 'x']}
        description="One profile for all your wallets."
        accountHref="/settings/account"
        onSignedOut={() => toast('Signed out.')}
      >
        <AccountPanel.Username description="Your name in the guild. Change it any time." />
        <GuildRankCard />
        <AccountPanel.Wallets
          extra={(wallet, { firstRun }) =>
            firstRun ? null : <WalletRank address={wallet.address} />
          }
        />
        <AccountPanel.Linked>
          <RemindersRow />
          <AccountPanel.LinkRow provider="x" description="Show your @handle on your profile." />
        </AccountPanel.Linked>
      </AccountPanel>
    </header>
  )
}

// The guild's own card, drawn as the panel's sections are. A first
// sign-in's onboarding keeps to what to set up, so it waits for the profile.
function GuildRankCard() {
  const { firstRun } = useAccountPanelSection()
  const rank = useGuildRank()
  if (firstRun || !rank) return null
  return (
    <AccountPanel.Card title="Guild rank" badge={`#${rank.place}`}>
      <p>{rank.points} points this season</p>
      <a href="/leaderboard">See the leaderboard</a>
    </AccountPanel.Card>
  )
}

// The guild's bot messages a member once they link Telegram.
function RemindersRow() {
  return (
    <AccountPanel.LinkRow
      provider="telegram"
      title="Event reminders"
      description="A message from the guild's bot before each event."
      linkedLine={(account) => `On · @${account.handle}`}
    />
  )
}

// Or a row of the guild's own for Telegram, with its own buttons, through
// useLink('telegram'): `provider` makes it stand for Telegram, so the
// profile doesn't list their Telegram account again below it.
function RemindersRowOfOurOwn() {
  const telegram = useLink('telegram')
  return (
    <AccountPanel.Row
      provider="telegram"
      title="Event reminders"
      line={telegram.status === 'linked' ? 'On' : 'A message before each event.'}
      action={
        telegram.status === 'linked' ? null : (
          <button onClick={() => void telegram.link()}>Connect</button>
        )
      }
    />
  )
}

The children are what the onboarding and the profile show, in source order: the panel's own sections, and your app's cards between them (GuildRankCard here). There is no order prop. With no children, the panel shows Username, Wallets (where your brand offers wallets or the person has one) and Linked, with a row for each provider your brand offers.

Your own cards get what the sections have:

  • useAccountPanelSection() answers firstRun (the onboarding rather than the profile), view, close and hold. hold(busy) keeps the panel open on a click outside while a prompt of the card's waits: useEffect(() => hold(busy), [hold, busy]). A link inside the panel closes it as it navigates; before a router.push of your own, call close({ navigating: true }), which takes ?panel=account out of the address in place rather than going Back.
  • AccountPanel.Card draws a card as the sections are: its title (a heading that names it), an optional badge beside it, and what you put in it.
  • AccountPanel.Row draws a row as a LinkRow is: an icon, a title, a line and an action. AccountPanel.Linked renders its children inside a list, so a row of your own there is an <li>, which AccountPanel.Row is. A row that stands for a provider (your own Telegram row, say) takes its provider, so the profile doesn't list that linked account again, read only.
  • A popover, select or tooltip your card renders into <body> (Radix, Headless UI) counts as inside the panel: pressing it leaves the panel open.

In a Server Component

@synqauth/react is a client module, and a Server Component can't reach into one with a dot: AccountPanel.Username fails there. Every part is also its own export, AccountPanelUsername, AccountPanelWallets, AccountPanelLinked, AccountPanelLinkRow, AccountPanelCard and AccountPanelRow, so a header that renders on the server takes those, with cards of its own rendered on the server between them. Only props that are data cross over: onSignedOut, keep as a function, extra, linkedLine and avatar.fallback are functions, so a header that needs them is a client component.

// app/(guild)/header.tsx: a Server Component
import {
  AccountPanel,
  AccountPanelCard,
  AccountPanelLinkRow,
  AccountPanelLinked,
  AccountPanelUsername,
  AccountPanelWallets,
} from '@synqauth/react'

export async function GuildHeader() {
  const season = await getSeason()
  return (
    <header>
      <a href="/">Acme Guild</a>
      <AccountPanel methods={['wallet', 'google', 'telegram', 'x']} accountHref="/settings/account">
        <AccountPanelUsername />
        <AccountPanelCard title="This season">
          <p>
            {season.name} ends {season.endsOn}.
          </p>
        </AccountPanelCard>
        <AccountPanelWallets />
        <AccountPanelLinked>
          <AccountPanelLinkRow provider="telegram" title="Event reminders" />
        </AccountPanelLinked>
      </AccountPanel>
    </header>
  )
}
PropWhat it does
methodsThe ways in that lead the panel, in this order, of those your brand offers the app: its first four by default. The rest go under More options, in the brand's order.
descriptionA line under the sign-in title, in your words.
accountHrefYour page with <AccountManager>, linked as Account settings under the profile.
onSignedOutCalled once the person signed out from the panel, which stays on the page: your toast.
urlParamThe query parameter that mirrors the panel being open, ?panel=account by default; null for none.
keepSmall state of your app's (at most 4 KB of JSON), or a function the tap calls for it, to have back after a sign-in that leaves the page: useRedirectResult().kept.
moment and sparksWhether a sign-in plays the avatar's moment, yes by default, and how many embers rise, 6 by default.
avatarHow avatars fall back and which pictures show (Avatars): Acme Guild passes its own art as avatar={{ fallback: (seed) => <GuildCrest seed={seed} /> }}.
containerWhere the panel renders: document.body by default, so no ancestor's transform, filter or overflow clips it; null renders it beside its button.
classNameAdded to the button's wrapper, and nothing else: a responsive hidden md:inline-flex hides the button, not the panel.
panelClassNameAdded to the panel's layer, the full-window element that holds the dialog: where theme variables scoped to the panel go, since it renders outside your header.
unstyledSynq's look, or the same elements, roles and labels with no Synq class.

Signing in

The panel reads your brand's methods with useSignInMethods(), so a way you turn on or off in the dashboard shows up or goes away with no deploy. The way this browser last used is marked Last used, and lifted out of More options when it was there, so it is always in sight.

Each way finishes where it can:

  • A provider (Google, X, Telegram…) opens in a popup on a laptop, inside the tap, and the page carries on once the person finishes there (Sign in in a popup). On a phone, in another app's built-in browser, or where the browser blocks the popup, it is a redirect: the page leaves and comes back with ?panel=account, so the panel opens again on its next view. Google is left off inside other apps' built-in browsers, which it refuses.
  • A wallet signs in with one signature, in place, through the wallet layer: the connected wallet's address leads the button, with Use another wallet to pick another; with none connected, the panel lists the browser's wallets that can sign in.
  • An emailed code or a password opens its form in the panel, where own-UI sign-in is on; anything else goes to the hosted page.

While a sign-in is under way, its button says what it waits on (Finish in the Google window, Approve in Phantom, Opening Google…) with a Cancel under it, and the other ways dim. A closed popup, a declined signature or the way back from your brand's page (access_denied, which the page already explained) just puts the panel back at rest. Any other failure says so under the way it was for, a redirect's too once the page is back. If the session ends while the panel is open (it expired, say), the panel goes back to the ways in with "You were signed out. Sign in again." Cancel resets the panel; a provider's popup that already reached your brand's issuer is cut off from the page by the provider's opener policy, so the person closes it.

The moment, the welcome and the profile

The moment a sign-in lands, a ring sweeps around the person's avatar and a few embers rise off it: <AvatarMoment>, which plays once per sign-in and never on a page load. A first sign-in (useSignInEvent().isNewUser) opens the onboarding: "You're in", the cards, each of which saves itself and can be skipped, and Done. It shows once: closing the panel tells your server the page heard of the sign-in. A returning sign-in is greeted, and the panel puts itself away after a moment unless the person is using it. Linking a provider and confirming it's them aren't sign-ins the page hears of: the person signed in is the same, so the onboarding or the profile carries on where it was.

The profile shows their picture, their name, and under it their username, or how this session signed in ("Signed in with Google", or the wallet's address, from the sign-in context) when their username is the name shown, or else their email, with Edit for their name and username and Change picture for your app's default, an upload or a linked account's picture (Usernames, Avatars), then the cards, and Sign out. Signing out ends the session at the brand from your server and the page stays where it is (Sign out): the connected wallet stays connected, and onSignedOut runs.

The sections each take a title:

  • AccountPanel.Username: the username card of the onboarding, with free names checked as they type and three suggestions for a taken one. Its description is a line under the field while there's nothing to say about the name typed: what the username is for, in your words.
  • AccountPanel.Wallets: the profile's wallets, marked Connected, Signed in with this and Primary; Connect with no signature; a nudge to add the connected wallet when it isn't on the profile; Add a wallet with one signature; and in the profile, a menu to make one primary, rename, copy or remove it. Removing one asks first. Adding and removing a way in want a sign-in from the last 5 minutes: older than that, the card asks Confirm it's you, which takes one signature from a wallet on their profile where this browser has one, or else your brand's sign-in again in a popup (a redirect on a phone, which comes back into the panel), then goes on with the change. Remove is off only for their last way in, of every kind: a wallet beside a Google account can go. Signed in with this is the ID token's word where sign-in context is on, and otherwise only for a wallet sign-in this tab made. extra(wallet, { firstRun }) adds your own line under each.
  • AccountPanel.Linked: its rows, and in the profile, each other linked account, read only.
  • AccountPanel.LinkRow: one provider to link, with its provider, title, description and linkedLine, through useLink.

Its look

Synq's look comes from @synqauth/react/styles.css, themed with the same --synq-* variables as the other components, on .synq:

.synq {
  --synq-color-primary: #7c5cff;
  --synq-color-danger: #ff6b5a;
  --synq-font-display: 'Acme Display', sans-serif;
  /* The moment's ring and embers. */
  --synq-moment-1: #7c5cff;
  --synq-moment-2: #ff8a5c;
  --synq-moment-3: #ffd166;
}

It follows the same variables as <AccountManager>: cards take --synq-color-surface and --synq-color-border on --synq-color-background, cards and rows round to --synq-radius, and fields, menus and tiles to --synq-radius-control. Its own:

VariableWhat it sets
--synq-panel-widthThe popover's width, 400px. It sits inside the window at any width, wherever its button is.
--synq-panel-zWhat it sits above, 1000.
--synq-radius-panelThe dialog's corners: --synq-radius × 1.5.
--synq-glyph-filterTurns the issuer's white provider glyphs dark on a light panel (invert(1)); a panel that is always dark sets it to none.
--synq-icon-plateThe plate behind a provider's full-color artwork, such as Google's: white.
--synq-font-displayIts titles and greetings.
--synq-font-monoWallet addresses.
--synq-moment-1 to 3The moment's ring and embers.

Text sizes, in the panel and in every other component, are a scale: --synq-text-xs (13px, only for incidental details such as "Last used"), --synq-text-sm (14px: labels, a row's second line, badges), --synq-text-base (16px: body text, rows, fields and buttons; --synq-font-size follows it) and --synq-text-lg to --synq-text-3xl for titles. From 1024px wide every step goes up one (14, 15, 17…). They're in px, so a page whose root font size is smaller can't shrink them. Set them to retheme; keep them at 13px or more.

A button that is off, in the panel and in every other component, is a flat grey with its own edge and words, never its colour faded: --synq-color-disabled (its fill), --synq-color-disabled-border (its edge, 3:1 against the surfaces) and --synq-color-disabled-text (its words, 4.5:1 on the fill), with light and dark defaults. Set all three together when you change them.

The panel renders into document.body, outside your header, so set its theme on .synq (every Synq element carries it) or on panelClassName. Every text is 13px or larger, fields are 16px, every control is at least 44px, and every animation has a reduced-motion version: the ring is simply there, with no embers. The words come from <SynqProvider messages>, English for any left out.

Headless

useAccountPanel() is the same panel's state and behavior for one of your own: spread triggerProps on your button and panelProps on your dialog, and it keeps the focus inside, closes on Escape and a click outside (by React's tree, so your portaled layers are inside), mirrors itself in the address and gives the focus back to the button. It moves your dialog only with useAccountPanel({ animate: true }), which plays Synq's open and close; otherwise the motion is yours, and present is open.

'use client'

import { useAccountPanel, useSession, useSignInMethods } from '@synqauth/react'

export function GuildAccount() {
  const panel = useAccountPanel()
  const { user } = useSession()
  const { data: methods } = useSignInMethods()
  return (
    <>
      <button {...panel.triggerProps}>{user ? 'Profile' : 'Sign in'}</button>
      {panel.open && (
        <div {...panel.panelProps}>
          <h2 id={panel.titleId}>
            {panel.view === 'onboarding' ? 'Welcome to the guild' : user ? 'Profile' : 'Sign in'}
          </h2>
          {panel.view === 'sign-in' &&
            methods
              ?.filter((m) => !m.in_place)
              .map((m) => (
                <button key={m.id} onClick={() => panel.signIn(m.id)}>
                  Continue with {m.name}
                </button>
              ))}
          {panel.view === 'progress' && <button onClick={panel.cancel}>Cancel</button>}
          {user && <button onClick={() => panel.signOut()}>Sign out</button>}
        </div>
      )}
    </>
  )
}

view is sign-in, progress, onboarding or profile; layout is popover or sheet; pending is the sign-in under way, with its display (popup, redirect or in-place); problem is why the last one failed, a redirect's too, and problemMethod the way it was for; signedOut is a session that ended while it was open; event is the sign-in being welcomed; close({ navigating: true }) closes it before a navigation of yours. <AvatarMoment event={panel.event} /> draws the moment in a panel of your own.

Another chain's wallets

The panel reaches wallets only through a wallet layer, WalletLayerProvider, which <SynqWalletProvider> fills for Solana. A wallet layer of your own passes its value: the connected wallet, the browser's wallets, and signIn, add, move, connect and reauthenticate, each answering { data, error }.

On this page