flowglad / flowglad-pricing-ui
Install for your project team
Run this command in your project directory to install the skill for your entire team:
mkdir -p .claude/skills/flowglad-pricing-ui && curl -L -o skill.zip "https://fastmcp.me/Skills/Download/3795" && unzip -o skill.zip -d .claude/skills/flowglad-pricing-ui && rm skill.zipProject Skills
This skill will be saved in .claude/skills/flowglad-pricing-ui/ and checked into git. All team members will have access to it automatically.
Important: Please verify the skill by reviewing its instructions before using it.
Build pricing pages, pricing cards, and plan displays with Flowglad. Use this skill when creating pricing tables, displaying subscription options, or building plan comparison interfaces.
0 views
0 installs
Skill Content
---
name: flowglad-pricing-ui
description: Build pricing pages, pricing cards, and plan displays with Flowglad. Use this skill when creating pricing tables, displaying subscription options, or building plan comparison interfaces.
license: MIT
metadata:
author: flowglad
version: "1.0.0"
---
<!--
@flowglad/skill
sources_reviewed: 2026-02-24T21:27:00Z
source_files:
- platform/docs/features/prices.mdx
- platform/docs/features/pricing-models.mdx
- platform/docs/sdks/pricing-models-products.mdx
- platform/docs/sdks/react.mdx
-->
# Flowglad Pricing UI
## Abstract
Comprehensive guide for building pricing pages, pricing cards, and plan displays with Flowglad. Covers loading states, accessing pricing data through helper functions, formatting prices correctly, highlighting current subscriptions, implementing billing interval toggles, and responsive layout patterns.
---
## Table of Contents
1. [Loading States](#1-loading-states) — **CRITICAL**
- 1.1 [Wait for pricingModel Before Rendering](#11-wait-for-pricingmodel-before-rendering)
- 1.2 [Public Pricing Pages with usePricingModel](#12-public-pricing-pages-with-usepricingmodel)
2. [Accessing Pricing Data](#2-accessing-pricing-data) — **HIGH**
- 2.1 [Use getProduct and getPrice Helpers](#21-use-getproduct-and-getprice-helpers)
- 2.2 [Filter Products for Display](#22-filter-products-for-display)
3. [Building Pricing Cards](#3-building-pricing-cards) — **MEDIUM**
- 3.1 [Format Prices from Cents](#31-format-prices-from-cents)
- 3.2 [Display Billing Interval](#32-display-billing-interval)
- 3.3 [Extract and Display Features](#33-extract-and-display-features)
4. [Current Plan Highlighting](#4-current-plan-highlighting) — **MEDIUM**
- 4.1 [Detect Current Subscription](#41-detect-current-subscription)
- 4.2 [Disable or Style Current Plan](#42-disable-or-style-current-plan)
5. [Billing Interval Toggle](#5-billing-interval-toggle) — **MEDIUM**
- 5.1 [Monthly/Annual Toggle Pattern](#51-monthlyannual-toggle-pattern)
- 5.2 [Filter Prices by Interval](#52-filter-prices-by-interval)
6. [Responsive Layout](#6-responsive-layout) — **LOW**
- 6.1 [Grid Layout for Pricing Cards](#61-grid-layout-for-pricing-cards)
---
## 1. Loading States
**Impact: CRITICAL**
The pricing model loads asynchronously. Rendering before data is available causes visual flicker, incorrect UI states, or hydration mismatches.
### 1.1 Wait for pricingModel Before Rendering
**Impact: CRITICAL (prevents flash of incorrect content)**
Always check that billing data has loaded before rendering pricing UI. The `pricingModel` is `null` or `undefined` until the billing data loads.
**Incorrect: renders empty or broken UI while loading**
```tsx
function PricingPage() {
const billing = useBilling()
// BUG: pricingModel is undefined while loading!
// This renders empty pricing grid, then re-renders when data arrives
const products = billing.pricingModel?.products ?? []
return (
<div className="pricing-grid">
{products.map((product) => (
<PricingCard key={product.id} product={product} />
))}
</div>
)
}
```
Users see an empty pricing page that suddenly fills in, causing layout shift and poor UX.
**Correct: show loading state until data is ready**
```tsx
function PricingPage() {
const billing = useBilling()
// Wait for billing to load
if (!billing.loaded) {
return <PricingPageSkeleton />
}
// Handle error state
if (billing.errors) {
return <div>Unable to load pricing. Please try again.</div>
}
// Now safe to access pricingModel
const products = billing.pricingModel?.products ?? []
return (
<div className="pricing-grid">
{products.map((product) => (
<PricingCard key={product.id} product={product} />
))}
</div>
)
}
```
**Alternative: early return pattern**
```tsx
function PricingPage() {
const billing = useBilling()
if (!billing.loaded || billing.errors || !billing.pricingModel) {
return <PricingPageSkeleton />
}
// TypeScript now knows pricingModel is defined
const { products } = billing.pricingModel
return (
<div className="pricing-grid">
{products.map((product) => (
<PricingCard key={product.id} product={product} />
))}
</div>
)
}
```
### 1.2 Public Pricing Pages with usePricingModel
**Impact: CRITICAL (enables unauthenticated pricing pages)**
For public pricing pages that don't require authentication, use the `usePricingModel()` hook instead of `useBilling()`. This returns only the pricing data without requiring a logged-in user.
**Incorrect: uses useBilling for public page**
```tsx
// Public pricing page - no user logged in
function PublicPricingPage() {
// BUG: useBilling requires authentication context
// Will fail or return empty data for unauthenticated users
const billing = useBilling()
if (!billing.loaded) return <div>Loading...</div>
return <PricingDisplay products={billing.pricingModel?.products} />
}
```
**Correct: uses usePricingModel for public pages**
```tsx
import { usePricingModel } from '@flowglad/nextjs'
function PublicPricingPage() {
// Works without authentication
const pricingModel = usePricingModel()
// Returns null while loading
if (!pricingModel) {
return <PricingPageSkeleton />
}
return (
<div className="pricing-grid">
{pricingModel.products.map((product) => {
const defaultPrice = product.defaultPrice ?? product.prices?.[0]
return (
<article key={product.slug}>
<h3>{product.name}</h3>
<p>{product.description}</p>
{defaultPrice && (
<p>
${(defaultPrice.unitPrice / 100).toFixed(2)}
{defaultPrice.intervalUnit && `/${defaultPrice.intervalUnit}`}
</p>
)}
</article>
)
})}
</div>
)
}
```
**When to use each hook:**
- `useBilling()` - Authenticated pages where you need subscription status, checkout, or user-specific data
- `usePricingModel()` - Public pricing pages, marketing sites, or anywhere you just need to display plans
---
## 2. Accessing Pricing Data
**Impact: HIGH**
Flowglad provides helper functions to access products and prices by slug. Using these helpers is more reliable than manual array lookups.
### 2.1 Use getProduct and getPrice Helpers
**Impact: HIGH (prevents runtime errors, cleaner code)**
The billing object provides `getProduct()` and `getPrice()` helper functions that look up items by slug. Use these instead of manually searching arrays.
**Incorrect: manual array lookup**
```tsx
function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const billing = useBilling()
if (!billing.loaded) return null
// Fragile: searches across all products, easy to get wrong
const targetPrice = billing.pricingModel?.products
.flatMap((p) => p.prices)
.find((price) => price.slug === targetPriceSlug)
if (!targetPrice) return null
return <button>Upgrade to {targetPrice.name}</button>
}
```
**Correct: use getPrice helper**
```tsx
function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const billing = useBilling()
if (!billing.loaded) return null
// Clean: helper does the lookup efficiently
const targetPrice = billing.getPrice(targetPriceSlug)
if (!targetPrice) return null
return <button>Upgrade to {targetPrice.name}</button>
}
```
**Same pattern for products:**
```tsx
function ProductFeatures({ productSlug }: { productSlug: string }) {
const billing = useBilling()
if (!billing.loaded) return null
// Use getProduct helper
const product = billing.getProduct(productSlug)
if (!product) return null
return (
<ul>
{product.features.map((feature) => (
<li key={feature.id}>{feature.name}</li>
))}
</ul>
)
}
```
### 2.2 Filter Products for Display
**Impact: HIGH (shows only relevant products)**
Not all products should appear on pricing pages. Filter out default/free products and products without active prices.
**Incorrect: displays all products including internal ones**
```tsx
function PricingGrid() {
const billing = useBilling()
if (!billing.loaded || !billing.pricingModel) return null
// BUG: Shows ALL products, including free tier and inactive products
return (
<div>
{billing.pricingModel.products.map((product) => (
<PricingCard key={product.id} product={product} />
))}
</div>
)
}
```
**Correct: filter to displayable products**
```tsx
function PricingGrid() {
const billing = useBilling()
if (!billing.loaded || !billing.pricingModel) return null
// Filter products for display
const displayProducts = billing.pricingModel.products.filter((product) => {
// Skip default/free tier products
if (product.default === true) return false
// Only show products with active subscription prices
const hasActivePrice = product.prices.some(
(price) => price.type === 'subscription' && price.active === true
)
return hasActivePrice
})
return (
<div>
{displayProducts.map((product) => (
<PricingCard key={product.id} product={product} />
))}
</div>
)
}
```
**Transform to UI-friendly format:**
```tsx
interface PricingPlan {
name: string
description?: string
displayPrice: string
slug: string
features: string[]
unitPrice: number
}
function transformProductsToPricingPlans(
pricingModel: PricingModel | null | undefined
): PricingPlan[] {
if (!pricingModel?.products) return []
return pricingModel.products
.filter((product) => {
if (product.default === true) return false
return product.prices.some(
(p) => p.type === 'subscription' && p.active === true
)
})
.map((product) => {
const price = product.prices.find(
(p) => p.type === 'subscription' && p.active === true
)
if (!price?.slug) return null
return {
name: product.name,
description: product.description,
displayPrice: `$${(price.unitPrice / 100).toFixed(2)}`,
slug: price.slug,
features: product.features.map((f) => f.name).filter(Boolean),
unitPrice: price.unitPrice,
}
})
.filter((plan): plan is PricingPlan => plan !== null)
.sort((a, b) => a.unitPrice - b.unitPrice)
}
```
---
## 3. Building Pricing Cards
**Impact: MEDIUM**
Pricing cards display product information with proper formatting. Getting price formatting and interval display right is essential for clear communication.
### 3.1 Format Prices from Cents
**Impact: MEDIUM (prevents displaying wrong amounts)**
Flowglad stores prices in cents (e.g., 1000 = $10.00). Always convert to dollars for display.
**Incorrect: displays cents as dollars**
```tsx
function PriceDisplay({ price }: { price: Price }) {
// BUG: Shows "$1000" instead of "$10.00"
return <span>${price.unitPrice}</span>
}
```
**Correct: convert cents to dollars**
```tsx
function PriceDisplay({ price }: { price: Price }) {
const dollars = (price.unitPrice / 100).toFixed(2)
return <span>${dollars}</span>
}
```
**Helper function for consistent formatting:**
```tsx
function formatPriceFromCents(cents: number): string {
return `$${(cents / 100).toFixed(2)}`
}
// Usage
function PriceDisplay({ price }: { price: Price }) {
return <span>{formatPriceFromCents(price.unitPrice)}</span>
}
```
**With locale-aware formatting:**
```tsx
function formatPriceFromCents(
cents: number,
currency: string = 'USD',
locale: string = 'en-US'
): string {
return new Intl.NumberFormat(locale, {
style: 'currency',
currency,
}).format(cents / 100)
}
```
### 3.2 Display Billing Interval
**Impact: MEDIUM (clarifies subscription terms)**
Subscription prices have `intervalUnit` (day, month, year) and `intervalCount` properties. Display these clearly.
**Incorrect: ignores billing interval**
```tsx
function PriceDisplay({ price }: { price: SubscriptionPrice }) {
// Confusing: Is this $10 total? Per month? Per year?
return <span>${(price.unitPrice / 100).toFixed(2)}</span>
}
```
**Correct: shows billing interval**
```tsx
function PriceDisplay({ price }: { price: SubscriptionPrice }) {
const amount = (price.unitPrice / 100).toFixed(2)
// Format interval display
let intervalLabel = ''
if (price.intervalUnit) {
if (price.intervalCount === 1) {
intervalLabel = `/${price.intervalUnit}`
} else {
intervalLabel = ` every ${price.intervalCount} ${price.intervalUnit}s`
}
}
return (
<span>
${amount}
{intervalLabel}
</span>
)
}
// Renders: "$10.00/month" or "$99.00/year" or "$5.00 every 2 weeks"
```
**Helper function:**
```tsx
function formatSubscriptionPrice(price: SubscriptionPrice): string {
const amount = (price.unitPrice / 100).toFixed(2)
if (!price.intervalUnit) {
return `$${amount}`
}
if (price.intervalCount === 1) {
return `$${amount}/${price.intervalUnit}`
}
return `$${amount} every ${price.intervalCount} ${price.intervalUnit}s`
}
```
### 3.3 Extract and Display Features
**Impact: MEDIUM (shows value proposition)**
Products have a `features` array. Extract and display feature names in pricing cards.
**Incorrect: doesn't handle missing feature names**
```tsx
function FeatureList({ product }: { product: Product }) {
return (
<ul>
{product.features.map((feature) => (
// BUG: feature.name might be undefined
<li key={feature.id}>{feature.name}</li>
))}
</ul>
)
}
```
**Correct: filter to features with names**
```tsx
function FeatureList({ product }: { product: Product }) {
// Filter to features that have names
const displayFeatures = product.features.filter(
(feature): feature is Feature & { name: string } =>
typeof feature.name === 'string' && feature.name.length > 0
)
if (displayFeatures.length === 0) {
return null
}
return (
<ul>
{displayFeatures.map((feature) => (
<li key={feature.id}>{feature.name}</li>
))}
</ul>
)
}
```
---
## 4. Current Plan Highlighting
**Impact: MEDIUM**
When displaying pricing to authenticated users, highlight which plan they're currently on to help them understand their options.
### 4.1 Detect Current Subscription
**Impact: MEDIUM (helps users understand their status)**
Use the current subscription's price ID to determine which pricing card represents the user's current plan.
**Incorrect: compares product names (unreliable)**
```tsx
function isPlanCurrent(product: Product, billing: LoadedBillingContext) {
// BUG: Product names might not be unique, or might change
return billing.currentSubscription?.product?.name === product.name
}
```
**Correct: compares price IDs**
```tsx
function isPlanCurrent(priceSlug: string, billing: LoadedBillingContext) {
// No current subscription = no current plan
if (!billing.currentSubscriptions?.length) {
return false
}
// Get the price by slug
const price = billing.getPrice(priceSlug)
if (!price) {
return false
}
// Check if any current subscription uses this price
const currentPriceIds = new Set(
billing.currentSubscriptions.map((sub) => sub.priceId)
)
return currentPriceIds.has(price.id)
}
```
**Usage in a component:**
```tsx
function PricingCard({
plan,
isCurrentPlan,
}: {
plan: PricingPlan
isCurrentPlan: boolean
}) {
return (
<div className={isCurrentPlan ? 'border-primary' : 'border-gray-200'}>
<h3>{plan.name}</h3>
<p>{plan.displayPrice}</p>
{isCurrentPlan && <span className="badge">Current Plan</span>}
</div>
)
}
function PricingGrid() {
const billing = useBilling()
if (!billing.loaded || !billing.pricingModel) return null
const plans = transformProductsToPricingPlans(billing.pricingModel)
return (
<div className="grid grid-cols-3 gap-4">
{plans.map((plan) => (
<PricingCard
key={plan.slug}
plan={plan}
isCurrentPlan={isPlanCurrent(plan.slug, billing)}
/>
))}
</div>
)
}
```
### 4.2 Disable or Style Current Plan
**Impact: MEDIUM (prevents confusing interactions)**
The "current plan" card should not have an active checkout button. Either disable or restyle the action.
**Incorrect: same button for all plans**
```tsx
function PricingCard({ plan }: { plan: PricingPlan }) {
const billing = useBilling()
const handleUpgrade = async () => {
// BUG: Allows clicking to "upgrade" to current plan
await billing.createCheckoutSession({
priceSlug: plan.slug,
successUrl: window.location.origin,
cancelUrl: window.location.href,
autoRedirect: true,
})
}
return (
<div>
<h3>{plan.name}</h3>
<button onClick={handleUpgrade}>Get Started</button>
</div>
)
}
```
**Correct: disable button for current plan**
```tsx
function PricingCard({
plan,
isCurrentPlan,
}: {
plan: PricingPlan
isCurrentPlan: boolean
}) {
const billing = useBilling()
const [isLoading, setIsLoading] = useState(false)
const handleUpgrade = async () => {
if (isCurrentPlan || isLoading) return
setIsLoading(true)
try {
await billing.createCheckoutSession({
priceSlug: plan.slug,
successUrl: `${window.location.origin}/dashboard?upgraded=true`,
cancelUrl: window.location.href,
autoRedirect: true,
})
} finally {
setIsLoading(false)
}
}
return (
<div className={isCurrentPlan ? 'border-primary' : ''}>
<h3>{plan.name}</h3>
<p>{plan.displayPrice}</p>
<button
onClick={handleUpgrade}
disabled={isCurrentPlan || isLoading}
className={isCurrentPlan ? 'opacity-50 cursor-not-allowed' : ''}
>
{isCurrentPlan ? 'Current Plan' : isLoading ? 'Loading...' : 'Get Started'}
</button>
</div>
)
}
```
---
## 5. Billing Interval Toggle
**Impact: MEDIUM**
Many pricing pages let users toggle between monthly and annual billing to compare options.
### 5.1 Monthly/Annual Toggle Pattern
**Impact: MEDIUM (improves comparison shopping)**
Implement a toggle that filters prices by billing interval.
**Basic implementation:**
```tsx
type BillingInterval = 'month' | 'year'
function PricingPage() {
const billing = useBilling()
const [interval, setInterval] = useState<BillingInterval>('month')
if (!billing.loaded || !billing.pricingModel) {
return <PricingPageSkeleton />
}
return (
<div>
<div className="flex gap-2 mb-8">
<button
onClick={() => setInterval('month')}
className={interval === 'month' ? 'bg-primary' : 'bg-gray-200'}
>
Monthly
</button>
<button
onClick={() => setInterval('year')}
className={interval === 'year' ? 'bg-primary' : 'bg-gray-200'}
>
Annual
</button>
</div>
<PricingGrid interval={interval} pricingModel={billing.pricingModel} />
</div>
)
}
```
### 5.2 Filter Prices by Interval
**Impact: MEDIUM (shows correct prices for selected interval)**
When displaying prices, filter to only show prices matching the selected billing interval.
**Incorrect: shows all prices regardless of interval**
```tsx
function PricingGrid({
interval,
pricingModel,
}: {
interval: BillingInterval
pricingModel: PricingModel
}) {
return (
<div>
{pricingModel.products.map((product) => {
// BUG: Shows first price regardless of interval selection
const price = product.prices[0]
return (
<PricingCard key={product.id} product={product} price={price} />
)
})}
</div>
)
}
```
**Correct: filter prices by interval**
```tsx
function PricingGrid({
interval,
pricingModel,
}: {
interval: BillingInterval
pricingModel: PricingModel
}) {
const plans = pricingModel.products
.filter((product) => !product.default)
.map((product) => {
// Find the price matching the selected interval
const price = product.prices.find(
(p) =>
p.type === 'subscription' &&
p.active === true &&
p.intervalUnit === interval &&
(p.intervalCount === 1 || p.intervalCount === undefined)
)
if (!price) return null
return {
product,
price,
displayPrice: formatSubscriptionPrice(price),
}
})
.filter(Boolean)
return (
<div className="grid grid-cols-3 gap-4">
{plans.map(({ product, price, displayPrice }) => (
<PricingCard
key={product.id}
name={product.name}
description={product.description}
price={displayPrice}
priceSlug={price.slug}
features={product.features}
/>
))}
</div>
)
}
```
---
## 6. Responsive Layout
**Impact: LOW**
Pricing grids should adapt to different screen sizes for optimal viewing.
### 6.1 Grid Layout for Pricing Cards
**Impact: LOW (improves mobile experience)**
Use CSS grid with responsive breakpoints to adjust the number of columns.
**Basic responsive grid:**
```tsx
function PricingGrid({ plans }: { plans: PricingPlan[] }) {
return (
<div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
{plans.map((plan) => (
<PricingCard key={plan.slug} plan={plan} />
))}
</div>
)
}
```
**Centered layout for fewer plans:**
```tsx
function PricingGrid({ plans }: { plans: PricingPlan[] }) {
// Center cards when fewer than 3 plans
const gridClass =
plans.length <= 2
? 'flex flex-wrap justify-center gap-6'
: 'grid gap-6 md:grid-cols-2 lg:grid-cols-3'
return (
<div className={gridClass}>
{plans.map((plan) => (
<PricingCard key={plan.slug} plan={plan} />
))}
</div>
)
}
```
**Full-width cards on mobile:**
```tsx
function PricingCard({ plan }: { plan: PricingPlan }) {
return (
<div className="w-full md:max-w-sm rounded-lg border p-6">
<h3 className="text-xl font-semibold">{plan.name}</h3>
<p className="text-3xl font-bold my-4">{plan.displayPrice}</p>
<ul className="space-y-2 mb-6">
{plan.features.map((feature, index) => (
<li key={index} className="flex items-center gap-2">
<CheckIcon className="h-4 w-4 text-green-500" />
<span>{feature}</span>
</li>
))}
</ul>
<button className="w-full py-2 px-4 bg-primary text-white rounded">
Get Started
</button>
</div>
)
}
```
---
## References
1. [Flowglad Documentation](https://docs.flowglad.com)
2. [Flowglad React SDK](https://github.com/flowglad/flowglad)