React - Metrifox

Unified theme API from v2.0.0
@metrifox/react-sdk v2.0.0 and later use one theme object on metrifoxInit({ theme }) with customerPortal and pricingTable. Root-level pricingTableTheme and the older flat / legacy theme shapes are removed and are not supported on 2.x. Releases before v2.0.0 used the previous theme model—upgrade to 2.0.0+ and migrate theme objects to the grouped structure. See SDK changelog and Styling.

Use the live playground to preview Customer Portal and Pricing Table before integrating the SDK into your application: React SDK Playground.

Installation

npm install @metrifox/react-sdk
# or
pnpm add @metrifox/react-sdk
# or
yarn add @metrifox/react-sdk

Setup

Initialize once with your client key (from the Metrifox dashboard) before rendering any SDK components.

import { metrifoxInit } from "@metrifox/react-sdk";

metrifoxInit({
  clientKey:
    process.env.NEXT_PUBLIC_METRIFOX_APP_SECRET ||
    process.env.REACT_APP_METRIFOX_APP_SECRET ||
    import.meta.env?.VITE_METRIFOX_APP_SECRET ||
    "your-client-key",
});

Works with React, Next.js, and other setups on React 18+. Environment variable names may vary by framework; use the public prefix your bundler expects so the key is available in the browser.

Widgets

`CustomerPortal`

Renders a customer dashboard: plans, subscriptions, billing, credits, and related sections.

import { CustomerPortal } from "@metrifox/react-sdk";

const MyCustomPlan = ({ foo }: { foo?: string }) => (
  <div>Custom plan section. Foo: {foo}</div>
);

export default function MyPortalPage() {
  return (
    <CustomerPortal
      customerKey="your-customer-key"
      sectionsConfig={[
        { key: "subscription" },
        { key: "plan", component: MyCustomPlan, props: { foo: "bar" } },
        { key: "billingHistory", hidden: true },
      ]}
      theme={{ general: { linkColor: "#2563eb" } }}
    />
  );
}

Optional theme prop: pass a CustomerPortalTheme partial to override or extend the global theme from metrifoxInit for this mount only (merged with defaults and global config).

Section configuration

Property	Type	Description
`key`	`SectionKey`	Section identifier (see table below)
`hidden`	`boolean`	When `true`, the section is not shown
`component`	`React.ComponentType`	Replace the default section UI
`props`	`Record<string, unknown>`	Props passed to custom or default section

Built-in section keys

Key	Description
`upcomingInvoice`	Next invoice details
`subscription`	Active subscription overview
`creditBalance`	Wallet / credit balance
`entitlementUsage`	Usage meters
`paymentOverview`	Payment methods and summary
`billingHistory`	Past invoices / transactions
`plan`	Current plan

Section anchors (deep links)

Each section is wrapped in <section id="..."> for hash links (for example https://yourapp.com/billing#billing-history).

Anchor ID	Section key
`#upcoming-invoice`	`upcomingInvoice`
`#subscription`	`subscription`
`#credit-balance`	`creditBalance`
`#entitlement-usage`	`entitlementUsage`
`#payment-overview`	`paymentOverview`
`#billing-history`	`billingHistory`
`#plan`	`plan`

`PricingTable`

Renders subscription plans and one-time purchases for a product.

import { PricingTable } from "@metrifox/react-sdk";

export default function PricingPage() {
  return (
    <PricingTable
      checkoutUsername="your-checkout-username"
      productKey="your-product-key"
      theme={{ plans: { planCards: { background: "#ffffff" } } }}
    />
  );
}

Props

Property	Type	Required	Default	Description
`checkoutUsername`	`string`	Yes	—	Checkout username from Settings → Checkout
`productKey`	`string`	Yes	—	Product identifier from the product page
`plansOnly`	`boolean`	No	`false`	Only subscription plans
`singlePurchasesOnly`	`boolean`	No	`false`	Only one-time purchases
`showTabHeader`	`boolean`	No	`true`	Tab header for plans vs single purchases
`theme`	`PricingTableTheme`	No	—	Per-instance theme override (merged with global `theme.pricingTable`)

If both plansOnly and singlePurchasesOnly are false or omitted, both plans and single purchases are shown.

Styling

Import global SDK styles once (for example in src/main.tsx, app/layout.tsx, or _app.tsx):

import "@metrifox/react-sdk/dist/styles.css";

This stylesheet is required for correct layout and components.

Theme configuration (supported shape)

Theming is driven by a single object passed to metrifoxInit:

metrifoxInit({
  clientKey: "...",
  theme: {
    customerPortal?: CustomerPortalTheme;
    pricingTable?: PricingTableTheme;
  },
});

Omitted keys fall back to SDK defaults. <CustomerPortal /> and <PricingTable /> may each take an optional theme prop to layer overrides for that instance only. Not supported on v2.0.0+: passing pricingTableTheme at the root of metrifoxInit, or the legacy flat customer portal / pricing table theme shapes. Those APIs are not honored in 2.x.

Customer Portal theme (`CustomerPortalTheme`)

Grouped by UI area; every field is optional.

Group	Role
`general`	Page: link color, background, radius, font, container padding
`tabs`	Tab bar: backgrounds, borders, active / inactive text
`sections`	Section cards: surfaces, typography, usage bars, empty states
`buttons`	Primary / secondary buttons
`lineItems`	Subscription line rows
`tables`	Data tables (e.g. billing history)
`modals`	Modal shell and actions
`plans`	Plan cards inside the portal: `currentPlanCard`, `planCards`, `planFeatures`, `planButton`, `planToggle`, `planTags`

Minimal example:

customerPortal: {
  general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
  tabs: {
    tabBackground: "#ffffff",
    tabBorderColor: "#e5e7eb",
    activeTabBackground: "#2563eb",
    activeTabTextColor: "#ffffff",
    inactiveTabTextColor: "#6b7280",
  },
  sections: {
    background: "#ffffff",
    content: { background: "#f4f4f5", borderRadius: "8px" },
    header: { fontSize: "16px", fontWeight: "600", color: "#52525b" },
    label: { fontSize: "13px", color: "#71717a" },
    value: { fontSize: "16px", color: "#52525b" },
  },
  buttons: {
    primary: {
      backgroundColor: "#2563eb",
      border: { radius: "8px" },
      typography: { color: "#ffffff" },
    },
    secondary: {
      backgroundColor: "#e4e4e7",
      typography: { color: "#3f3f46" },
    },
  },
  plans: {
    planCards: {
      background: "#ffffff",
      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
      header: { background: "#e5e7eb", textColor: "#111827" },
      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
      price: {
        amountColor: "#111827",
        primaryTextColor: "#6b7280",
        secondaryTextColor: "#9ca3af",
      },
    },
    planButton: { background: "#2563eb", textColor: "#ffffff" },
    planToggle: {
      background: "#e5e7eb",
      activeBackground: "#1f2937",
      activeText: "#ffffff",
      inactiveText: "#6b7280",
    },
  },
},

Font customization

Set customerPortal.general.fontFamily (or pricing-table-related tokens as documented in types) to any CSS font-family string. Your app must load the font (Google Fonts, @font-face, etc.) before or as the SDK mounts to avoid FOUT.

Pricing Table theme (`PricingTableTheme`)

Plan-related tokens live under plans (for example plans.planCards, plans.planToggle). Top-level plan keys are not supported.

Key	Purpose
`plans`	All plan UI: `currentPlanCard`, `planCards`, `planFeatures`, `planButton`, `planToggle`, `planTags`
`tabs`	Plans vs single-purchase tabs: `inactiveText`, `activeText`, `indicator`, `borderColor`
`checkoutBar`	Sticky checkout bar colors

Minimal example:

pricingTable: {
  plans: {
    planCards: {
      background: "#ffffff",
      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
      header: { background: "#e5e7eb", textColor: "#111827" },
      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
      price: {
        amountColor: "#111827",
        primaryTextColor: "#6b7280",
        secondaryTextColor: "#9ca3af",
      },
    },
    planButton: { background: "#2563eb", textColor: "#ffffff" },
    planToggle: {
      background: "#e5e7eb",
      activeBackground: "#1f2937",
      activeText: "#ffffff",
      inactiveText: "#6b7280",
    },
  },
  tabs: { activeText: "#2563eb", indicator: "#2563eb", borderColor: "#9ca3af" },
  checkoutBar: {
    background: "#f9fafb",
    borderColor: "#e5e7eb",
    textColor: "#3f3f46",
    buttonBackground: "#2563eb",
    buttonTextColor: "#ffffff",
  },
},

When Pricing Table is embedded in Customer Portal, plan styling follows theme.customerPortal.plans so portal and table stay consistent.

Full init example

import { metrifoxInit } from "@metrifox/react-sdk";

metrifoxInit({
  clientKey: "your-client-key",
  theme: {
    customerPortal: {
      general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
      tabs: {
        tabBackground: "#ffffff",
        activeTabBackground: "#2563eb",
        activeTabTextColor: "#ffffff",
        inactiveTabTextColor: "#6b7280",
      },
      sections: {
        background: "#ffffff",
        content: { background: "#f4f4f5", borderRadius: "8px" },
      },
      buttons: {
        primary: { backgroundColor: "#2563eb", typography: { color: "#ffffff" } },
      },
    },
    pricingTable: {
      plans: {
        planCards: {
          background: "#ffffff",
          border: { color: "#e5e7eb", radius: "8px" },
        },
        planButton: { background: "#2563eb", textColor: "#ffffff" },
      },
      tabs: { activeText: "#2563eb", indicator: "#2563eb" },
      checkoutBar: { buttonBackground: "#2563eb", buttonTextColor: "#ffffff" },
    },
  },
});

Per-widget overrides:

<CustomerPortal customerKey="..." theme={{ general: { linkColor: "#1d4ed8" } }} />
<PricingTable
  checkoutUsername="..."
  productKey="..."
  theme={{ plans: { planCards: { background: "#f8fafc" } } }}
/>

Changelog and support

Release history and breaking-change notes: SDK changelog.
Package README and issue trackers live on the public npm scope @metrifox/react-sdk.
Broader product docs: docs.metrifox.com.

Overview

SDKs

Documentation Index

​Installation

​Setup

​Widgets

​CustomerPortal

​Section configuration

​Built-in section keys

​Section anchors (deep links)

​PricingTable

​Props

​Styling

​Theme configuration (supported shape)

​Customer Portal theme (CustomerPortalTheme)

​Font customization

​Pricing Table theme (PricingTableTheme)

​Full init example

​Changelog and support

Installation

Setup

Widgets

`CustomerPortal`

Section configuration

Built-in section keys

Section anchors (deep links)

`PricingTable`

Props

Styling

Theme configuration (supported shape)

Customer Portal theme (`CustomerPortalTheme`)

Font customization

Pricing Table theme (`PricingTableTheme`)

Full init example

Changelog and support