@schematichq/schematic-components

schematic-components

schematic-components provides client-side React components for customer portals, checkouts, and more using Schematic. It can be used in combination with schematic-react, or on its own.

Install

npm install @schematichq/schematic-components
# or
yarn add @schematichq/schematic-components
# or
pnpm add @schematichq/schematic-components

Usage

Import components and functions and compose them into your project.

import { EmbedProvider, SchematicEmbed, useEmbed } from '@schematichq/schematic-components';

See the Schematic documentation for a full guide on how to set up and use Schematic components.

Advanced Checkout Usage

We provide a function initializeWithPlan as an alternate entrypoint into a checkout flow. It's suitable for click handlers, and must be extracted from the library's embedded context.

const { initializeWithPlan } = useEmbed();

This function allows developers to create their own button that

• Pre-selects a Plan
• Pre-selects Add-ons (if available)
• Skips and hides plan selection stages

The initializeWithPlan function can be called with a Schematic plan ID, or with a more powerful BypassConfig object.

Providing a plan ID as a string will preselect that plan and skip the plan selection stage.

initializeWithPlan('plan_VBXv4bHjSf3');

Passing a config object allows pre-selecting Add-ons and pay-in-advance quantities, as well as hiding specific stages.

const config = {
  planId: 'plan_VBXv4bHjSf3',      // pre-select a Plan
  addOnIds: ['plan_AWv7bPjSx2'],   // pre-select 1 or more Add-ons
  period: 'month',                 // pre-select 'month' or 'year' for the billing period (optional)
  payInAdvanceQuantities: {        // pre-fill pay-in-advance quantities, keyed by feature id (optional)
    feat_cns2asuKAG2: 3,           // "feat_cns2asuKAG2" is a feature id, 3 is the quantity
  },
  promoCode: 'SUMMER20',           // pre-apply a Stripe promotion code (optional)
  showBillingDisclaimer: false,    // if false, hide the recurring billing disclaimer (optional)
  skipped: {
    planStage: true,               // if true, skip Plan selection
    addOnStage: true,              // if true, skip Add-on selection
    usageStage: true,              // if true, skip the pay-in-advance Quantity stage
    addOnUsageStage: true,         // if true, skip the add-on Quantity stage
  },
  hideSkipped: true,               // if true, hide skipped stages from breadcrumb navigation
};

initializeWithPlan(config);

payInAdvanceQuantities only applies to entitlements with pay-in-advance pricing; entries for other (or unknown) features are ignored. Combine it with skipped.usageStage / skipped.addOnUsageStage to send the customer straight to the final checkout step with the quantities already set.

promoCode pre-applies a discount to the checkout. It expects a Stripe promotion code — the customer-facing code such as SUMMER20, not the underlying coupon id. The discount is applied on load, so the previewed charges reflect it and it ships with the final checkout request.

showBillingDisclaimer controls the fine print under the checkout totals, e.g. "You will be billed $50.00 for this subscription every month on the 17th unless you unsubscribe." It is shown by default; set it to false when your own UI states the billing terms. Hiding it does not affect the scheduled-downgrade notice that appears in the same spot.

The Plans and Add-ons available to the checkout flows must be live in your Schematic account Catalog configuration.

Programmatic Unsubscribe

We provide a function requestUnsubscribe for starting the unsubscribe flow from your own UI, without using the built-in UnsubscribeButton. Like initializeWithPlan, it's suitable for click handlers and must be extracted from the library's embedded context.

const { requestUnsubscribe } = useEmbed();

This lets developers create their own button — for example, a custom "are you sure?" retention flow — that hands off to the same unsubscribe experience the built-in component uses.

requestUnsubscribe();

The function takes no arguments. If there is no active subscription to cancel, the request is ignored and a warning is logged to the console.

The unsubscribe flow is rendered by the embed itself, so a Schematic embed (the Viewport that hosts it) must be mounted on the page where you call requestUnsubscribe. This is the same requirement as initializeWithPlan.

License

MIT

Support

Need help? Please open a GitHub issue or reach out to [e-mail] and we'll be happy to assist.