Battlepass

Rendering a season

One provider, the season header, and a lane layout that keeps levels aligned.

The main build. Every piece of the pass renders inside one provider.

The shape

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

export function BattlepassPage() {
  return (
    <Battlepass.Provider>
      <SeasonHeader />
      <LaneStack />
    </Battlepass.Provider>
  )
}

Battlepass.Provider reads four things at once so you wire one: the fan's progress through the season, their membership, the community's membership tiers, and their XP level. It derives the lanes from all four and publishes the result to everything inside it.

Do not pass a communityId. The provider resolves it from the slug you already gave FanbaseProvider. And do not fetch membership tiers yourself anywhere on this page. The provider has them.

The pass renders signed out. A fan who is not signed in sees every tier with no personal progress on it, which is a good reason to put the pass somewhere they can find it before they have an account.

The season header

Title, level and whether claims are open. Battlepass.Season hands you all of it.

import { Battlepass, Parser } from '@xborglabs/fanbase-react'

function SeasonHeader() {
  return (
    <Battlepass.Season>
      {({ season, claimsEnabled, currentLevel, maxLevel }) => (
        <header className="your-season-header">
          <h1>{season?.title ?? 'Rewards'}</h1>
          <p>Level {currentLevel} of {maxLevel}</p>
          {season?.description ? <Parser content={season.description} /> : null}
          {!claimsEnabled && <p>Claims are closed for this season.</p>}
        </header>
      )}
    </Battlepass.Season>
  )
}

Three things to get right here:

season can be null. That is orphan mode, not a missing season. Render the ladder anyway. claimsEnabled is true in that state.

currentLevel is community XP, not membership rank. For a progress bar, useBattlepass().state.xp carries the balance and the next target:

const { state } = useBattlepass()
const progress = state.xp ? state.xp.balance / state.xp.next.target : 0

The description is structured content, the same format as a quest description. Render it through Parser. Printed as a string it comes out as JSON. Quest descriptions explains the format.

Do not show a countdown. The dates are not enforced, so a countdown to a season that keeps paying out after zero is a promise the platform does not keep. Show claimsEnabled instead.

Lanes and tiers

The part that decides whether the pass looks right.

function LaneStack() {
  return (
    <Battlepass.Lane>
      {({ lane }) => (
        <section className="your-lane">
          <h2>{lane.kind === 'free' ? 'Free' : lane.name}</h2>

          <Battlepass.Tier>
            {({ slot, level, gate, canClaim }) => (
              <div className="your-cell" data-level={level}>
                {!slot ? null : (
                  <article data-state={slot.state}>
                    <h3>{slot.tier.title}</h3>

                    {slot.state === 'PREMIUM_LOCKED' && (
                      <p>Needs {gate?.reason?.requiredTierName}</p>
                    )}

                    {canClaim && (
                      <Battlepass.Claim asChild>
                        <button className="your-button">Claim</button>
                      </Battlepass.Claim>
                    )}
                  </article>
                )}
              </div>
            )}
          </Battlepass.Tier>
        </section>
      )}
    </Battlepass.Lane>
  )
}

Battlepass.Lane renders every lane in order: the premium lane on top, the free lane below it. Pass laneId to render just one, for example as tabs on a phone.

Battlepass.Tier walks the lane one level at a time. It includes the gaps. A lane with nothing at level 4 still gets a cell at level 4, with slot set to null. That is deliberate: slots[i] is always level i + 1, in every lane, so a CSS grid keyed on level keeps the free lane and the premium lane lined up. Render the empty cell. If you skip it, every tier after the gap slides one column left and the lanes stop matching.

Both parts accept a render function or plain children. If you would rather build a card as its own component than thread props into it, read the same values from useBattlepassLane() and useBattlepassTier() inside it.

A season, two lanesTry it
Fan's membership
Fan's XP level
4
Show
Level 1Level 2Level 3Level 4Level 5Level 6Level 7Level 8
PremiumPremium members
100 Coins🔒 Premium
Premium badge🔒 Premium
500 Coins🔒 Premium
Loot box🔒 Premium
300 Coins🔒 Premium
Signed shirt🔒 Premium
750 Coins🔒 Premium
Animated border🔒 Premium
FreeEveryone
50 Coins
Profile picture
50 Coins
Loot box
no tier
100 Coins
Match ticket
150 Coins
The lanes follow your membership, the levels follow your XP. Note the free lane has no tier at level 5, and its level 6 tier stays in the level 6 column. Example data.

Tier states

Each slot carries a state. Render it, do not recompute it.

stateMeansWhat to render
PREMIUM_LOCKEDThe fan's membership is below what this tier asks forLock badge, the tier name from gate.reason.requiredTierName, an upgrade prompt
CLAIMEDAlready takenA taken state, no button
CLAIMABLELevel reached and not claimedThe claim button
FUTURELevel not reached yetA dimmed card, nothing to press

A tier the fan has reached but cannot claim for a reason the SDK does not recognise also reads as FUTURE. Inert is the safe way to render "we are not sure you can have this".

The premium upsell is yours. The gate tells you which membership tier unlocks the reward, by name and rank. What the upgrade costs and where it goes is your product's call.

Milestone tiers, the ones your community team flagged as featured, carry slot.isMilestone. Use it for a taller card or a different treatment.

Switching seasons

Optional. Past seasons are worth showing when a community runs them back to back.

import { Battlepass, useBattlepassProgress, useBattlepassSeasons } from '@xborglabs/fanbase-react'

function SeasonSwitcher() {
  const [selectedId, setSelectedId] = useState()
  const { data: progress } = useBattlepassProgress()
  const { data: seasons = [] } = useBattlepassSeasons()

  const liveId = progress?.season?.seasonId
  const switchable = seasons.filter((season) => season.status !== 'CLOSED')

  return (
    <Battlepass.Provider seasonId={selectedId}>
      <select
        value={selectedId ?? liveId}
        onChange={(e) => setSelectedId(e.target.value === liveId ? undefined : e.target.value)}
      >
        {switchable.map((season) => (
          <option key={season.seasonId} value={season.seasonId}>
            {season.title ?? season.seasonId}
          </option>
        ))}
      </select>
      <SeasonHeader />
      <LaneStack />
    </Battlepass.Provider>
  )
}

Leave CLOSED seasons out of the control.

For the live season, pass undefined, not its id. That keeps the provider on the live progress read, which is the only one that works in orphan mode. Passing the live season's own id sends it down the single-season read instead, and a community with no active season then renders nothing.

Components

ComponentUse
Battlepass.ProviderReads the season, membership and XP, derives the lanes
Battlepass.SeasonSeason header: title, level, whether claims are open
Battlepass.LaneEvery lane in order, or one by laneId
Battlepass.TierOne cell per level in a lane, gaps included
Battlepass.ClaimClaim button for one tier
Battlepass.ClaimAllClaim button for everything that can settle on its own

Claim and ClaimAll take asChild and render your element. Full props in Components.

Checklist

  • The pass renders with no communityId and no membership fetch of your own
  • season: null renders the ladder, not an empty state
  • The season description goes through Parser
  • No code compares the end date to today, and there is no countdown
  • The premium lane renders above the free lane
  • A lane with a gap renders an empty cell there, and the lanes stay aligned
  • A premium tier shows as locked for a free fan, with the required tier's name

On this page