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

Localization

The components render in English by default. EmbedProvider takes three props to change that:

<EmbedProvider
  accessToken={accessToken}
  i18n={i18next}
  translations={{ it: schematicIt }}
  locale="it-IT"
>

• locale is a BCP 47 tag. It picks the language the components read from and formats every number, currency, and date. Without it, the components use the i18n instance's current language, else en-US.
• i18n is your own i18next instance, v21 or later. The components read their strings from its schematic namespace in its current language, and re-render when you call changeLanguage. Nothing is fetched from your backend: the components look keys up and fall back to English for any they do not find.
• translations is a map of language to bundle, for an app without i18next. Any key a bundle leaves out falls back to English.

Keys are the English strings themselves, and the English bundle is exported as schematicTranslationsEn to translate from. The SchematicTranslations type checks a bundle's keys. A plural takes i18next's suffixes, looked up by the bare key and a count:

import type { SchematicTranslations } from '@schematichq/schematic-components';

export const schematicIt: SchematicTranslations = {
  'Cancel subscription': 'Annulla abbonamento',
  'Discount for months_one': '{{discount}} per il prossimo mese',
  'Discount for months_other': '{{discount}} per i prossimi {{count, number}} mesi',
};

With an i18n instance, register the same bundle under the schematic namespace:

i18next.addResourceBundle('it', 'schematic', schematicIt);

Passing both i18n and translations is unusual. If you do, the instance answers first, including through its own fallbackLng, so a key its English bundle has is never read from translations.

Numbers interpolated into a string are formatted for the locale before they reach it, so {{amount}} reads 20,000 or 20.000 on its own. A plural's count is the exception: it stays a number so i18next can pick the form, and the bundle formats it with {{count, number}}.

Feature names and their plural forms come from your Schematic account, not the bundle, so set them there in the language you need.

License

MIT

Support

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