Customize the Appearance

Align the checkout form with your brand and design system. Consistent styling improves user trust, reduces friction, and keeps the experience accessible across devices. The PayNext SDK supports two complementary approaches:

Inline styles: Apply React CSSProperties to individual elements through styles
Design tokens: Override the checkout’s colors, borders, focus ring, and hover states through cssVariables

Inline Styles

React CSS properties for precise control over individual form elements.

Design Tokens

CSS variables that restyle the whole checkout, including focus and hover states.

The checkout renders inside a secure iframe. Your page’s stylesheets, CSS classes, CSS custom properties, and fonts don’t reach it, so style the checkout only through styles and cssVariables. See Migrate to SDK 2.0.

Implement Brand Styles

Pass your brand values to the checkout directly. Set theme-wide tokens with cssVariables, then fine-tune individual elements with styles:

const brandStyles: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-input-bg': '#ffffff',
    '--paynext-sdk-border': '#d1d5db',
    '--paynext-sdk-border-focus': '#4f46e5',
    '--paynext-sdk-border-radius': '8px',
    '--paynext-sdk-button-bg': '#4f46e5',
    '--paynext-sdk-button-hover-opacity': '0.85'
  },
  SubmitButton: {
    styles: {
      fontWeight: '600'
    }
  }
}

Keep your brand values in one shared constant, so your page and the checkout use the same colors and radii.

CSS custom properties defined on your page, such as var(--color-primary), don’t resolve inside the checkout iframe. Pass the actual values instead.

Configure StylesConfig

The StylesConfig interface provides styling options for all checkout form elements.

Define your StylesConfig objects and pass them into the styles property when calling checkout.mount('element-id', { ...config, styles }), following the pattern in Mount the Checkout.

Core Elements

InputStyles

Configure card number, expiry, CVC, cardholder name, etc.

Show InputStyles Properties

HTMLStyles

Styles for the input element itself.

Show field properties

CSSProperties

React CSS properties for the input element.

HTMLStyles

Styles for field labels.

Show label properties

CSSProperties

React CSS properties for labels.

HTMLStyles

Styles for validation error messages.

Show error properties

CSSProperties

React CSS properties for error text.

HTMLStyles

Wrapper around field, label, and error.

Show container properties

CSSProperties

React CSS properties for the container.

{ styles?: CSSProperties }

Styles for placeholder text.

Show placeholder properties

CSSProperties

React CSS properties for placeholder text.

ISubmitButtonStyles

Styles for the payment submit button.

Show SubmitButton properties

CSSProperties

React CSS properties for the button.

string

Inline SVG markup rendered to the left of the button text. The spinner replaces this icon while a payment attempt is pending, so size the artwork (24x24px recommended) to match the layout without shifting content.

Digital Wallet Buttons

IApplePayButtonStyles

Apple Pay button styling following Apple’s guidelines.

Show Apple Pay Configuration

Partial<Pick<ApplePayOptions, 'type' | 'style' | 'padding' | 'borderRadius' | 'size'>>

Apple Pay styling options:

type: 'buy' | 'donate' | 'check-out' | 'book' | 'subscribe'
style: 'black' | 'white' | 'white-outline'
borderRadius: number (pixels)
size: 'small' | 'medium' | 'large'

IPayPalButtonStyles

PayPal button styling following PayPal specifications.

Show PayPal Configuration

PayPalButtonStyle

PayPal styling options:

layout: 'horizontal' | 'vertical'
color: 'gold' | 'blue' | 'silver' | 'white' | 'black'
shape: 'rect' | 'pill'
label: 'paypal' | 'checkout' | 'buynow' | 'pay'
height: number (25-55 pixels)

IGooglePayButtonStyles

Google Pay button styling.

Show Google Pay Configuration

Partial<Pick<GooglePayOptions, 'type' | 'color' | 'borderRadius' | 'size'>>

Google Pay styling options:

type: 'buy' | 'checkout' | 'pay' | 'order'
color: 'default' | 'black' | 'white'
borderRadius: number (pixels)
size: 'small' | 'medium' | 'large'

HTMLStyles

Cash App Pay button styling (Stripe wallets only).

Show Cash App Configuration

CSSProperties

Standard CSS-in-JS overrides for the Cash App button (height, border, colors, spacing). Stick to solid fills that maintain contrast for accessibility.

Match the default 40px height when possible so the button aligns with other wallet controls. Increase padding for better tap targets on mobile.

HTMLStyles

Styles for generic wallet buttons (e.g., custom wallet implementations).

Show WalletButton properties

CSSProperties

React CSS properties object for styling wallet buttons.

HTMLStyles

Styles for Braintree payment buttons.

Show BraintreeButton properties

CSSProperties

React CSS properties object for styling Braintree buttons.

Pix Button

HTMLStyles

Styles for the Pix button in the payment method list. The button shows the Pix icon without a label, so text properties have no effect — use styles for the surface itself: background, border, height, and radius. Defaults are a full-width 40px button with a white background, an #e0e0e0 border, and the theme’s border radius. The dark theme uses a #1a1a1a background with a #333 border.

Show PixButton properties

CSSProperties

Inline styles applied directly to the button element. These override the theme defaults, so a background you set here applies in both light and dark themes.

pix-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const pixButtonStyles: StylesConfig = {
  PixButton: {
    styles: {
      backgroundColor: '#32BCAD',
      border: 'none',
      borderRadius: '8px'
    }
  }
}

Pix Form

PixFormStyles

Overrides for the Pix form’s embedded Stripe Payment Element — the email, CPF/CNPJ, and name fields, plus the QR code step. Unlike the other elements on this page, these map to Stripe’s Appearance API variables instead of React CSSProperties, since the Pix form renders inside a Stripe-hosted iframe.

Show PixFormStyles properties

string

Accent color for the focused field and primary QR code elements.

string

Background color of the field group.

string

Text color for labels and entered values.

string

Color for validation error text and borders.

string

Placeholder text color.

string

Corner radius for the Pix input fields, for example '8px'.

Every field is optional — fields you don’t set keep the active theme’s default. Overrides apply to both recurring Pix Automático and one-time Pix, and re-apply immediately if the theme changes while the form is open. See Pix Form Theming.

pix-form.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const pixFormStyles: StylesConfig = {
  PixForm: {
    colorPrimary: '#ff4785',
    borderRadius: '4px'
  }
}

Available from SDK version 1.1.0.

BLIK Button

HTMLStyles

Styles for the BLIK button in the payment method list. The button shows the BLIK mark without a label, so text properties have no effect — use styles for the surface itself: background, border, height, and radius. The default is a full-width 40px black tile (#000000 background and border) with the theme’s border radius. Unlike the other payment buttons it is black in both themes, because the BLIK mark is white on black; the dark theme only softens the border to #333.

Show BlikButton properties

CSSProperties

Inline styles applied directly to the button element. These override the theme defaults, so a background you set here applies in both light and dark themes.

blik-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const blikButtonStyles: StylesConfig = {
  BlikButton: {
    styles: {
      backgroundColor: '#000000',
      border: 'none',
      borderRadius: '8px'
    }
  }
}

Available from SDK version 1.2.0.

BLIK Form

BlikFormStyles

Overrides for the BLIK form’s embedded Stripe Payment Element, where the customer enters the six-digit code from their banking app. BlikFormStyles has the same shape as PixFormStyles: the fields map to Stripe’s Appearance API variables instead of React CSSProperties, since the BLIK form renders inside a Stripe-hosted iframe.

Show BlikFormStyles properties

string

Accent color for the focused field.

string

Background color of the field group.

string

Text color for labels and the entered code.

string

Color for validation error text and borders.

string

Placeholder text color.

string

Corner radius for the BLIK code field, for example '8px'.

Every field is optional — fields you don’t set keep the active theme’s default, and overrides re-apply immediately if the theme changes while the form is open. See BLIK Form Theming.

blik-form.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const blikFormStyles: StylesConfig = {
  BlikForm: {
    colorPrimary: '#000000',
    borderRadius: '4px'
  }
}

Available from SDK version 1.2.0.

HTMLStyles

Styles for the back button wrapper that sits above the card form (hidden when the default variant hides the control). Defaults include a 30x30px flex container with centered content, a #f4f4f5 background, and 8px border radius.

Show BackButton properties

CSSProperties

Inline styles applied directly to the wrapper element.

CSSVariablesConfig

Override the SDK design tokens directly from styles without adding external stylesheets. Values apply to the checkout root element and merge with the active theme.

Leave any variable undefined to keep the theme default. See Theme Support › CSS Variables for the complete token list and defaults.

css-variables.constant.ts

import { PayNextCheckout, type StylesConfig, type CSSVariablesConfig } from '@paynext/sdk'

const brandTokens: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-bg': '#0b1220',
    '--paynext-sdk-text': '#e2e8f0',
    '--paynext-sdk-button-bg': 'linear-gradient(135deg, #06b6d4, #2563eb)',
    '--paynext-sdk-border-radius': '14px',
    '--paynext-sdk-input-focus-shadow': 'none' // Disable default focus ring
  }
}

