MetriFox React SDK

A fully-configurable React SDK providing ready-to-use widgets for SaaS and billing platforms including customer portals, billing sections, and more.

Installation

# using npm
npm install @metrifox/react-sdk

# or pnpm
pnpm add @metrifox/react-sdk

# or yarn
yarn add @metrifox/react-sdk

Setup

Before using any SDK components, initialize it once with your Client key.

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 frameworks using React 18+.

Widgets

CustomerPortal

Displays a customizable customer dashboard with plans, subscriptions, billing, credits, and more.

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

const MyCustomPlan = ({ foo }) => <div>Custom Plan! 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 },
      ]}
    />
  )
}

Section Configuration

The sectionsConfig prop controls what appears in the portal.

| Property | Type | Description | | ----------- | ------------------------- | --------------------------------------------------- | | key | SectionKey | Unique key of the section (see list below) | | hidden | boolean | Hide this section when true | | component | React.ComponentType | Replace the default section with your own component | | props | Record<string, unknown> | Extra props passed to the custom or default section |

Built-in Section Keys

| Key | Description | | ------------------ | ----------------------------- | | upcomingInvoice | Displays next invoice details | | subscription | Active subscription overview | | walletBalance | Shows user wallet balance | | entitlementUsage | Displays resource usage | | paymentOverview | Payment summary and methods | | billingHistory | List of past transactions | | plan | Current plan details |

Section Anchors

Each portal section now renders inside a <section id="..."> wrapper so you can link directly to segments of a customer portal view. The default anchor IDs are:

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

Use these anchors when embedding the SDK or sharing deep links (e.g., https://app.example.com/portal#billing-history).

Pricing Table

Displays subscription plans and one-time purchases in a configurable pricing table component.

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

export default function PricingPage() {
  return( 
    <PricingTable 
      checkoutUsername="your-checkout-username" 
      productKey="your-product-key" 
    />
  )
}

Props

The props control how the pricing table is configured.

| Property | Type | Required | Default | Description | | --------------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------- | | checkoutUsername | string | Yes | — | Unique username used for checkout. This can be found in Settings → Checkout. | | productKey | string | Yes | — | Unique product identifier. This can be found on the product page. | | plansOnly | boolean | No | false | Controls whether only subscription plans are rendered. | | singlePurchasesOnly | boolean | No | false | Controls whether only single purchases are rendered. | | showTabHeader | boolean | No | true | Controls whether the tab header for switching between offerings is rendered. |

Note: If both plansOnly and singlePurchasesOnly are false or undefined, both plans and single purchases are displayed.

Styling

Import the SDK’s global styles into your app entry (e.g., src/index.tsx or _app.tsx):

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

This is required for proper styling of all widgets.

Pricing Table

The SDK accepts an optional pricingTableTheme object during initialization. This theme is applied to Pricing Table component and UI elements within it to match your brand styles.

Any values not provided will fall back to the default theme.

// Pricing table theme configuration
pricingTableTheme?: {
  card?: {
    background?: string
    borderColor?: string
    descriptionColor?: string

    header?: {
      background?: string
      textColor?: string
    }

    description?: {
      textColor?: string
      textButtonColor?: string
    }

    price?: {
      amountColor?: string
      primaryTextColor?: string
      secondaryTextColor?: string
      textButtonColor?: string
      background?: string
      borderColor?: string
    }
  }

  button?: {
    background?: string
    textColor?: string
    secondaryBackground?: string
    secondaryTextColor?: string
    textButtonColor?: string
  }

  featureList?: {
    textColor?: string
    iconColor?: string
  }

  tabs?: {
    inactiveText?: string
    activeText?: string
    indicator?: string
    borderColor?: string
  }

  intervalToggle?: {
    background?: string
    activeBackground?: string
    activeText?: string
    inactiveText?: string
  }

  currentSubscriptionCard?: {
    header?: {
      background?: string
      textColor?: string
    }
    gradientColor?: string
  }

  freeTrialTag?: {
    background?: string
    textColor?: string
  }

  checkoutBar?: {
    background?: string
    borderColor?: string
    textColor?: string
    buttonBackground?: string
    buttonTextColor?: string
  }
}

Example usage

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

const pricingTableTheme = {
  pricingTable: {
    card: {
      background: "#ffffff",
      price: {
        amountColor: "#111827",
        textButtonColor: "#2563eb",
      },
    },
    button: {
      background: "#2563eb",
    },
    tabs: {
      activeText: "#2563eb",
    },
  },
}

metrifoxInit({
  clientKey: "your-client-key",
  pricingTableTheme,
})

Local Development

Using yalc

For local SDK testing:

# In SDK project
pnpm build
npx yalc publish

# In consuming app
npx yalc add @metrifox/react-sdk
pnpm install

Auto-update during development

# In SDK project
pnpm dev:build   # watch & rebuild
pnpm dev:link    # re-publish build to yalc

# In consuming project
npx yalc update @metrifox/react-sdk

Clean up

npx yalc remove @metrifox/react-sdk
pnpm install

Support

📘 Full Documentation: For detailed guides, API references, and live examples, visit docs.metrifox.com.

📄 License

MIT © MetriFox