Skip to main content

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

PropertyTypeDescription
fontFamilystringFont family (see approved fonts)
borderRadiusstringBorder radius for buttons and inputs (e.g., "8px")
accentColorstringPrimary color for buttons and active states (e.g., "#7c3aed")

Text Properties

Control body text styling:

PropertyTypeDescription
text.primaryColorstringMain text color
text.secondaryColorstringSecondary text color for labels and hints
text.fontSizestringBase font size (e.g., "16px")
text.fontWeightstringFont weight (e.g., "400", "bold")

Title Properties

Control section heading styling:

PropertyTypeDescription
title.fontSizestringTitle font size
title.fontWeightstringTitle 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.

Next Steps