const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', {
  ...config,
  styles: brandTokens,
})

Use cssVariables for theme-level changes and component-level styles for fine-grained control. They work together—component styles take precedence over CSS variables.

Element-level styling properties accept styles (React CSSProperties), while cssVariables overrides global tokens for the entire checkout. Inline styles can’t express pseudo-states such as :hover or :focus — use the hover and focus tokens in cssVariables for those.
Wallet button styling must also follow each processor’s brand guidelines (Apple, PayPal, Google) to remain compliant.

Use Advanced Styling Patterns

These examples demonstrate real-world styling patterns used by production applications. Each example includes performance optimizations and accessibility considerations.

All examples below show only the StylesConfig object. Pass it to checkout.mount('element-id', { ...config, styles }) as shown in Mount the Checkout.

css-variables-only.constant.ts

import { type StylesConfig, type CSSVariablesConfig } from '@paynext/sdk'

// Theme-level customization using only CSS variables
const cssVariablesStyles: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-input-focus-shadow': 'none',
    '--paynext-sdk-border': '#e5e7eb',
    '--paynext-sdk-border-focus': '#6366f1',
    '--paynext-sdk-input-bg': '#f9fafb',
    '--paynext-sdk-input-text': '#1f2937',
    '--paynext-sdk-button-bg': '#6366f1',
    '--paynext-sdk-button-text': '#ffffff',
    '--paynext-sdk-button-hover-opacity': '0.9',
    '--paynext-sdk-border-radius': '8px'
  }
}

CSS variables are the simplest way to customize the checkout. Use them for theme-level changes without touching component styles.

submit-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const submitButtonStyles: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-button-hover-opacity': '0.9' // Hover feedback
  },
  SubmitButton: {
    styles: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      border: 'none',
      borderRadius: '12px',
      color: 'white',
      fontSize: '16px',
      fontWeight: '600',
      padding: '16px 24px',
      boxShadow: '0 8px 32px rgba(102, 126, 234, 0.3)',
      transition: 'all 0.3s ease',
      cursor: 'pointer'
    },
  }
}

Inline styles can’t target :hover. Set --paynext-sdk-button-hover-opacity in cssVariables to control the Pay button’s hover feedback.

apple-pay.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const applePayStyles: StylesConfig = {
  ApplePayButton: {
    styles: {
      type: 'buy',
      style: 'black',
      borderRadius: 8,
      padding: 4,
      size: 'medium'
    }
  }
}

Apple Pay button styling follows Apple’s Human Interface Guidelines. The type determines the button text, while style controls the appearance.

paypal.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const paypalStyles: StylesConfig = {
  PayPalButton: {
    styles: {
      layout: 'horizontal',
      color: 'gold',
      shape: 'pill',
      label: 'checkout',
      tagline: false,
      height: 40
    }
  }
}

Use PayPal brand-approved styles. gold is the default recommendation in their guide.

google-pay.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const googlePayStyles: StylesConfig = {
  GooglePayButton: {
    styles: {
      type: 'buy',
      color: 'default',
      borderRadius: 4,
      size: 'medium'
    }
  }
}

Use color: 'white' on dark backgrounds and color: 'black' on light backgrounds.

cash-app.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const cashAppStyles: StylesConfig = {
  CashAppButton: {
    styles: {
      backgroundColor: '#14d13a',
      color: '#ffffff',
      border: 'none',
      borderRadius: '12px',
      fontSize: '16px',
      fontWeight: '600',
      height: '40px',
      cursor: 'pointer',
    },
  }
}

