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 : 0The 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.
Tier states
Each slot carries a state. Render it, do not recompute it.
state | Means | What to render |
|---|---|---|
PREMIUM_LOCKED | The fan's membership is below what this tier asks for | Lock badge, the tier name from gate.reason.requiredTierName, an upgrade prompt |
CLAIMED | Already taken | A taken state, no button |
CLAIMABLE | Level reached and not claimed | The claim button |
FUTURE | Level not reached yet | A 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
| Component | Use |
|---|---|
Battlepass.Provider | Reads the season, membership and XP, derives the lanes |
Battlepass.Season | Season header: title, level, whether claims are open |
Battlepass.Lane | Every lane in order, or one by laneId |
Battlepass.Tier | One cell per level in a lane, gaps included |
Battlepass.Claim | Claim button for one tier |
Battlepass.ClaimAll | Claim 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
communityIdand no membership fetch of your own season: nullrenders 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