Quest detail
One view that handles every quest type.
The main build, and the one page worth reading twice.
The shape
import { Quest } from '@xborglabs/fanbase-react'
export function QuestDetailPage({ questId }) {
const profile = useFanProfile()
return (
<Quest.Provider
questId={questId}
authProfile={{ socials: profile?.socials, wallets: profile?.wallets }}
fetchRewards
>
<Quest.Frame>
<QuestBody />
</Quest.Frame>
</Quest.Provider>
)
}Quest.Provider loads the quest, runs the state machine and exposes both through useQuest(). Quest.Frame wraps your UI. Everything inside is yours.
fetchRewards is a flag that asks the provider to load the fan's reward allocations, which is what tells the claim button a reward is waiting. It is off by default. Keep it on here and off on the list. Rewards and claims.
Passing the fan profile
authProfile is how the machine learns what the fan has linked.
Leave it out and the machine has to assume nothing is linked, so every social-gated and wallet-gated quest stays disabled with no obvious cause. It looks like a bug in the machine and it is a missing prop.
const { data: socials = [] } = useLinkedSocials()
authProfile={{ socials, wallets: profile?.wallets }}Take the socials from useLinkedSocials, not the profile. The profile leaves out expiry dates, so an expired Twitch link would look fine to the machine and the fan could never tell why the quest will not open. See Fan profile.
Seeding from the list row
You have the row from the list already, and rendering a title instantly beats a spinner.
Pass it as the quest prop and let the provider own it from there:
<Quest.Provider questId={questId} quest={listRow} …>Do not copy the row into your own useState and feed that in. It is the natural thing to reach for and it pins the page: your state never updates, so after a submit the status, the button label and the CTA all stay where they were. It reads as a state management bug in your own code and it is this.
If you need the fresh value after an action, take it from state.quest inside the provider rather than from your copy.
Not confirmed yet. A trial saw the page stay pinned even with the row passed straight through and nothing mirrored. We have not reproduced it, so we cannot say whether seeding pins the page or only the mirrored version does.
If your page stops updating after a submit and you are already doing the above,
drop the quest prop. The provider fetches the quest itself and the page updates.
It costs one extra GET /v1/quests/{questId} and the instant title render.
Reading state
const { state, actions } = useQuest()
state.quest // the quest
state.quest.template.name // which template
state.quest.template.args // template settings from the admin panel
state.buttonLabel // label for the current state
state.canSubmit // can the fan act
state.canClaim // is a reward waiting
state.disabledReasonLabel // why not, in readable languageRender those. Do not recompute them.
disabledReasonLabel is worth surfacing rather than hiding. “Link your Discord account to start this quest” turns a dead button into a next step, and the machine has already written the sentence.
Guard it on the way out, though. Some reasons still arrive with an unsubstituted
{quest} token in them, and You need to log in to start this {quest}. is worse
in front of a fan than no message at all:
function reason(label) {
if (!label) return null
return label.includes('{') ? null : label
}Dropping the message and leaving the button disabled is the safe fallback. If you would rather keep the sentence, substitute the quest title in yourself rather than passing the token through.
The requirement router
The one branch you write. Resolve the template name to its family, render the input, submit accordingly.
Branch on the family, never on template.name directly. The name that arrives is a
wire value like basic.auto-complete, and the families are a grouping you map it into
with familyOf, a short function you own. Quest templates has it in full.
Do not use getApiType for this. It returns the submit path, accept or complete,
not the family, so a switch on it never matches 'poll' and every quest silently goes
to your default branch.
import { familyOf } from './quest-families' // see Quest templates
function QuestBody() {
const { state, actions } = useQuest()
const template = state.quest?.template
if (!template) return null
switch (familyOf(template.name)) {
case 'poll':
return <PollInput args={template.args} onSubmit={actions.submit} />
case 'text':
return <TextInput args={template.args} onSubmit={actions.submit} />
case 'prediction':
return <PredictionInput args={template.args} onSubmit={actions.submit} />
case 'quiz':
return <QuizInput args={template.args} onSubmit={actions.submit} />
case 'image':
return <ImageUpload args={template.args} onSubmit={actions.submit} />
case 'visit':
return <VisitLink args={template.args} />
case 'bind':
return <BindAccount args={template.args} />
default:
return <Quest.Submit asChild><button>{state.buttonLabel}</button></Quest.Submit>
}
}Two families, two submit paths:
Typed templates carry a payload. Call actions.submit(payload) with the shape the template expects. Do not use Quest.Submit for these, it submits with no body.
Empty-body templates carry nothing. Use Quest.Submit, or actions.submit() with no argument.
Quest templates maps every live template name to its family and payload shape. Do not invent a template name or a payload shape. If a name arrives that you do not recognise, fall through to the default branch above, which handles it as empty-body and lets the machine decide.
Visit-link quests
The fan has to open a link before they can complete it. Render an outbound link, then let the machine take it from there.
function VisitLink({ args }) {
const { state } = useQuest()
return (
<>
<a href={args.url} target="_blank" rel="noopener noreferrer" className="your-link">
Open link
</a>
<Quest.Submit asChild>
<button disabled={!state.canSubmit}>{state.buttonLabel}</button>
</Quest.Submit>
</>
)
}Keep the CTA bound to state.canSubmit. The machine is what the platform verifies
against, and a button wired to your own click handler instead is not tracking the
thing that decides whether a submit is accepted.
canSubmit does not clear for visit-link quests. A trial ran the machine
against a live one and it held at VISIT_LINK_MISSION every time: no payload,
{ visited: true }, a full authProfile, community membership. Passing an
event changed the reason to EVENT_JOIN_NOT_ALLOWED instead of clearing it.
So the CTA above stays disabled. We have not tested whether bypassing the machine gets a submit accepted, so there is no workaround here yet. If a visit-link quest is on your critical path, talk to your FanBase contact first.
Social and bind quests
Follow, join, subscribe. These need the fan's account linked before the machine will let them act.
function BindAccount({ args }) {
const { state } = useQuest()
if (!state.canSubmit && state.disabledReasonLabel) {
return (
<>
<p>{state.disabledReasonLabel}</p>
<a href={connectUrl(args)} className="your-button">
Link account
</a>
</>
)
}
return <Quest.Submit asChild><button>{state.buttonLabel}</button></Quest.Submit>
}Payload is empty. Linking is the work. connectUrl is yours: it wraps buildBindUrl, with the account type in the redirect so your callback page knows what came back. Linking accounts has the whole flow.
Components
| Component | Use |
|---|---|
Quest.Provider | Loads the quest, runs the machine |
Quest.Frame | Wraps your detail UI |
Quest.Description | Renders structured description content |
Quest.Submit | Submit CTA for empty-body templates |
Quest.Accept | Accept step, where a template has one |
Quest.Complete | Complete step, where a template has one |
Quest.Claim | Claim CTA when a reward is waiting |
All take asChild and render your element. Full props in Components.
After a submit
The quest advances, and state follows it. Take your values from state, not from a copy, and the page updates on its own. If the reward became claimable, state.canClaim flips and you show the claim CTA. Rewards and claims.
Checklist
- Signed-in fan can submit at least one quest of each family you support
- Social-gated quests show a reason and a link button, not a dead disabled button
- After a submit, status and button label both change without a manual refresh
- An unrecognised template name renders something usable rather than crashing
- Description renders through
Quest.Description, not as raw JSON