Match the default 40px height to align with other wallet buttons.

cash-app.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const amazonPayStyles: StylesConfig = {
  AmazonPayButton: {
    styles: {
      backgroundColor: '#FFD814',
      color: '#0F1111',
      border: 'none',
      borderRadius: '8px',
      fontSize: '14px',
      fontWeight: '500',
      height: '40px',
      cursor: 'pointer',
    },
  },
}

Match the default 40px height to align with other wallet buttons.

pix-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const pixButtonStyles: StylesConfig = {
  PixButton: {
    styles: {
      backgroundColor: '#32BCAD',
      border: 'none',
      borderRadius: '8px',
      height: '40px',
      cursor: 'pointer',
    },
  }
}

The button shows the Pix icon only, so text properties have no effect. Keep the default 40px height to align with the other payment buttons.

blik-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const blikButtonStyles: StylesConfig = {
  BlikButton: {
    styles: {
      backgroundColor: '#000000',
      border: 'none',
      borderRadius: '8px',
      height: '40px',
      cursor: 'pointer',
    },
  }
}

The button shows the BLIK mark only, so text properties have no effect. The default tile is black in both themes — keep enough contrast for the white mark if you override the background, and keep the default 40px height to align with the other payment buttons.

wallet-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const walletButtonOnly: StylesConfig = {
  WalletButton: {
    styles: {
      backgroundColor: '#1a1a1a',
      color: 'white',
      border: '1px solid #333',
      borderRadius: '8px',
      padding: '12px 20px',
      fontSize: '14px',
      fontWeight: '500',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      gap: '8px',
      transition: 'all 0.2s ease'
    },
  }
}

Maintain contrast ratios ≥ 4.5:1 for accessibility.

braintree-button.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const braintreeButtonOnly: StylesConfig = {
  BraintreeButton: {
    styles: {
      backgroundColor: '#0070f3',
      color: 'white',
      border: 'none',
      borderRadius: '6px',
      padding: '14px 24px',
      fontSize: '16px',
      fontWeight: '600',
      cursor: 'pointer'
    },
  }
}

enhanced-input.constant.ts

import { type StylesConfig } from '@paynext/sdk'

const enhancedInputStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        backgroundColor: '#ffffff',
        border: '1px solid #d1d5db',
        borderRadius: '8px',
        padding: '16px 20px',
        fontSize: '16px',
        fontFamily: 'Inter, system-ui, sans-serif',
        transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
        boxShadow: '0 1px 3px rgba(0, 0, 0, 0.1)'
      },
    },
    label: {
      styles: {
        color: '#374151',
        fontSize: '14px',
        fontWeight: '600',
        marginBottom: '8px',
        display: 'block',
        textTransform: 'capitalize'
      }
    },
    placeholder: {
      styles: {
        color: '#9ca3af',
        fontSize: '15px',
        fontStyle: 'normal',
        opacity: '0.8'
      }
    },
    error: {
      styles: {
        color: '#dc2626',
        fontSize: '13px',
        fontWeight: '500',
        marginTop: '6px'
      },
    },
    container: {
      styles: {
        marginBottom: '24px',
        position: 'relative'
      },
      focus: 'ring-2 ring-indigo-500 ring-opacity-20'
    }
  }
}

Use subtle placeholder styling with opacity to create visual hierarchy without overwhelming the user.

combined-styles.constant.ts

import { type StylesConfig, type CSSVariablesConfig } from '@paynext/sdk'

// Best practice: Use CSS variables for theme tokens, 
// component styles for specific overrides
const combinedStyles: StylesConfig = {
  // Theme-level tokens via CSS variables
  cssVariables: {
    '--paynext-sdk-input-focus-shadow': '0 0 0 3px rgba(99, 102, 241, 0.1)',
    '--paynext-sdk-border': '#e5e7eb',
    '--paynext-sdk-border-focus': '#6366f1',
    '--paynext-sdk-border-radius': '10px'
  },
  
  // Component-specific customization
  Input: {
    container: {
      styles: { marginBottom: '20px' }
    },
    label: {
      styles: { fontWeight: '600' }
    }
  },
  
  // Button with gradient (overrides cssVariables button-bg)
  SubmitButton: {
    styles: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      padding: '18px 32px',
      fontSize: '17px',
      fontWeight: '700',
      boxShadow: '0 8px 32px rgba(102, 126, 234, 0.3)'
    }
  }
}

