Profile

Who is signed in, the XP bar, and how a profile page is put together from the features you already have.

A fan's own page: who they are, how far they have got, what they own and what they have done.

There is no profile component in the SDK. A profile is a page you compose from hooks that belong to other features. This page says which hook feeds which part, and covers the two reads that live nowhere else: who is signed in, and the XP bar.

Signed-in fans only

A profile is personal. Render nothing but a sign-in control until there is a session.

import { useFanbase } from '@xborglabs/fanbase-react'

function ProfileRoute() {
  const { state } = useFanbase()

  if (!state.ready) return <ProfileSkeleton />
  if (!state.session) return <SignInButton />
  return <ProfilePage />
}

Do the check here, above everything else. Some of the reads further down answer a signed-out visitor with zeros instead of an error, and a profile full of zeros looks like a real, empty account.

Who is signed in

The session holds tokens. It does not say who the fan is. useViewer() does.

import { formatViewerHandle, resolveViewerDisplayName, useViewer } from '@xborglabs/fanbase-react'

const { data: viewer } = useViewer()

const name = viewer ? resolveViewerDisplayName(viewer) : ''
const handle = viewer?.profile?.handle
FieldUse it for
userIdIdentity. Highlighting the fan's own row on a leaderboard.
profile.handleLinking to their public profile. Keep the whole handle, including the # and digits.
profile.displayNameTheir name. It can be missing.
createdAt"Joined in March"

resolveViewerDisplayName(viewer) always returns something to show: the display name, or the handle without its digits, or a short id as a last resort. formatViewerHandle(handle) strips the digits for display. Route with the full handle and show the formatted one.

Use this for identity, not membership. useViewer works for every signed-in fan. useMembership only works for a fan who has joined the community, and errors for one who has not. A name or a user id read from membership disappears for exactly the fans you most want to welcome.

There is no profile picture on the viewer. That is a personalisation, set per community.

Switching accounts

When a fan logs out and another logs in, the name updates on its own. Everything else on the page is cached by whether someone is signed in, not by who. After an account switch in the same tab, clear the cache before you render the profile:

const { meta } = useFanbase()
meta.queryClient.removeQueries()

The header

PartReadNotes
NameuseViewer() and resolveViewerDisplayNameAbove
Picture and borderuseEquippedPersonalization()The border sits on top of the picture. No picture: the first letter of the name. Personalisation.
Tier badgeuseMembership()Errors for a fan who has not joined. Show "no tier" and do not retry.
XP baruseCommunityXP() and resolveCommunityXpProgressBelow
AvatarAvatar.ProviderRendering an avatar

A fan can also equip a background. Where it goes is your call. It is designed to sit behind the whole page, not in a tile.

The XP bar

useCommunityXP() returns the fan's XP and the levels either side of it. resolveCommunityXpProgress turns that into a bar.

import { resolveCommunityXpProgress, useCommunityXP } from '@xborglabs/fanbase-react'

function XpBar() {
  const { data: xp } = useCommunityXP()
  if (!xp) return null

  const bar = resolveCommunityXpProgress(xp)
  if (!bar.hasLevels) return null

  return (
    <>
      <progress max={100} value={bar.percent} />
      <span>
        {bar.balance.toLocaleString()}
        {bar.target !== null ? ` / ${bar.target.toLocaleString()}` : ''}
      </span>
      <span>{xp.current?.name ?? `Level ${bar.level}`}</span>
    </>
  )
}
How full is the bar?Try it
The fan's XP
450
Community
What the SDK draws64%
450 / 700Level 2 to 3
A bar that restarts at each level38%
Not what the SDK draws. It empties every time the fan levels up, which reads as losing progress.
Levels start at 100, 300, 700 and 1,500 XP. Example ladder.
FieldMeans
percentHow full the bar is, 0 to 100
balanceThe fan's XP
targetThe XP the next level starts at. null at the top level.
level, nextLevelThe level they are on and the one ahead
isMaxLevelThey are on the last level
hasLevelsThe community has levels at all

Use the helper and not your own sum, because the bar has three cases that are easy to get wrong.

It fills from zero. A level's target is the total XP at which it starts, not the distance from the level before. A fan with 450 XP heading for a level at 1,000 is 45% of the way, and the bar shows 45%. It does not restart from empty at each level.

The top level is full. At the last level the bar is 100% and there is no target to print. Show the balance alone.

