@heymantle/polaris-web-react

React components for Shopify billing UIs using Polaris Web Components.

Installation

npm install @heymantle/polaris-web-react

Setup

Wrap your app with PolarisWebProvider to automatically load the required CDN scripts:

// _app.tsx or your app layout
import { PolarisWebProvider } from '@heymantle/polaris-web-react';

export default function App({ Component, pageProps }) {
  return (
    <PolarisWebProvider apiKey={process.env.NEXT_PUBLIC_SHOPIFY_API_KEY}>
      <Component {...pageProps} />
    </PolarisWebProvider>
  );
}

If you've already loaded the Polaris web component scripts via CDN in your _document.tsx, you can skip auto-injection:

<PolarisWebProvider skipScriptInjection>
  {/* ... */}
</PolarisWebProvider>

Components

PlansPage

Full-page plan selection with optional monthly/yearly toggle:

import { PlansPage } from '@heymantle/polaris-web-react';

export default function Plans() {
  const { customer, plans, subscribe } = useMantle();

  return (
    <PlansPage
      plans={plans}
      customer={customer}
      onSubscribe={async (plan, discount) => {
        const result = await subscribe({ planId: plan.id, discountId: discount?.id });
        if (result?.confirmationUrl) {
          window.location.href = result.confirmationUrl;
        }
      }}
      backUrl="/app"
      showIntervalToggle
    />
  );
}

PlanCard

Individual plan card:

import { PlanCard } from '@heymantle/polaris-web-react';

<PlanCard
  plan={plan}
  discount={discount}
  isRecommended
  onSelect={(plan) => console.log('Selected:', plan)}
/>

PlanCardStack

Grid of plan cards:

import { PlanCardStack } from '@heymantle/polaris-web-react';

<PlanCardStack
  plans={plans}
  customer={customer}
  interval="EVERY_30_DAYS"
  onSelectPlan={(plan) => console.log('Selected:', plan)}
/>

SubscriptionCard

Display current subscription status:

import { SubscriptionCard } from '@heymantle/polaris-web-react';

<SubscriptionCard
  subscription={customer.subscription}
  onChangePlan={() => navigate('/plans')}
  cancelSubscription={async () => {
    await cancelSubscription();
  }}
  onCancelled={() => {
    refetch();
  }}
/>

ChecklistCard

Progress checklist:

import { ChecklistCard } from '@heymantle/polaris-web-react';

<ChecklistCard
  title="Getting Started"
  steps={[
    { id: '1', name: 'Install the app', completed: true },
    { id: '2', name: 'Configure settings', completed: false },
    { id: '3', name: 'Add your first product', completed: false },
  ]}
  onToggleStep={(id, completed) => updateStep(id, completed)}
  showProgress
/>

BundleCard

Promote app bundles:

import { BundleCard } from '@heymantle/polaris-web-react';

<BundleCard
  title="Bundle and save!"
  apps={[
    {
      id: 'app1',
      name: 'Related App',
      description: 'Enhance your workflow',
      iconUrl: 'https://...',
      discountPercentage: 20,
      installUrl: 'https://...',
    },
  ]}
  onInstall={(app) => window.open(app.installUrl)}
/>

TypeScript

This package includes TypeScript declarations for both the components and the Polaris web components (s-* elements). The JSX types are automatically available when you import from this package.

Integration with @heymantle/react

This package works seamlessly with @heymantle/react for data management:

import { MantleProvider, useMantle } from '@heymantle/react';
import { PolarisWebProvider, PlansPage } from '@heymantle/polaris-web-react';

function App() {
  return (
    <MantleProvider appId="..." customerApiToken="...">
      <PolarisWebProvider>
        <PlansPage
          plans={plans}
          onSubscribe={handleSubscribe}
        />
      </PolarisWebProvider>
    </MantleProvider>
  );
}

License

MIT