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 .
Session, config and the authenticated HTTP client. Available anywhere under FanbaseProvider.
import { useFanbase } from '@xborglabs/fanbase-react'
const { state , actions , meta } = useFanbase ()
Field Notes readyThe provider has finished restoring any stored session. Gate on this. session{ accessToken, refreshToken } when signed in, else null.configThe resolved configuration.
Action Notes 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.
Field Notes 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.
Quest state and actions inside a Quest.Provider.
import { useQuest } from '@xborglabs/fanbase-react'
const { state , actions } = useQuest ()
Field Notes 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.
Action Notes 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
Hook For 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
Hook For 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
Hook For 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
Hook For 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
Hook For 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 . There is no provider: these are the whole surface.
Hook For 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
Hook For 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
Hook For 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
Hook For 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
Hook For useBind()Redeems a link token on your callback page useLinkedSocials()The fan's linked accounts, with expiry dates. Feeds authProfile.
Membership
Hook For 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.
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.