MantleProvider

<MantleProvider> is a component which uses the React Context API to wrap your application, making it easy to access customer data, plans, and actions throughout your app. Think of it as the central hub that makes Mantle's functionality available to all your React components.

Wrapping your app

The provider should wrap the parts of your app that need access to Mantle data:

import { MantleProvider } from '@heymantle/react';

function App() {
  return (
    <MantleProvider
      appId={process.env.MANTLE_APP_ID}
      customerApiToken={shop.mantleApiToken}
    >
      {children}
    </MantleProvider>
  );
}

Once the provider is set up, child components can access Mantle data and actions through the useMantle hook. Most apps will want to wrap their entire frontend with MantleProvider to ensure consistent access to customer data throughout the application.

Available data and callbacks

MantleProvider gives you access to the same data and functionality as MantleClient, but with the convenience of React's context system. Through the useMantle hook, you can access:

Data properties

Property	Description
`customer`	Customer details including subscription status, features, usage metrics and custom fields
`subscription`	Current active subscription details
`plans`	List of available plans the customer can subscribe to
`loading`	Boolean indicating if customer data is currently loading
`client`	The underlying MantleClient object if needed

Callback functions

Function	Description	Equivalent API
`refetch()`	Refresh all customer data	GET /v1/customer
`sendUsageEvent({ eventName, properties })`	Record a usage event for the customer	POST /v1/usage_events
`getUsageReport({ id, period })`	Retrieve usage data for a specific metric	GET /v1/usage_metrics/:id/report
`subscribe({ planId, discountId, returnUrl })`	Subscribe customer to a new plan	POST /v1/subscriptions
`cancelSubscription()`	Cancel the current subscription	DELETE /v1/subscriptions
`isFeatureEnabled({ featureKey })`	Check if a specific feature is enabled	Feature verification logic based on customer data
`limitForFeature({ featureKey })`	Get the limit value for a specific feature	Limit lookup based on customer data
`createHostedSession({ type })`	Create a hosted billing session	Creates a session for Hosted Billing

useMantle() hook

The useMantle() hook allows you to access properties and actions which are surfaced by the MantleProvider's context from within any functional React component:

import { useMantle } from '@heymantle/react';

function MyComponent() {
  const {
    customer, // Access the current customer
    plans, // access the plans the customer can subscribe to
  } = useMantle();
  
  // Example: Subscribe to a new plan and present charge screen
  const handleSubscribe = async () => {
    const newSubscription = await mantle.subscribe({ 
      planId: 'plan-id', 
      discountId: 'discount-id', 
      returnUrl: 'settings' 
    });
    window.open(newSubscription.confirmationUrl, '_top');
  };
  
  // Example: Check if a feature is enabled
  const canUseAdvancedFeature = mantle.isFeatureEnabled({ featureKey: 'advanced_feature' });
  
  // ... rest of your component
}

For detailed information on data properties and complete API reference, check out the @heymantle/react project documentation.