Component-level styles take precedence over cssVariables. Set defaults with variables, then override specific components as needed.

Review Complete Styling Example

Here’s a comprehensive example that demonstrates styling all available components. This configuration is production-ready and includes:

Accessibility compliance: standards
Cross-browser compatibility: Tested across major browsers
Mobile responsiveness: Touch-friendly targets and spacing

complete-styling.constant.ts

import { type PayNextConfig, type StylesConfig, type CSSVariablesConfig } from '@paynext/sdk'

const completeStyles: StylesConfig = {
  // Theme-level tokens (optional, for global consistency)
  cssVariables: {
    '--paynext-sdk-border': '#e5e7eb',
    '--paynext-sdk-border-focus': '#3b82f6',
    '--paynext-sdk-input-focus-shadow': '0 0 0 3px rgba(59, 130, 246, 0.15)',
    '--paynext-sdk-border-radius': '8px'
  },

  // Input field styling
  Input: {
    field: {
      styles: {
        backgroundColor: '#ffffff',
        border: '2px solid #e5e7eb',
        borderRadius: '8px',
        padding: '12px 16px',
        fontSize: '16px',
        fontFamily: 'system-ui, sans-serif',
        transition: 'border-color 0.2s ease'
      },
    },
    label: {
      styles: {
        color: '#374151',
        fontSize: '14px',
        fontWeight: '600',
        marginBottom: '6px',
        display: 'block'
      }
    },
    error: {
      styles: {
        color: '#ef4444',
        fontSize: '13px',
        marginTop: '4px'
      },
    },
    container: {
      styles: { marginBottom: '16px' },
      focus: 'ring-2 ring-blue-500 ring-opacity-20'
    },
    placeholder: {
      styles: {
        color: '#9ca3af',
        fontSize: '16px'
      }
    }
  },

  // Submit button styling
  SubmitButton: {
    styles: {
      backgroundColor: '#3b82f6',
      color: 'white',
      border: 'none',
      borderRadius: '8px',
      padding: '16px 24px',
      fontSize: '16px',
      fontWeight: '600',
      width: '100%',
      cursor: 'pointer',
      transition: 'all 0.2s ease'
    },
  },

  // Apple Pay button styling
  ApplePayButton: {
    styles: {
      type: 'buy',
      style: 'black',
      borderRadius: 8,
      size: 'medium'
    }
  },

  // PayPal button styling
  PayPalButton: {
    styles: {
      layout: 'horizontal',
      color: 'gold',
      shape: 'rect',
      label: 'checkout',
      height: 48
    }
  },

  // Google Pay button styling
  GooglePayButton: {
    styles: {
      type: 'buy',
      color: 'default',
      borderRadius: 8,
      size: 'medium'
    }
  },

  // Generic wallet button styling
  WalletButton: {
    styles: {
      backgroundColor: '#f9fafb',
      color: '#374151',
      border: '1px solid #d1d5db',
      borderRadius: '8px',
      padding: '12px 16px',
      fontSize: '14px',
      fontWeight: '500',
      cursor: 'pointer',
      transition: 'all 0.2s ease'
    },
  },

  // Braintree button styling
  BraintreeButton: {
    styles: {
      backgroundColor: '#6366f1',
      color: 'white',
      border: 'none',
      borderRadius: '8px',
      padding: '14px 20px',
      fontSize: '15px',
      fontWeight: '600',
      cursor: 'pointer'
    },
  },

  // Cash App Pay button styling
  CashAppButton: {
    styles: {
      backgroundColor: '#14d13a',
      color: '#ffffff',
      border: 'none',
      borderRadius: '12px',
      fontSize: '16px',
      fontWeight: '600',
      height: '40px',
      cursor: 'pointer',
    },
  },

  // Amazon Pay button styling
  AmazonPayButton: {
    styles: {
      backgroundColor: '#FFD814',
      color: '#0F1111',
      border: 'none',
      borderRadius: '8px',
      fontSize: '14px',
      fontWeight: '500',
      height: '40px',
      cursor: 'pointer',
    },
  },

  // Pix button styling (icon-only button — text properties have no effect)
  PixButton: {
    styles: {
      backgroundColor: '#32BCAD',
      border: 'none',
      borderRadius: '8px',
      height: '40px',
      cursor: 'pointer',
    },
  },

  // Pix form styling (Stripe Appearance API variables, not CSSProperties)
  PixForm: {
    colorPrimary: '#32BCAD',
    borderRadius: '8px'
  },

  // BLIK button styling (icon-only black tile — text properties have no effect)
  BlikButton: {
    styles: {
      backgroundColor: '#000000',
      border: 'none',
      borderRadius: '8px',
      height: '40px',
      cursor: 'pointer',
    },
  },

  // BLIK form styling (same shape as PixForm — Stripe Appearance API variables)
  BlikForm: {
    colorPrimary: '#000000',
    borderRadius: '8px'
  },

  // Back button styling
  BackButton: {
    styles: {
      width: '30px',
      height: '30px',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      backgroundColor: '#f4f4f5',
      borderRadius: '8px'
    },
  }
}

