Theming
The @blocklet/payment-react library is built on Material-UI and includes a dedicated theme provider, PaymentThemeProvider, to ensure a consistent and polished look across all components. This guide explains how to customize the default theme to match your application's design system.
PaymentThemeProvider#
Most components in the library, such as CheckoutForm, are internally wrapped with PaymentThemeProvider. This provider establishes a cohesive visual foundation by extending ArcBlock's base theme with styles tailored for payment UIs. It defines a specific color palette, typography scale, and default styles for various MUI components.
The theme merging process follows a clear hierarchy to combine the base theme, default payment styles, and your custom overrides.
Customization Methods#
You can customize the theme by passing a theme prop to payment components like CheckoutForm. This prop accepts a PaymentThemeOptions object, offering two primary methods for customization.
1. Overriding Component Styles#
To modify the default styles of underlying Material-UI components, provide a components object in your theme configuration. This object follows the standard MUI styleOverrides structure and will be deeply merged with the default payment theme.
This method is ideal for making consistent changes to components like buttons, inputs, and chips across the payment UI.
Example: Changing the Primary Button Color
import { CheckoutForm } from '@blocklet/payment-react';
function CustomStyledForm() {
return (
<CheckoutForm
id="plink_xxx"
theme={{
components: {
MuiButton: {
styleOverrides: {
containedPrimary: {
backgroundColor: '#1DC1C7',
color: '#fff',
'&:hover': {
backgroundColor: 'rgb(20, 135, 139)',
},
},
},
},
},
}}
/>
);
}2. Using the sx Prop for Targeted Overrides#
For more specific, one-off style adjustments, you can use the sx property within the theme object. This applies CSS directly to the component's wrapper element, allowing you to use class selectors to target nested elements.
This approach is useful when you need to style a specific element that doesn't have a direct styleOverrides entry or when you want to apply a quick fix without altering the global theme configuration.
Example: Customizing the Submit Button
import { CheckoutForm } from '@blocklet/payment-react';
function TargetedStyleForm() {
return (
<CheckoutForm
id="plink_xxx"
showCheckoutSummary={false}
theme={{
sx: {
// Note: The specific class name may vary.
// Inspect the element in your browser to find the correct selector.
'.cko-submit-button': {
backgroundColor: '#1DC1C7',
color: '#fff',
'&:hover': {
backgroundColor: 'rgb(20, 135, 139)',
},
},
},
}}
/>
);
}Understanding the Default Theme#
To customize effectively, it's helpful to know what the default theme provides. The PaymentThemeProvider includes several key customizations.
Custom Palette Extensions#
The theme extends the standard MUI palette with additional colors for specific UI elements.
Palette Key | Description |
|---|---|
| An object containing |
| A lighter text color, typically mapped to |
| The color for hyperlink text, mapped to |
Global CSS Classes#
The theme injects several global utility classes via MuiCssBaseline that you can use for styling consistency.
.base-card: Applies standard padding, border-radius, background, border, and shadow for card-like containers..base-label: A standard style for form labels and other descriptive text.
CSS Variables for Light & Dark Modes#
The entire color system is built upon a set of CSS variables that automatically adapt to light and dark modes. These variables cover backgrounds, text, buttons, borders, and shadows. While direct overrides are an advanced use case, being aware of this system helps in understanding how the theme achieves its adaptability.
For example, --backgrounds-bg-base is #ffffff in light mode and #1b1b1f in dark mode.
Now that you understand how to customize the visual appearance of components, you may want to explore the utility functions that can help with data formatting and API requests. For more information, see the Utilities guide.