Skip to main content

​
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_CLIENT_KEY ||
    process.env.REACT_APP_METRIFOX_CLIENT_KEY ||
    import.meta.env?.VITE_METRIFOX_CLIENT_KEY ||
    "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.
PropertyTypeDescription
keySectionKeyUnique key of the section (see list below)
hiddenbooleanHide this section when true
componentReact.ComponentTypeReplace the default section with your own component
propsRecord<string, unknown>Extra props passed to the custom or default section

​
Built-in Section Keys

KeyDescription
upcomingInvoiceDisplays next invoice details
subscriptionActive subscription overview
walletBalanceShows user wallet balance
entitlementUsageDisplays resource usage
paymentOverviewPayment summary and methods
billingHistoryList of past transactions
planCurrent plan details

​
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.
PropertyTypeRequiredDefaultDescription
checkoutUsernamestringYes—Unique username used for checkout. This can be found in Settings → Checkout.
productKeystringYes—Unique product identifier. This can be found on the product page.
plansOnlybooleanNofalseControls whether only subscription plans are rendered.
singlePurchasesOnlybooleanNofalseControls whether only single purchases are rendered.
showTabHeaderbooleanNotrueControls whether the tab header for switching between offerings is rendered.
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.

​
Widget Styling

The SDK accepts an optional theme object during initialization. This theme is applied to Widgets and UI elements within them to match your brand styles. Any values not provided will fall back to the default theme. 
theme?: {
  customerPortal?: CustomerPortalTheme
  pricingTable?: PricingTableTheme
}

// Customer portal theme configuration
customerPortalTheme?: {
  tabs?: {
    background?: string
    borderColor?: string
    activeBackground?: string
    activeTextColor?: string
    inactiveTextColor?: string
  }

  section?: {
    background?: string
    titleTextColor?: string
    contentBackground?: string
    iconBackground?: string
    iconColor?: string
    emptyTextColor?: string
  }

  card?: {
    titleBackground?: string
    contentBackground?: string
    titleColor?: string
    details?: {
      labelColor?: string
      valueColor?: string
    }
  }

  subscription?: {
    items?: {
      background?: string
      borderColor?: string
      textColor?: string
    }
  }

  table?: {
    headerTextColor?: string
    textcolor?: string
  }

  button?: {
    background?: string
    textColor?: string
  }

  filter?: {
    border?: string
    activeBackground?: string
    inactiveBackground?: string
    activeTextColor?: string
    inactiveTextColor?: string
    countBackground?: string
    countTextColor?: string
  }

  linkColor?: string
}

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

const customerPortalTheme = {
  tabs: {
    background: "#111827",
    borderColor: "#243044",
  },

  section: {
    background: "#020617",
  },

  card: {
    titleColor: "#F9FAFB",
    details: {
      labelColor: "#CBD5E1",
      valueColor: "#FFFFFF",
    },
  },
}

const theme = {
  customerPortal: customerPortalTheme,
  pricingTableTheme: pricingTableTheme,
}


metrifoxInit({
  clientKey: "your-client-key",
  theme,
  pricingTableTheme, // deprecated - Moved to `theme.pricingTable`
})

​
Upcoming Widgets

While the CustomerPortal is available today, we are also building additional widgets tailored to billing sections, feature flags, and usage dashboards. They’ll drop progressively, so keep an eye on the changelog for the latest releases and timelines.
See SDKs/changelog for the latest version notes and widget rollouts.