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 API key (and optional base URL). 
import { metrifoxInit } from "@metrifox/react-sdk"

metrifoxInit({
  apiKey:
    process.env.NEXT_PUBLIC_METRIFOX_API_KEY ||
    process.env.REACT_APP_METRIFOX_API_KEY ||
    import.meta.env?.VITE_METRIFOX_API_KEY ||
    "your-api-key",
  // baseUrl: "https://api.example.com" // Optional (defaults to Metrifox Cloud)
})
Works with React, Next.js, and other frameworks using React 18+.

​
Core Widget: 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

​
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.

​
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.