const completeConfig: PayNextConfig = {
  clientToken: 'your-client-token',
  environment: 'sandbox',
  apiVersion: 'v1',
  styles: completeStyles,
  /* other options */
}

// When mounting (see Getting Started "Mount the Checkout" section):
const checkout = new PayNextCheckout()
await checkout.mount('checkout-container', completeConfig)

This production-ready example includes compliance: 16px min text, 44px touch targets, ≥4.5:1 contrast, and visible focus states.

Apply Best Practices

Keep your brand values in one shared constant and pass them to the checkout, as in Implement Brand Styles. For theme-level tokens, prefer cssVariables over inline styles.

The checkout renders inside an iframe, so your page’s CSS custom properties don’t resolve there. A value such as var(--color-primary) falls back to the browser default — pass the actual color instead.

Follow Common Styling Patterns

Responsive Design

Mobile-First Approach

The checkout fills the width of the container you mount it into, and media queries inside the checkout iframe respond to that width, not to the browser window. Control the checkout’s width on your container, with your own media queries:

checkout-container.css

#checkout-container {
  width: 100%;
  max-width: 448px; /* Constrained on wider screens */
  margin: 0 auto;
}

Then size fields and buttons for touch:

mobile-first.constant.ts

const responsiveStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        fontSize: '16px', // Prevents zoom on iOS
        padding: '14px 16px', // Larger touch targets
        borderRadius: '8px'
      },
    }
  },
  SubmitButton: {
    styles: {
      padding: '16px 24px', // Generous padding for touch
      fontSize: '16px',
      width: '100%'
    },
  }
}

Accessibility Considerations

Ensure your styling meets accessibility standards:

accessible.constant.ts

const accessibleStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        fontSize: '16px', // Minimum readable size
        padding: '12px 16px',
        border: '2px solid #d1d5db', // Visible border
        backgroundColor: '#ffffff' // High contrast
      },
    },
    error: {
      styles: {
        color: '#dc2626', // High contrast red
        fontSize: '14px'
      },
    },
    placeholder: {
      styles: {
        color: '#6b7280', // Sufficient contrast ratio
        fontSize: '16px' // Same size as input text
      }
    }
  },
  SubmitButton: {
    styles: {
      minHeight: '44px', // Minimum touch target size
      fontSize: '16px',
      fontWeight: '600'
    },
  }
}

quick checks: 16px min text, ≥4.5:1 contrast, visible focus ring, 44px touch targets, no color-only semantics.

Performance Optimization

Optimize your styles for better performance:

optimized.constant.ts

const optimizedStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        backgroundColor: '#ffffff',
        borderColor: '#d1d5db',
        // Animate only what the focus state changes
        transition: 'border-color 0.2s ease, box-shadow 0.2s ease'
      }
    }
  },
  SubmitButton: {
    styles: {
      // The hover state changes opacity (--paynext-sdk-button-hover-opacity)
      transition: 'opacity 0.2s ease'
    },
  }
}