No levels means no bar. A community that has not set up levels has nothing to draw. Hide it.

A level here is an XP threshold. It has nothing to do with a membership tier, although both get called a rank. The leaderboard model lists the numbers that get confused.

One avatar provider for the whole page

If the profile shows an avatar and has an inventory tab, put one Avatar.Provider above both and keep it mounted when the fan changes tab.

<Avatar.Provider>
  <aside>
    <AvatarStage />
    <ProfileHeader />
  </aside>
  <main>
    <ProfileTabs value={tab} onChange={setTab} />
    {tab === 'overview' && <OverviewTab />}
    {tab === 'inventory' && <InventoryTab />}
    {tab === 'personalization' && <PersonalizationTab />}
    {tab === 'history' && <HistoryTab />}
  </main>
  <AvatarSaveBar />
</Avatar.Provider>

The provider holds the outfit the fan is trying on. With one provider, an item equipped in the inventory tab appears on the avatar beside it before they save. With one per tab, the avatar would not move until the page reloaded.

Do not mount it inside a tab, and do not key it by tab. Switching tabs then costs nothing.

The tabs

TabShow it whenCovered in
OverviewAlwaysBelow
InventoryThe community uses avatarsThe avatar editor
PersonalizationThe community uses personalisationPersonalisation
HistoryAlwaysBelow

useCommunity().data has the two switches: hasAvatar and hasPersonalizations. Treat a missing value as on, and hide the tab only when it is false.

Overview

CardReadNotes
RankuseCommunityXP().data.leaderboardRank0 or missing means unranked
Quests completeduseQuestStats()A total, and a day-by-day count for a chart
Events joineduseQuestEventsParticipatedCount()Events
Items owneduseAvatarItems({ onlyOwned: true, limit: 1 }).totalAsking for one item reads the count without the list
Inventory previewuseAvatarItems({ limit: 4 }).itemsFour items and a link to the tab
Recent questsusePaginatedQuestHistory({ page: 1, limit: 2 })Two rows and a link to the tab
Linked accountsuseLinkedSocials()Linking accounts

Quest stats

const { data: stats } = useQuestStats()
// stats.questsCompleted         all time
// stats.questsCompletedDaily    [{ date: '2026-11-05', questsCompleted: 2 }, ...]

questsCompleted is the all-time number. questsCompletedDaily is one row per day for the last seven days, ending today, with zeros filled in, so it can go straight into a chart. Pass a number to useQuestStats(14) for a different window.

Use this for the counter. The history list also has a total, but that one includes failed quests.

History

Every quest the fan has finished, a page at a time.

import { usePaginatedQuestHistory } from '@xborglabs/fanbase-react'

const { data } = usePaginatedQuestHistory({ page, limit: 5 })

const rows = data?.results ?? []
const hasNext = data ? data.offset + data.results.length < data.total : false

A row is a quest, with completedAt added. History holds quests that were completed and quests that failed. Say which on each row.

WantDo
The next pagepage + 1 while hasNext is true. Pages start at 1.
Only quests with a reward still to claimfilters: { 'rewards.rewardAllocations.claimStatus': 'ALLOCATED' }
To claim from a rowWrap the row in Quest.Provider with fetchRewards. Rewards and claims.

Grouping the rows by date reads well: today, the last week, the last month, older. completedAt is all you need for it.

Another fan's profile

A public profile is a different page. It works signed out, and it is read-only.

The SDK covers its avatar: usePublicAvatar({ handle }). Link to it from a leaderboard row with row.user.handle.

Hooks

HookReturns
useViewer()Who is signed in
useCommunityXP()XP, the current and next level, the fan's rank
useQuestStats(days?)Quests completed, all time and per day
usePaginatedQuestHistory({ page, limit, filters? })Finished quests, a page at a time
useQuestEventsParticipatedCount()Events joined
useEquippedPersonalization()Picture, border and background

Full signatures in Hooks.

Checklist

  • Signed out, the page shows a sign-in control and nothing else
  • The name renders for a fan who has not joined the community
  • Nothing reads the fan's name or id from membership
  • A fan with no tier sees "no tier", not an error
  • The XP bar comes from resolveCommunityXpProgress, is full at the top level, and is hidden when there are no levels
  • Equipping an item in the inventory tab changes the avatar before saving
  • The quests counter reads useQuestStats, not the history total
  • History stops paging at the end

On this page