Appearance customization
Use the appearance parameter to customize the visual and layout of the payment page, including theme selection, layout configuration, and CSS style customization.
Web/WAP
iOS
Android
Flutter
- Start by picking a theme.
Get started with pre-built themes; choose the one that best matches your website or application. - Choose your preferred layout mode.
Choose between two layout modes: Accordion and Tab.
- Use CSS variables to fine-tune components.
If needed, you can specify custom CSS properties for individual component within Payment Element.
- Customize card brand style.
If needed, you can configure whether to display card brand icons using the card parameter.
The following is a sample code for configuring the appearance of Payment Element using the appearance parameter:
// For npm users (TypeScript), import enums. Omit this import for CDN or JS only usage.
import { AMSElement, ThemeType, PaymentElementLayout } from '@alipay/ams-checkout';
// Option 1: Use string values (CDN, npm/JavaScript, or npm/TypeScript)
elementPayment.mount({
type: 'payment',
appearance: {
theme: 'night', // String value
layout: { type: 'accordion' }, // String value
variables: { ... },
card: {
showBrandIcon: false
}
}
}, '#payment-element');
/*
Option 2: Use enums（Only applicable to npm + TypeScript）
*/
// elementPayment.mount({
// type: 'payment',
// appearance: {
// theme: ThemeType.Night, // TypeScript enum
// layout: { type: PaymentElementLayout.Accordion }, // TypeScript enum
// variables: { ... },
// card: {
// showBrandIcon: false
// }
// }
// }, '#payment-element');Theme
Payment Element provides six preset themes. You can use JavaScript (for CDN or npm) or a TypeScript enum (npm only) to configure the theme property in the appearance parameter to select a theme. Valid values are:
- default: Default theme (light)
- night: Night
- nostalgicGray: Nostalgic gray
- agateGreen: Agate green
- cherryBlossomPink: Cherry blossom pink
- gamingPurple: Gaming purple
The following are the visualization and sample codes for each theme:
Default theme (light)
Night
Nostalgic gray
Agate green
Cherry blossom pink
Gaming purple
appearance: { theme: 'default' }
// TypeScript enum: theme: ThemeType.Default
appearance: { theme: 'night' }
// TypeScript enum: theme: ThemeType.Night
appearance: { theme: 'nostalgicGray' }
// TypeScript enum: theme: ThemeType.NostalgicGray
appearance: { theme: 'agateGreen' }
// TypeScript enum: theme: ThemeType.AgateGreen
appearance: { theme: 'cherryBlossomPink' }
// TypeScript enum: theme: ThemeType.CherryBlossomPink
appearance: { theme: 'gamingPurple' }
// TypeScript enum: theme: ThemeType.GamingPurpleLayout
Payment Element supports two layout modes: Accordion and Tabs. You can configure the appearance.layout object using JavaScript (for CDN or npm) or a TypeScript enum (npm only). Valid values are:
- accordion: Default value, Accordion mode. Payment options are stacked vertically into collapsible sections. Each section title is always visible, and clicking it expands the section to display its content.
- showRadio: Boolean type. The default value is true. Used to control whether radio buttons are displayed in the payment list under the accordion layout.
- tabs: Tabs mode. Payment options are arranged in horizontal tabs, and clicking the tab switches the content.
The following are the visualization and sample codes for these two modes:
Accordion
Tabs
appearance: {
layout: { type: 'accordion' } ,
accordion: {
showRadio: false // Hide radio buttons, defaults to true
}
// TypeScript enum: layout: { type: PaymentElementLayout.Accordion }
appearance: {
layout: { type: 'tabs' }
}
// TypeScript enum: layout: { type: PaymentElementLayout.Tabs }CSS variables
Payment Element supports fine‑grained customization of visual components via CSS, including styles for borders, backgrounds, text, and icons. To customize styles, you need to pass CSS variables through the variables parameter.
The following is a reference list of supported CSS variables and their default values. You can override these variables in your CSS code according to your branding requirements.
Color variables
Size variables
Color variables are used to define the overall visual color scheme of payment elements, covering aspects such as content, background, borders, actions, and states.
Content color
Background color
Border color
Action button color
State color
Size variables define the shape and spatial relationships of payment elements, including settings for border radius, wrapper, and stroke.
Border radius settings
Wrapper settings
Stroke settings
Below is a reference list of supported CSS variables and their default values. You can override the values of these variables in your CSS code according to your brand requirements.
Sample
const appearance = {
theme: "default",
layout: { type: "Accordion" },
variables: {
"content-primary": "#2a3a52",
"content-secondary": "#7c8ca3",
"content-tertiary": "#abb9cc",
"content-quaternary": "#ffffff",
"background-primary": "#ffffff",
"background-secondary": "#f9fafb",
"background-disable": "#fcfcfc",
"background-transparency": "#0000000a",
"border-primary": "#cfd8e5",
"border-secondary": "#ebebeb",
"border-disable": "#f5f5f5",
"action-normal": "#1650ff",
"action-hover": "#5c85ff",
"action-disable": "#a2b9ff",
"action-secondary": "#f3f6ff",
"state-failure": "#ff5b4d",
"state-warning": "#ff9f1a",
"state-success": "#00b277",
"state-info": "#6092d8",
"state-marketing": "#ff6060",
"state-conventional": "#7c8ca3",
"radius-backup": "4px",
"radius-module": "12px",
"radius-component": "8px",
"radius-button": "12px",
"wrapper-padding": "24px",
"stroke-default": "0.5px",
"stroke-active": "1px",
},
};The following illustrations show how to customize different interface styles using CSS variables:
Accordion layout mode
Tabs layout mode
Payment info collection page
Card payment page
Digital wallet payment page
Address module
Pop-up window
Other (virtual account) page
Customize card brand style
In card payment scenarios, the display of card brand icons may affect the visual style and interactive experience of card information collection. Depending on your business scenario's UI guidelines or brand consistency requirements, you may need flexible control over whether to display these icons on the payment page. For example, if you want to simplify interface elements, avoid visual distractions, or have already integrated your own card brand recognition functionality, you can choose to hide the default icons. Conversely, if you need to clearly indicate supported card brands, you can maintain the default display to enhance buyer trust.
Through the card.showBrandIcon parameter in appearance, you can quickly control the visibility of card brand icons. Valid values are:
- true: Default value. Card brand icons are displayed on the payment page.
- false: The payment page only displays text input areas without any card brand icons.
Below are visual demonstrations and sample codes for configuring card brand display using the card.showBrandIcon parameter:
Display card brand icons
Hide card brand icons
Use the default value of the card.showBrandIcon parameter or set it to
true
to display card brand icons on the payment page.
{
appearance: {
card: {
showBrandIcon: true
}
}
}Set the card.showBrandIcon parameter to
false
. The payment page will only display plain text input areas without any card brand icons.
{
appearance: {
card: {
showBrandIcon: false
}
}
}- Start by picking a theme.
Get started with pre-built themes; choose the one that best matches your website or application. - Choose your preferred layout mode.
Choose between two layout modes: Accordion and Tab.
- Use CSS variables to fine-tune components.
If needed, you can specify custom CSS properties for individual component within Payment Element.
Theme
Payment Element provides six preset themes. You can select a theme by passing a JSON string containing the theme property to the appearance configuration. Valid values are:
- "default": Default theme (light)
- "night": Night
- "nostalgicGray": Nostalgic gray
- "agateGreen": Agate green
- "cherryBlossomPink": Cherry blossom pink
- "gamingPurple": Gaming purple
The following are the visualization and sample codes for each theme:
Default theme (light)
Night
Nostalgic gray
Agate green
Cherry blossom pink
Gaming purple
AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "default"
// }
// == >
// @"{\"theme\": \"default\"}"
NSString *appearance = @"{\"theme\": \"default\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "night"
// }
// == >
// @"{\"theme\": \"night\"}"
NSString *appearance = @"{\"theme\": \"night\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "nostalgicGray"
// }
// == >
// @"{\"theme\": \"nostalgicGray\"}"
NSString *appearance = @"{\"theme\": \"nostalgicGray\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "agateGreen"
// }
// == >
// @"{\"theme\": \"agateGreen\"}"
NSString *appearance = @"{\"theme\": \"agateGreen\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "cherryBlossomPink"
// }
// == >
// @"{\"theme\": \"cherryBlossomPink\"}"
NSString *appearance = @"{\"theme\": \"cherryBlossomPink\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "gamingPurple"
// }
// == >
// @"{\"theme\": \"gamingPurple\"}"
NSString *appearance = @"{\"theme\": \"gamingPurple\"}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;Layout
Payment Element supports two layout modes: Accordion and Tabs. You can set the layout mode by defining the type property of the layout object in the appearance configuration JSON string. Valid values are:
- "Accordion": Default value, Accordion mode. Payment options are stacked vertically into collapsible sections. Each section title is always visible, and clicking it expands the section to display its content.
- "Tabs": Tabs mode. Payment options are arranged in horizontal tabs, and clicking the tab switches the content.
The following are the visualization and sample codes for these two modes:
Accordion
Tabs
AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "default",
// "layout": {
// "type": "Accordion"
// }
// }
// == >
// @"{\"theme\": \"default\",\"layout\": {\"type\": \"Accordion\"}}"
NSString *appearance = @"{\"them\": \"default\",\"layout\": {\"type\": \"Accordion\"}}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;AMSPaymentElementConfiguration *componentConfig = [AMSPaymentElementConfiguration new];
// Convert the JSON into a JSON string.
// {
// "theme": "default",
// "layout": {
// "type": "tabs"
// }
// }
// == >
// @"{\"theme\": \"default\",\"layout\": {\"type\": \"tabs\"}}"
NSString *appearance = @"{\"theme\": \"default\",\"layout\": {\"type\": \"tabs\"}}";
NSDictionary *options = @{ @"appearance": appearance };
componentConfig.options = options;CSS variables
Payment Element supports fine‑grained customization of visual components via CSS, including styles for borders, backgrounds, text, and icons. To customize styles, you need to pass CSS variables through the variables parameter.
The following is a reference list of supported CSS variables and their default values. You can override these variables in your CSS code according to your branding requirements.
Color variables
Size variables
Color variables are used to define the overall visual color scheme of payment elements, covering aspects such as content, background, borders, actions, and states.
Content color
Background color
Border color
Action button color
State color
Size variables define the shape and spatial relationships of payment elements, including settings for border radius, wrapper, and stroke.
Border radius settings
Wrapper settings
Stroke settings
Below is a reference list of supported CSS variables and their default values. You can override the values of these variables in your CSS code according to your brand requirements.
Sample
NSString *appearance = @"{\
\n \"theme\": \"default\",\
\n \"layout\": {\
\n \"type\": \"Accordion\"\
\n },\
\n \"variables\": {\
\n \"content-primary\": \"#2a3a52\",\
\n \"content-secondary\": \"#7c8ca3\",\
\n \"content-tertiary\": \"#abb9cc\",\
\n \"content-quaternary\": \"#ffffff\",\
\n\
\n \"background-primary\": \"#ffffff\",\
\n \"background-secondary\": \"#f9fafb\",\
\n \"background-disable\": \"#fcfcfc\",\
\n \"background-transparency\": \"#0000000a\",\
\n\
\n \"border-primary\": \"#cfd8e5\",\
\n \"border-secondary\": \"#ebebeb\",\
\n \"border-disable\": \"#f5f5f5\",\
\n\
\n \"action-normal\": \"#1650ff\",\
\n \"action-hover\": \"#5c85ff\",\
\n \"action-disable\": \"#a2b9ff\",\
\n \"action-secondary\": \"#f3f6ff\",\
\n\
\n \"state-failure\": \"#ff5b4d\",\
\n \"state-warning\": \"#ff9f1a\",\
\n \"state-success\": \"#00b277\",\
\n \"state-info\": \"#6092d8\",\
\n \"state-marketing\": \"#ff6060\",\
\n \"state-conventional\": \"#7c8ca3\",\
\n\
\n \"radius-backup\": \"4px\",\
\n \"radius-module\": \"12px\",\
\n \"radius-component\": \"8px\",\
\n \"radius-button\": \"12px\",\
\n\
\n \"wrapper-padding\": \"24px\",\
\n\
\n \"stroke-default\": \"0.5px\",\
\n \"stroke-active\": \"1px\"\
\n }\
\n}";The following illustrations show how to customize different interface styles using CSS variables:
Accordion layout mode
Tabs layout mode
Payment info collection page
Card payment page
Digital wallet payment page
Address module
Pop-up window
Other (virtual account) page
- Start by picking a theme.
Get started with pre-built themes; choose the one that best matches your website or application. - Choose your preferred layout mode.
Choose between two layout modes: Accordion and Tab.
- Use CSS variables to fine-tune components.
If needed, you can specify custom CSS properties for individual component within Payment Element.
Theme
Payment Element provides six preset themes. You can set the theme property of the appearance configuration object by constructing a JSON string to select a theme. Valid values are：
- "default": Default theme (light)
- "night": Night
- "nostalgicGray": Nostalgic gray
- "agateGreen": Agate green
- "cherryBlossomPink": Cherry blossom pink
- "gamingPurple": Gaming purple
The following are the visualization and sample codes for each theme:
Default theme (light)
Night
Nostalgic gray
Agate green
Cherry blossom pink
Gaming purple
AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"default\"}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"night\"}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"nostalgicGray\"}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"agateGreen\"}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"cherryBlossomPink\"}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"gamingPurple\"}";
configuration.setOption("appearance", appearance);Layout
Payment Element supports two layout modes: Accordion and Tabs. Set the layout by constructing a JSON string and assigning a valid value to the type field in the layout object. Valid values are:
- "Accordion": Default value, Accordion mode. Payment options are stacked vertically into collapsible sections. Each section title is always visible, and clicking it expands the section to display its content.
- "Tabs": Tabs mode. Payment options are arranged in horizontal tabs, and clicking the tab switches the content.
The following are the visualization and sample codes for these two modes:
Accordion
Tabs
AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme\":\"night\",\"layout\":{\"type":\"Accordion\"}}";
configuration.setOption("appearance", appearance);AMSPaymentElementConfiguration configuration = new AMSPaymentElementConfiguration();
String appearance = "{\"theme":\"night\",\"layout\":{\"type\":\"Tabs\"}}";
configuration.setOption("appearance", appearance);CSS variables
Payment Element supports fine‑grained customization of visual components via CSS, including styles for borders, backgrounds, text, and icons. To customize styles, you need to pass CSS variables through the variables parameter.
The following is a reference list of supported CSS variables and their default values. You can override these variables in your CSS code according to your branding requirements.
Color variables
Size variables
Color variables are used to define the overall visual color scheme of payment elements, covering aspects such as content, background, borders, actions, and states.
Content color
Background color
Border color
Action button color
State color
Size variables define the shape and spatial relationships of payment elements, including settings for border radius, wrapper, and stroke.
Border radius settings
Wrapper settings
Stroke settings
Below is a reference list of supported CSS variables and their default values. You can override the values of these variables in your CSS code according to your brand requirements.
Sample
String appearance =
"{\n" +
" \"theme\": \"default\",\n" +
" \"layout\": {\n" +
" \"type\": \"Accordion\"\n" +
" },\n" +
" \"variables": {\n" +
" \"content-primary\": \"#2a3a52\",\n" +
" \"content-secondary\": \"#7c8ca3\",\n" +
" \"content-tertiary\": \"#abb9cc\",\n" +
" \"content-quaternary\": \"#ffffff\",\n" +
"\n" +
" \"background-primary\": \"#ffffff\",\n" +
" \"background-secondary\": \"#f9fafb\",\n" +
" \"background-disable\": \"#fcfcfc\",\n" +
" \"background-transparency\": \"#0000000a\",\n" +
"\n" +
" \"border-primary\": \"#cfd8e5\",\n" +
" \"border-secondary\": \"#ebebeb\",\n" +
" \"border-disable\": \"#f5f5f5\",\n" +
"\n" +
" \"action-normal\": \"#1650ff\",\n" +
" \"action-hover\": \"#5c85ff\",\n" +
" \"action-disable\": \"#a2b9ff\",\n" +
" \"action-secondary\": \"#f3f6ff\",\n" +
"\n" +
" \"state-failure\": \"#ff5b4d\",\n" +
" \"state-warning\": \"#ff9f1a\",\n" +
" \"state-success\": \"#00b277\",\n" +
" \"state-info\": \"#6092d8\",\n" +
" \"state-marketing\": \"#ff6060\",\n" +
" \"state-conventional\": \"#7c8ca3\",\n" +
"\n" +
" \"radius-backup\": \"4px\",\n" +
" \"radius-module\": \"12px\",\n" +
" \"radius-component\": \"8px\",\n" +
" \"radius-button\": \"12px\",\n" +
"\n" +
" \"wrapper-padding\": \"24px\",\n" +
"\n" +
" \"stroke-default\": \"0.5px\",\n" +
" \"stroke-active\": \"1px\"\n" +
" }\n" +
"}";The following illustrations show how to customize different interface styles using CSS variables:
Accordion layout mode
Tabs layout mode
Payment info collection page
Card payment page
Digital wallet payment page
Address module
Pop-up window
Other (virtual account) page
- Start by picking a theme.
Get started with pre-built themes; choose the one that best matches your website or application. - Choose your preferred layout mode.
Choose between two layout modes: Accordion and Tab.
- Use CSS variables to fine-tune components.
If needed, you can specify custom CSS properties for individual component within Payment Element.
Theme
Payment Element provides six preset themes. You can set the theme property of the appearance configuration object by constructing a JSON string to select a theme. Valid values are：
- "default": Default theme (light)
- "night": Night
- "nostalgicGray": Nostalgic gray
- "agateGreen": Agate green
- "cherryBlossomPink": Cherry blossom pink
- "gamingPurple": Gaming purple
The following are the visualization and sample codes for each theme:
Default theme (light)
Night
Nostalgic gray
Agate green
Cherry blossom pink
Gaming purple
Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"default\"}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"night\"}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"nostalgicGray\"}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"agateGreen\"}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"cherryBlossomPink\"}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": "{\"theme\":\"gamingPurple\"}",
};Layout
Payment Element supports two layout modes: Accordion and Tabs. Set the layout by constructing a JSON string and assigning a valid value to the type field in the layout object. Valid values are:
- "Accordion": Default value, Accordion mode. Payment options are stacked vertically into collapsible sections. Each section title is always visible, and clicking it expands the section to display its content.
- "Tabs": Tabs mode. Payment options are arranged in horizontal tabs, and clicking the tab switches the content.
The following are the visualization and sample codes for these two modes:
Accordion
Tabs
Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance":
"{\"theme\":\"night\",\"layout\":{\"type\":\"Accordion\"}}",
};Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance":
"{\"theme\":\"night\",\"layout\":{\"type\":\"Tabs\"}}",
};CSS variables
Payment Element supports fine‑grained customization of visual components via CSS, including styles for borders, backgrounds, text, and icons. To customize styles, you need to pass CSS variables through the variables parameter.
The following is a reference list of supported CSS variables and their default values. You can override these variables in your CSS code according to your branding requirements.
Color variables
Size variables
Color variables are used to define the overall visual color scheme of payment elements, covering aspects such as content, background, borders, actions, and states.
Content color
Background color
Border color
Action button color
State color
Size variables define the shape and spatial relationships of payment elements, including settings for border radius, wrapper, and stroke.
Border radius settings
Wrapper settings
Stroke settings
Below is a reference list of supported CSS variables and their default values. You can override the values of these variables in your CSS code according to your brand requirements.
Sample
Map<String, dynamic> amsPaymentElementConfiguration = {
"appearance": """
{
"theme": "default",
"layout": {
"type": "Accordion"
},
"variables": {
"content-primary": "#2a3a52",
"content-secondary": "#7c8ca3",
"content-tertiary": "#abb9cc",
"content-quaternary": "#ffffff",
"background-primary": "#ffffff",
"background-secondary": "#f9fafb",
"background-disable": "#fcfcfc",
"background-transparency": "#0000000a",
"border-primary": "#cfd8e5",
"border-secondary": "#ebebeb",
"border-disable": "#f5f5f5",
"action-normal": "#1650ff",
"action-hover": "#5c85ff",
"action-disable": "#a2b9ff",
"action-secondary": "#f3f6ff",
"state-failure": "#ff5b4d",
"state-warning": "#ff9f1a",
"state-success": "#00b277",
"state-info": "#6092d8",
"state-marketing": "#ff6060",
"state-conventional": "#7c8ca3",
"radius-backup": "4px",
"radius-module": "12px",
"radius-component": "8px",
"radius-button": "12px",
"wrapper-padding": "24px",
"stroke-default": "0.5px",
"stroke-active": "1px"
}
}
"""
};The following illustrations show how to customize different interface styles using CSS variables:
Accordion layout mode
Tabs layout mode
Payment info collection page
Card payment page
Digital wallet payment page
Address module
Pop-up window
Other (virtual account) page