Brand Integration

Color Consistency

Use your brand colors consistently across all payment elements to maintain visual cohesion.

Typography Matching

Set fontFamily and fontWeight in styles to match your site. Your page’s web fonts aren’t loaded inside the checkout iframe, so choose a font that’s installed on the customer’s device, with a system fallback.

Border Radius

Maintain consistent border radius values that match your site’s design language.

Animation Timing

Use consistent transition durations (typically 0.2s-0.3s) for a cohesive user experience.

Common Styling Patterns

Dark Mode
Minimal Design

dark-mode.constant.ts

import { type StylesConfig } from '@paynext/sdk'

// Option 1: Use built-in dark theme with CSS variable overrides
const darkModeWithVariables: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-bg': '#1a1a1a',
    '--paynext-sdk-text': '#ffffff',
    '--paynext-sdk-border': '#404040',
    '--paynext-sdk-border-focus': '#8b5cf6',
    '--paynext-sdk-input-bg': '#2d2d2d',
    '--paynext-sdk-input-text': '#f5f5f5',
    '--paynext-sdk-input-focus-shadow': '0 0 0 2px rgba(139, 92, 246, 0.3)',
    '--paynext-sdk-button-bg': '#8b5cf6',
    '--paynext-sdk-button-hover-opacity': '0.85'
  }
}

// Option 2: Component-level dark styling
const darkModeStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        backgroundColor: '#1f2937',
        borderColor: '#374151',
        color: '#f9fafb'
      },
    },
    label: {
      styles: { color: '#e5e7eb' }
    },
    error: {
      styles: { color: '#f87171' }
    }
  },
  SubmitButton: {
    styles: {
      backgroundColor: '#3b82f6',
      color: '#ffffff'
    },
  }
}

Prefer cssVariables for dark mode. See Theme Support for more presets.

minimal.constant.ts

import { type StylesConfig } from '@paynext/sdk'

// Clean, minimal aesthetic using CSS variables
const minimalStyles: StylesConfig = {
  cssVariables: {
    '--paynext-sdk-input-focus-shadow': 'none',
    '--paynext-sdk-border': '#000000',
    '--paynext-sdk-border-focus': '#000000',
    '--paynext-sdk-border-radius': '0px'
  },
  Input: {
    field: {
      styles: {
        border: 'none',
        borderBottom: '2px solid #e5e7eb',
        padding: '12px 0',
        backgroundColor: 'transparent'
      },
    },
    label: {
      styles: {
        fontSize: '12px',
        textTransform: 'uppercase',
        letterSpacing: '0.1em',
        color: '#6b7280'
      }
    }
  },
  SubmitButton: {
    styles: {
      backgroundColor: 'transparent',
      border: '2px solid #000000',
      color: '#000000',
      padding: '16px 32px',
      textTransform: 'uppercase',
      letterSpacing: '0.05em'
    },
  }
}

Getting Started

Use Cases

Customization

Constants

Inline Styles

Design Tokens

Implement Brand Styles

Configure StylesConfig

Core Elements

Digital Wallet Buttons

Pix Button

Pix Form

BLIK Button

BLIK Form

Use Advanced Styling Patterns

Review Complete Styling Example

Apply Best Practices

Follow Common Styling Patterns

Responsive Design

Brand Integration

Color Consistency

Typography Matching

Border Radius

Animation Timing

Common Styling Patterns

Inline Styles

Design Tokens

​Implement Brand Styles

​Configure StylesConfig

​Core Elements

​Digital Wallet Buttons

​Pix Button

​Pix Form

​BLIK Button

​BLIK Form

​Use Advanced Styling Patterns

​Review Complete Styling Example

​Apply Best Practices

​Follow Common Styling Patterns

​Responsive Design

​Brand Integration

Color Consistency

Typography Matching

Border Radius

Animation Timing

​Common Styling Patterns

Implement Brand Styles

Configure StylesConfig

Core Elements

Digital Wallet Buttons

Pix Button

Pix Form

BLIK Button

BLIK Form

Use Advanced Styling Patterns

Review Complete Styling Example

Apply Best Practices

Follow Common Styling Patterns

Responsive Design

Brand Integration

Common Styling Patterns