Reference

Hooks

Every hook in the SDK, grouped by feature, with what each one is for.

The whole hook surface, grouped by feature. Each group links to the guide that uses it.

Every hook needs FanbaseProvider above it. Hooks named after a compound, like useQuest or useBattlepass, also need that compound's provider, and throw outside one.

All of them are react-query under your own client, so SDK queries show up in devtools alongside yours.

None of them take a communityId you have to supply. Anything scoped to a community resolves it from the slug on FanbaseProvider.

useFanbase()

Session, config and the authenticated HTTP client. Available anywhere under FanbaseProvider.

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

const { state, actions, meta } = useFanbase()

state

FieldNotes
readyThe provider has finished restoring any stored session. Gate on this.
session{ accessToken, refreshToken } when signed in, else null.
configThe resolved configuration.

actions

ActionNotes
loginWithToken({ provider, token })Exchanges an OAuth callback token. The provider has to match the one that started sign-in.
bind({ token, accountType })Redeems a link token. Never touches the session. Linking accounts.
refreshSession()Refreshes the tokens. Rarely needed: the client does it on a 401.
logout()Clears the adapter and the in-memory session.

meta

FieldNotes
httpAuthenticated client. Tenant header, Bearer token and 401 retry handled. For endpoints without a hook.
queryClientThe react-query client the SDK uses.

Three narrower hooks read one piece each: useFanbaseSession() for the session, useFanbaseConfig() for the tenant, slug and app id, and useFanbaseHttp() for the client.

useQuest()

Quest state and actions inside a Quest.Provider.

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

const { state, actions } = useQuest()

state

FieldNotes
questThe quest, including template.name, template.args and rewards.
rewardsThe fan's reward allocations, when the provider has fetchRewards and there is a session.
machineThe machine's full verdict. machine.reason is why the fan cannot act.
canSubmitWhether the fan can act now.
canClaimWhether a reward is waiting.
buttonLabelThe label for the current state, already resolved.
disabledReasonLabelWhy the fan cannot act, in a sentence. Worth showing.

actions

ActionNotes
submit(payload?)A payload for typed templates, none for empty-body ones.
accept(payload?)The accept step, where a template has one.
complete(payload?)The complete step, where a template has one.
claimAllAllocated(payload?)Claims every waiting reward. What Quest.Claim does.
claimFirstAllocated(payload?)Claims the first waiting reward.
claim(rewardAllocationId, payload?)Claims one named allocation.
refetch()Refetches the quest.

Quests

Quests

HookFor
useQuestsList()The quest list. One request for the page, never one per card. Works signed out.
useQuest()State and actions inside Quest.Provider. Above.
useQuestDetail()One quest, outside Quest.Provider
useQuestResults(questId)Entry counts per option for a poll or a prediction
useQuestHistory()The fan's finished quests, completed and failed, as one page
usePaginatedQuestHistory({ page, limit, filters? })The same, a page at a time. Profile.
useQuestStats(days?)The fan's quests completed: all time, and per day for a chart. Profile.
useQuestStreak()The fan's streak on one quest
useQuestTranslate()A translate function for Quests.* display strings

Events

Events

HookFor
useQuestEvent()State and actions inside QuestEvent.Provider
useQuestEvents({ buckets })The community's events, filtered into sections and sorted
useFeaturedQuestEvents({ communityId })Featured events still running. Pass the community id: it is not scoped on its own.
useQuestEventDetail(eventId)One event with its quests, outside the provider
useQuestEventLeaderboard({ eventId, page, limit })One page of an event's board. Signed in only.
useQuestEventViewerRank({ eventId })The fan's rank in an event
useQuestEventRewardAllocations({ eventId })The fan's rewards from a completed event
useQuestEventQuestsCompleted({ eventId })The community's count on a collaborative event
useJoinQuestEvent()Joins an event, outside the provider
useSyncQuestEvent()Refreshes a score, outside the provider
useClaimQuestEventReward()Claims one reward, outside the provider
useQuestEventsParticipatedCount()How many events the fan has joined, for a profile

Battlepass

Battlepass

HookFor
useBattlepass()State and actions inside Battlepass.Provider
useBattlepassLane()The lane a Battlepass.Lane is rendering
useBattlepassTier()The slot a Battlepass.Tier is rendering, with its gate
useBattlepassProgress()The live season and its tiers, outside the provider
useBattlepassSeasons()Every season, for a season switcher
useBattlepassSeason(seasonId)One season with its tiers
useCompleteTier()Completes a tier that takes an input
useClaimAllTiers(slots)Claims every tier that can settle on its own, and hands back the rest

Store

Store

HookFor
useStore()State and actions inside Store.Provider
useStoreListing()One listing and its gate, inside Store.Listing
useStoreListings()Listings, outside the provider
useStoreTags()Tags, for filter chips
useStoreCarousel()Featured carousel slides
useSpendableResources()The fan's balances, one per currency
useResourceTypes()Currency names, public, for pricing signed-out fans
usePurchaseListing()Buys a listing, outside the compound
usePurchases()The fan's store purchase history
usePurchase(purchaseId, { refetchInterval })One purchase, pollable, for a Shopify order in progress

Leaderboard

Leaderboard

HookFor
useLeaderboard()State and actions inside Leaderboard.Provider
useLeaderboardList({ kind, page, limit })One page of a board, outside the provider
useLeaderboardViewerRank({ kind })The signed-in fan's own row, outside the provider

Newsfeed

Newsfeed. There is no provider: these are the whole surface.

HookFor
useNewsfeedFeed(filters)The feed, as an infinite query
useNewsfeedPost({ newsId })One post
useNewsfeedPublishers()Publishers, for filter chips
useNewsfeedReactionTypes()The community's reaction emoji
useReactToPost()Reacts to a post. Optimistic.
useNewsfeedComments({ newsId, sort })A post's comments, as an infinite query
useNewsfeedCommentReplies({ newsId, commentId })More replies under one comment
usePostComment()Posts a comment or a reply. Optimistic.
useUpdateComment()Edits the fan's own comment
useDeleteComment()Deletes the fan's own comment
useCommentVote()Votes on a comment. Optimistic.
useReactToComment()Reacts to a comment. Optimistic.

Prizes and inventory

Prizes and inventory

HookFor
usePrizes({ ownedOnly })Prizes in the community, or the ones this fan owns
usePrize(prizeId)One prize, with the details it asks for
useLootboxes({ lootboxIds })A loot box's possible items, for the reveal
useClaimLootbox()Sends a won prize's details. Refuses unless it is claimable.
useInventoryItem({ communityKey, itemId })One inventory item the fan holds
usePersonalizations({ ownedOnly, kind })Cosmetics, filtered by kind
useEquippedPersonalization()What the fan is wearing now
useBatchEquipPersonalizations()Equips a whole draft at once
useEquipPersonalization()Equips one
useUnequipPersonalization()Takes one off

Avatars

Avatars

HookFor
useAvatar()The draft and its actions inside Avatar.Provider
useAvatarSlots({ userId? })Slots without the draft. With userId, another fan's.
useAvatarItems({ slotId, onlyOwned, rarity, page, limit })One page of the item grid
useAvatarItem({ itemId })One item
useAllocateAvatarSlots()Equips in one tap and saves at once, outside the editor
usePublicAvatar({ handle })Another fan's avatar, as 2D layers
useAvatarSceneConfig()The community's 3D scene settings
useAvatar3D()Camera and capture state inside Avatar3D.Provider. From @xborglabs/fanbase-react/avatar-3d.

Profile

Profile

HookFor
useViewer()Who is signed in: id, handle, display name. Works for a fan who has not joined.

The rest of a profile page is hooks from other groups: useCommunityXP, useQuestStats, usePaginatedQuestHistory, useEquippedPersonalization, useLinkedSocials.

Linking accounts

Linking accounts

HookFor
useBind()Redeems a link token on your callback page
useLinkedSocials()The fan's linked accounts, with expiry dates. Feeds authProfile.

Community and membership

Membership

HookFor
useCommunity()The community, resolved from your slug
useResolvedCommunityId()Just its id, for writes that need one
useMembership()The fan's membership. Errors for a non-member: treat that as rank 0. For the fan's id or name use useViewer().
useMembershipTiers()The community's tiers, lowest rank first
useCommunityXP()The fan's XP and level. Always XP, whichever leaderboard is on screen. Draw the bar with resolveCommunityXpProgress.

Outside the hooks

Every read also has a prepare…Options factory and every write a prepare…Mutation, for a server-side prefetch or a query client you manage yourself. Each feature exports its query keys, like FANBASE_STORE_KEYS, and an invalidateFanbase…Queries function. You rarely need them: every write already refreshes what it touched.

On this page