flowglad-pricing-ui

<!-- @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 — CRITICAL
   • 1.1 Wait for pricingModel Before Rendering
   • 1.2 Public Pricing Pages with usePricingModel
2. Accessing Pricing Data — HIGH
   • 2.1 Use getProduct and getPrice Helpers
   • 2.2 Filter Products for Display
3. Building Pricing Cards — MEDIUM
   • 3.1 Format Prices from Cents
   • 3.2 Display Billing Interval
   • 3.3 Extract and Display Features
4. Current Plan Highlighting — MEDIUM
   • 4.1 Detect Current Subscription
   • 4.2 Disable or Style Current Plan
5. Billing Interval Toggle — MEDIUM
   • 5.1 Monthly/Annual Toggle Pattern
   • 5.2 Filter Prices by Interval
6. Responsive Layout — LOW
   • 6.1 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

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

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

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

// 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

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

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

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:

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

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

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:

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,
      }


---

*Content truncated.*