Quests

Listing quests

One hook, one request, and what a card needs.

The list page. Short, because the SDK does most of it.

One hook

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

export function QuestsPage() {
  const { data: quests, isLoading, error } = useQuestsList()

  if (isLoading) return <YourSkeleton count={6} />
  if (error) return <YourError />
  if (!quests?.length) return <YourEmptyState />

  return (
    <div className="your-grid">
      {quests.map((quest) => (
        <QuestCard key={quest.id} quest={quest} />
      ))}
    </div>
  )
}

One call, one GET /v1/quests, the whole list scoped to your tenant.

Do not fan out

Cards render from the row you already have. Do not call quest detail per card, and do not fetch reward allocations for cards.

It is tempting when a card wants a completion state or a reward image, and it turns one request into fifty on a busy page. Everything a card needs is on the row. If something genuinely is not, tell us rather than fanning out.

What a row has

Title, description, template, status, dates, rewards, image. Enough for a card without any extra call.

Two of those need care when rendering:

Status comes back as a raw enum. INACTIVE does not mean the quest is off, it means the fan has not started it. Resolve it through the string catalog. Display strings.

Description is structured content, not a string. On a card you usually want a plain-text excerpt rather than the full render. Quest descriptions.

Cards without sign-in

The list works signed out. That is usually what you want, since a fan seeing what is on offer is the reason they sign in.

Quest detail is a different story. Submitting and claiming need a session, and reward fetching needs one too. Detail for a signed-out fan renders, with the machine reporting that sign-in is required.

Filtering and grouping

Filter and sort client-side off the rows you have. Common groupings: active first, then completed. By tag, if your community team uses tags. By reward type.

Tags are set in the admin panel, so your community team can reorganise a quest page without a deploy if you group by them.

Opening a quest

Route to a detail page and pass the row through as seed data so the detail view has something to render immediately.

navigate(`/quests/${quest.id}`, { state: { quest } })

How you hand that row to Quest.Provider matters. Read Quest detail before wiring it, there is one specific way to do it that keeps the page updating after a submit.

On this page