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| Field | Use it for |
|---|---|
userId | Identity. Highlighting the fan's own row on a leaderboard. |
profile.handle | Linking to their public profile. Keep the whole handle, including the # and digits. |
profile.displayName | Their 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
| Part | Read | Notes |
|---|---|---|
| Name | useViewer() and resolveViewerDisplayName | Above |
| Picture and border | useEquippedPersonalization() | The border sits on top of the picture. No picture: the first letter of the name. Personalisation. |
| Tier badge | useMembership() | Errors for a fan who has not joined. Show "no tier" and do not retry. |
| XP bar | useCommunityXP() and resolveCommunityXpProgress | Below |
| Avatar | Avatar.Provider | Rendering 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>
</>
)
}| Field | Means |
|---|---|
percent | How full the bar is, 0 to 100 |
balance | The fan's XP |
target | The XP the next level starts at. null at the top level. |
level, nextLevel | The level they are on and the one ahead |
isMaxLevel | They are on the last level |
hasLevels | The 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
| Tab | Show it when | Covered in |
|---|---|---|
| Overview | Always | Below |
| Inventory | The community uses avatars | The avatar editor |
| Personalization | The community uses personalisation | Personalisation |
| History | Always | Below |
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
| Card | Read | Notes |
|---|---|---|
| Rank | useCommunityXP().data.leaderboardRank | 0 or missing means unranked |
| Quests completed | useQuestStats() | A total, and a day-by-day count for a chart |
| Events joined | useQuestEventsParticipatedCount() | Events |
| Items owned | useAvatarItems({ onlyOwned: true, limit: 1 }).total | Asking for one item reads the count without the list |
| Inventory preview | useAvatarItems({ limit: 4 }).items | Four items and a link to the tab |
| Recent quests | usePaginatedQuestHistory({ page: 1, limit: 2 }) | Two rows and a link to the tab |
| Linked accounts | useLinkedSocials() | 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 : falseA row is a quest, with completedAt added. History holds quests that were completed and quests that failed. Say which on each row.
| Want | Do |
|---|---|
| The next page | page + 1 while hasNext is true. Pages start at 1. |
| Only quests with a reward still to claim | filters: { 'rewards.rewardAllocations.claimStatus': 'ALLOCATED' } |
| To claim from a row | Wrap 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
| Hook | Returns |
|---|---|
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