Browsing the store
The grid, the filters, the cards, and a price that says what it is priced in.
The storefront. Mostly your design, with the SDK doing the data and the arithmetic.
The shape
import { Store, useStore } from '@xborglabs/fanbase-react'
export function StorePage() {
return (
<Store.Provider enrichRequirements>
<Grid />
</Store.Provider>
)
}
function Grid() {
const { state } = useStore()
if (state.isLoading) return <YourSkeleton count={8} />
if (state.error) return <YourError />
if (!state.listings.length) return <YourEmptyState />
return (
<ul className="your-grid">
{state.listings.map((listing) => (
<li key={listing.storeItemId}>
<Store.Listing listing={listing}>
<ListingCard />
</Store.Listing>
</li>
))}
</ul>
)
}Store.Provider reads the listings, the fan's balances, the membership tiers and the currency names in one go. Store.Listing wraps one card and works out whether that listing can be bought.
Do not pass a containerId or communityId. The provider resolves them from the slug on FanbaseProvider.
Keep enrichRequirements on. It fills in details the fan has already saved, like their shipping address, so a listing that needs one does not wrongly report it as missing. Turning it on for a separate useStoreListings call beside the provider does not help: it has to be on the provider, because that is the read that fills the grid.
The store works signed out. Listings, prices and currency names are public. Balances and membership only load once a fan signs in.
Filters
Four of them, and the SDK turns them into the request for you. Pass them to the provider:
import { STORE_SORT } from '@xborglabs/fanbase-react'
<Store.Provider
enrichRequirements
page={page}
limit={24}
filters={{
sort: STORE_SORT.CHEAPEST,
maxPrice: 500,
inStockOnly: true,
tagIds: selectedTagIds,
}}
>| Sort | Order |
|---|---|
STORE_SORT.ALL | The order your community team set |
STORE_SORT.CHEAPEST | Price, low to high |
STORE_SORT.MOST_EXPENSIVE | Price, high to low |
STORE_SORT.NEWEST | Newest first |
Filtering happens on the server, so paging stays correct. limit defaults to 20.
The SDK holds no filter state and does not read the URL. Keep the filters in your router's query string, so a filtered view survives a refresh and can be shared as a link.
Tags
Your community team tags listings in the admin panel. Read the tags for your filter chips with a hook beside the provider:
import { useStoreTags } from '@xborglabs/fanbase-react'
const { data } = useStoreTags()
data?.results.map((tag) => (
<button key={tag.tagId} onClick={() => toggle(tag.tagId)}>{tag.label}</button>
))Tag labels arrive already translated. Put the tagIds you select into filters.tagIds.
The featured carousel
Optional, and configured in the Hub. Each slide links to a listing.
import { useStoreCarousel } from '@xborglabs/fanbase-react'
const { data: slides = [] } = useStoreCarousel()This one returns the slides directly, not inside results. A slide's title, description and buttons can all be empty if your team did not fill them in, so treat each as optional. The slide's own description is plain text. The listing it points to, at slide.item, has the same shape as a card.
A card
Every listing arrives with a unified field: a name, an image and a description, whichever of the four listing types it is. Build cards from that and you never branch on type to find a title.
import { Store, useStoreListing } from '@xborglabs/fanbase-react'
function ListingCard() {
const { state } = useStoreListing()
const { name, mediaUrl } = state.listing.unified
return (
<article className="your-card">
{mediaUrl ? <img src={mediaUrl} alt={name} /> : <YourPlaceholder />}
<h3>{name || 'Untitled'}</h3>
<Store.Description isPlain />
<Price />
</article>
)
}Check for mediaUrl before rendering an image. An item with no art has no mediaUrl at all, rather than an empty string, so there is no broken image to guard against.
The item a listing points at can be missing even when its id is there. Read anything beyond unified with optional chaining, listing.prize?.name, so one incomplete listing does not take down the grid.
Descriptions
A listing description is structured content, the same format as a quest description. It is not a string and not markdown.
<Store.Description isPlain /> // on a card: plain text, one line of it
<Store.Description /> // on a product page: the full renderPrinted directly it comes out as [object Object]. Quest descriptions covers the format and how to style it.
Prices
A price is a number and a currency. resolveStorePriceChrome puts them together:
import { getSpendableBalance, resolveStorePriceChrome, useStore, useStoreListing } from '@xborglabs/fanbase-react'
function Price() {
const { state: store } = useStore()
const { state } = useStoreListing()
const option = state.pricingOption
const chrome = resolveStorePriceChrome(option, store.balances, store.resourceTypes)
const balance = option ? getSpendableBalance(store.balances, option.resourceTypeId) : undefined
return (
<p className="your-price">
{chrome?.label}
{store.isAuthenticated && <span>You have {balance}</span>}
</p>
)
}chrome.label is 12 Credits, or whatever your currency is called. It works for fans who are not signed in, because currency names are public.
Read the balance for the listing's own currency, as above. Never balances[0]. In a store with two currencies, the first balance is often the wrong one, and a fan with plenty of Coins gets told they cannot afford something priced in Coins.
Sales
A listing on sale has two prices: the sale one, with isSale: true, and the normal one. The SDK does not pick the sale price for you. Unless you say otherwise, the gate and the checkout use the first price in the list.
Pick it yourself:
const selected = listing.listings.find((option) => option.isSale) ?? listing.listings[0]Then pass selected to the checkout, as Buying shows. The strikethrough and the percentage off are yours to draw from the two prices.
Level requirements
Some listings need a minimum level. That badge is yours to render, from the listing's requirements. It is not part of the purchase gate, so a fan below the level will still see the buy button enabled, and the purchase will be refused with the same error as a bad email. If level-locked listings matter to your store, check the fan's level on the product page before you enable the button.
Checklist
- The grid renders with no
containerIdorcommunityId enrichRequirementsis on the provider- Every card has a name, and art only where there is art
- Descriptions go through
Store.Description, plain on cards - Prices read
12 Credits, signed in or not - A store with two currencies shows the balance of the right one
- A sale listing sells at the sale price
- Filters live in the URL