Element Library

The Schematic Components library provides several advanced features for customizing and extending the default behavior.

Launch Checkout Programmatically

A common billing use case is to present a user with a paywall, and then open a checkout flow to quickly allow them to upgrade their plan.

Imagine a user is trying to create their 6th AI-generated image, but their current plan only includes 5 images per month. You can present them a paywall explaining they are at their limit and prove an “Upgrade to the Pro Plan” button. When they click the upgrade button, you can create a seamless upgrade experience by:

1. Opening the checkout flow
2. Pre-selecting the Pro plan they need to upgrade to

Here’s a barebones implementation of this:

1
"use client"
2
3
import {
4
  EmbedProvider,
5
  useEmbed,
6
} from "@schematichq/schematic-components";
7
import { useCallback, useEffect, useState } from "react";
8
9
function Checkout() {
10
  const { initializeWithPlan, layout, CheckoutDialog } = useEmbed();
11
12
  const checkout = useCallback(async () => {
13
    const response = await fetch("/api/accessToken");
14
    const result = await response.json();
15
    setAccessToken(result.accessToken);
16
    initializeWithPlan("plan_abc123");
17
  }, [setAccessToken, setLayout, setCheckoutState]);
18
19
  return (
20
    <>
21
      <button onClick={checkout}>Upgrade to Pro</button>
22
      {layout === "checkout" && <CheckoutDialog />}
23
    </>
24
  )
25
}
26
27
export default function CustomCheckout() {
28
  return (
29
    <EmbedProvider>
30
      <Checkout />
31
    </EmbedProvider>
32
  );
33
}

The key element is initializeWithPlan, an alternate entry point to the checkout flow. Above, we pass a plan ID to the function, which will pre-select the plan in the checkout flow.

In the above example, while the plan is pre-selected, the user will still be able to navigate the full checkout flow. A common desire is to take the user directly to the payment step, and remove the options to change plan or add-on choices. To achieve this, initializeWithPlan can be called with an object of additional options. The full set of options are below.

1
const config = {
2
  planId: 'plan_VBXv4bHjSf3',      // pre-select a Plan
3
  addOnIds: ['plan_AWv7bPjSx2'],   // pre-select 1 or more Add-ons
4
  skipped: {
5
    planStage: true,               // if true, skip Plan selection
6
    addOnStage: true               // if true, skip Add-on selection
7
  }
8
  hideSkipped:  true               // if true, hide skipped stages from breadcrumb navigation
9
};
10
11
initializeWithPlan(config);

Examples

You can see a full example, including error handling and loading states in our example app.

Check it out online: https://schematic-next-example.vercel.app/custom-checkout See the code: https://github.com/SchematicHQ/schematic-next-example/blob/main/src/app/custom-checkout/page.tsx