Elements Appearance API

Customize the look and feel of Elements to match the design of your site.

Stripe Elements supports visual customization, which allows you to match the design of your site with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.

1. Pick a prebuilt theme that most closely resembles your website.
2. Customize the theme using inputs and labels . You can also set variables , such as the fontFamily and colorPrimary to broadly customize components appearing throughout each Element.
3. If needed, fine-tune individual components and states using rules .

For complete control, specify custom CSS properties for individual components appearing in the Element.

Note

The Elements Appearance API doesn’t support individual payment method Elements (such as CardElement). Use the Style object to customize your Element instead.

Customer location

Layout

Themes

Start customizing Elements by selecting one of the following themes:

• stripe
• night
• flat

const appearance = {
 theme: 'night'
};

// Pass the appearance object when initializing checkout
const checkout = stripe.initCheckoutElementsSdk({clientSecret, elementsOptions: {appearance}});

Inputs and labels

Customize the appearance of input fields and their associated labels.

Layout

Inputs

Labels

Checkout.js

const appearance = {
 inputs: 'spaced',
 labels: 'auto'
}

Inputs

Choose the style of input fields to suit your design.

Labels

Control the position and visibility of labels associated with input fields.

Variables

Set variables to affect the appearance of many components appearing throughout each Checkout element.

The variables option works like CSS variables. You can specify CSS values for each variable and reference other appearance variables with the var(--myVariable) syntax. You can even inspect the resulting DOM using the DOM explorer in your browser.

Note

The colorPrimary, colorBackground, colorText, colorSuccess, colorDanger, and colorWarning variables don’t support rgba() or the var(--myVariable) syntax.

const appearance = {
 theme: 'stripe',

 variables: {
 colorPrimary: '#0570de',
 colorBackground: '#ffffff',
 colorText: '#30313d',
 colorDanger: '#df1b41',
 fontFamily: 'Ideal Sans, system-ui, sans-serif',
 spacingUnit: '2px',
 borderRadius: '4px',
 // See all possible variables below
 }
};

// Pass the appearance object when initializing checkout
const checkout = stripe.initCheckoutElementsSdk({clientSecret, elementsOptions: {appearance}});

Commonly used variables

Less commonly used variables

Rules

The rules option is a map of CSS-like selectors to CSS properties, allowing more customization of individual components. After defining your theme and variables, use rules to integrate the UI to match the design of your site.

const appearance = {
 rules: {
 '.Tab': {
 border: '1px solid #E0E6EB',
 boxShadow: '0px 1px 1px rgba(0, 0, 0, 0.03), 0px 3px 6px rgba(18, 42, 66, 0.02)',
 },

 '.Tab:hover': {
 color: 'var(--colorText)',
 },

 '.Tab--selected': {
 borderColor: '#E0E6EB',
 boxShadow: '0px 1px 1px rgba(0, 0, 0, 0.03), 0px 3px 6px rgba(18, 42, 66, 0.02), 0 0 0 2px var(--colorPrimary)',
 },

 '.Input--invalid': {
 boxShadow: '0 1px 1px 0 rgba(0, 0, 0, 0.07), 0 0 0 2px var(--colorDanger)',
 },

 // See all supported class names and selector syntax below
 }
 };

// Pass the appearance object when initializing checkout
const checkout = stripe.initCheckoutElementsSdk({clientSecret, elementsOptions: {appearance}});

All rules

The selector for a rule can target any of the public class names in the UI, and the supported states, pseudo-classes, and pseudo-elements for each class. For example, the following are valid selectors:

• . Tab,. Label,. Input
• . Tab:focus
• . Input--invalid,. Label--invalid
• . Input::placeholder

The following are not valid selectors:

• . p-SomePrivateClass, img , only public class names can be targeted
• . Tab. TabLabel , ancestor-descendant relationships in selectors are unsupported
• . Tab--invalid , the . Tab class doesn’t support the --invalid state

Each class name used in a selector supports an allowlist of CSS properties, that you specify using camel case (for example, boxShadow for the box-shadow property).

The following is the complete list of supported class names and corresponding states, pseudo-classes, and pseudo-elements.

Tabs

Inputs (above labels)

Make sure that you choose a font size of at least 16px for input fields on mobile.

Inputs (floating labels)

Note

You can enable floating labels as an additional configuration option.

Block

Code Input

Checkbox

Dropdown

Note

Dropdown styling is limited on macOS. The appearance API for dropdowns primarily affects Windows systems. On macOS, you can’t style system dropdowns, such as the country selector, using these rules because of operating system restrictions.

Switch

Picker

Make sure your .PickerItem active state stands out from the other states.

Menu

Accordion

Payment Method Messaging Element

Radio Icon

You can control the overall size of the icon with the width property on .RadioIcon. You can control the relative size of .RadioIconInner with the r (radius) property. .RadioIconOuter and .RadioIconInner are SVG elements and can be styled with stroke and fill properties. See the full list of supported CSS properties below.

const appearance = {
 rules: {
 '.RadioIcon': {
 width: '24px'
 },
 '.RadioIconOuter': {
 stroke: '#E0E6EB'
 },
 '.RadioIconInner': {
 r: '16'
 }
 }
};

Toggle

Supported CSS properties

Other configuration options

In addition to themes, labels, inputs, variables and rules, you can style Elements using other appearance configuration options.

You can customize these by adding them to the appearance object:

const appearance = {
 disableAnimations: true,

 // other configurations such as `theme`, `labels`, `inputs`, `variables` and `rules`...
}

We currently support the below options: