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
3. Taking them directly to the payment step

Here’s a barebones implementation of this:

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

The key difference here is that instead of rendering our component by default, we’re rendering it in reaction to a user action (clicking the “Upgrade to Pro” button). When this button is clicked:

1. We fetch an access token from our backend
2. Provide it to the component
3. Call setLayout("checkout"). layout determines which screen the checkout flow is currently on.
4. Because layout now has a value, the CheckoutDialog component will be rendered.

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

Additional Options

There are additional ways you can control the component state when programmatically launching. These are unlikely to be needed in most cases, but are documented here for completeness.

Control which component is rendered

In addition to the checkout flow, you can also load other parts of the Schematic Components library instead. To do this, you’ll set a different value in setLayout. The accepted values are: