Theming

Customize the Drop-in appearance to align with your brand. Pass a theme object when creating the instance.

Basic Usage

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  theme: {
    fontFamily: "Inter",
    borderRadius: "8px",
    accentColor: "#7c3aed"
  }
});

Theme Properties

Global Properties

Property	Type	Description
fontFamily	string	Font family (see approved fonts)
borderRadius	string	Border radius for buttons and inputs (e.g., "8px")
accentColor	string	Primary color for buttons and active states (e.g., "#7c3aed")

Text Properties

Control body text styling:

Property	Type	Description
text.primaryColor	string	Main text color
text.secondaryColor	string	Secondary text color for labels and hints
text.fontSize	string	Base font size (e.g., "16px")
text.fontWeight	string	Font weight (e.g., "400", "bold")

Title Properties

Control section heading styling:

Property	Type	Description
title.fontSize	string	Title font size
title.fontWeight	string	Title font weight

Approved Fonts

The following fonts are pre-loaded and approved:

• Roboto
• Montserrat
• Raleway
• Inter
• Noto Sans
• Open Sans
• Lato
• Nunito
• Work Sans

Other font values are ignored.

Font Weight Values

Accepted fontWeight values:

• Keywords: normal, bold, bolder, lighter
• Numeric: 100, 200, 300, 400, 500, 600, 700, 800, 900

Complete Example

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  theme: {
    fontFamily: "Inter",
    borderRadius: "12px",
    accentColor: "#7c3aed",
    text: {
      primaryColor: "#0f172a",
      secondaryColor: "#64748b",
      fontSize: "16px",
      fontWeight: "400"
    },
    title: {
      fontSize: "20px",
      fontWeight: "600"
    }
  }
});

TypeScript Type Definition

type DropinTheme = {
  fontFamily?:
    | "Roboto"
    | "Montserrat"
    | "Raleway"
    | "Inter"
    | "Noto Sans"
    | "Open Sans"
    | "Lato"
    | "Nunito"
    | "Work Sans";
  borderRadius?: string;
  accentColor?: string;
  text?: {
    primaryColor?: string;
    secondaryColor?: string;
    fontSize?: string;
    fontWeight?:
      | "normal"
      | "bold"
      | "bolder"
      | "lighter"
      | "100" | "200" | "300" | "400" | "500" | "600" | "700" | "800" | "900";
  };
  title?: {
    fontSize?: string;
    fontWeight?:
      | "normal"
      | "bold"
      | "bolder"
      | "lighter"
      | "100" | "200" | "300" | "400" | "500" | "600" | "700" | "800" | "900";
  };
};

Validation Behavior

Theme properties are validated at initialization. Invalid or unknown properties are silently ignored — the Drop-in renders normally using default values for invalid entries.

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  theme: {
    fontFamily: "Comic Sans",  // Ignored — fallback to default
    borderRadius: "8px",       // Applied
    unknownProp: "value"       // Ignored — unknown property
  }
});
// Renders with borderRadius: "8px" and default fontFamily

No CSS Variables

Custom CSS properties (CSS variables like var(--my-color)) are not supported in theme values.

Highlighting Payment Methods

Display a custom tag (a label with an optional background color) on specific payment methods to draw attention to them. A common use case is flagging the method a returning customer used last, so they can find it at a glance. Pass a highlightMethods array when creating the instance. This is a top-level option, not part of the theme object.

Look up the customer's previous payment method from your backend, then tag it:

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  highlightMethods: [
    // The method the customer used on their last order, from your records.
    { method: "creditcard", label: "Last used", color: "#bbf7d0" }
  ]
});

Highlight Properties

Property	Type	Required	Description
method	string	Yes	Method identifier to match (e.g. "creditcard")
partner	string	No	Partner identifier to match (e.g. "paypal")
label	string	Yes	Free text shown in the tag
color	string	No	Any valid CSS color for the tag background

Matching Rules

• A method is highlighted when its method matches. When partner is set, both partner and method must match. When partner is omitted, every partner exposing that method is highlighted.
• Secondary methods (vouchers, gift cards, loyalty) are grouped by method, so their highlight matches on method only and ignores partner.
• When color is set, a readable text color in the same hue is derived automatically: a light tint on dark tags, a dark shade on light tags. When color is omitted, the tag uses the default theme style.
• Methods absent from highlightMethods are unaffected. Highlighting does not change the display order, which stays driven by the session configuration.

Scope

Highlight tags apply to the Drop-in payment method list. Express buttons (Apple Pay, Google Pay) and the standalone PayPal button are not tagged.

The same array can be passed to setConfig to update the tags on a mounted instance.

Next Steps

• Events — Handle Drop-in lifecycle events
• API Reference — Complete API documentation