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:

CSS-in-JS: Apply React CSSProperties directly for precise control
CSS classes: Use custom classes for state styling, animations, and responsive design

CSS-in-JS Styling

Direct React CSS properties for precise control over form elements.

CSS Class Names

Custom classes for advanced styling with pseudo-selectors and responsive design.

Implement Brand Styles

Integrate the checkout form with your design system using CSS custom properties:

const brandStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        fontFamily: 'var(--font-primary)',
        backgroundColor: 'var(--surface-primary)',
        borderColor: 'var(--border-default)',
        borderRadius: 'var(--radius-md)'
      }
    }
  },
  SubmitButton: {
    styles: {
      backgroundColor: 'var(--color-primary)',
      borderRadius: 'var(--radius-md)'
    }
  }
}

Prefer CSS custom properties (var(...)) to keep styles consistent with your design system, enable easy theming, and minimize code changes.

CSS custom properties enable dynamic theming without JavaScript and generally perform better than heavy inline style changes.

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.

string

CSS class for the input element.

HTMLStyles

Styles for field labels.

Show label properties

CSSProperties

React CSS properties for labels.

string

CSS class for labels.

HTMLStyles

Styles for validation error messages.

Show error properties

CSSProperties

React CSS properties for error text.

string

CSS class for error text.

HTMLStyles & {focus?: string}

Wrapper around field, label, and error.

Show container properties

CSSProperties

React CSS properties for the container.

string

CSS class for the container.

string

CSS class applied when field is focused.

{ 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

CSS class 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.

string

Append a class for pseudo-state styling in your stylesheet (hover, focus, disabled) if you prefer to avoid inline styles.

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.

string

CSS class name to apply to wallet buttons.

HTMLStyles

Styles for Braintree payment buttons.

Show BraintreeButton properties

CSSProperties

React CSS properties object for styling Braintree buttons.

string

CSS class name to apply to 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.

string

Custom class name appended to the button element for pseudo-state or per-theme rules (hover, focus, disabled) in your stylesheet.

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.

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.

string

Custom class name appended to the wrapper element for external CSS targeting.

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 support both styles (React CSSProperties) and className, while cssVariables overrides global tokens for the entire checkout.
Wallet button styling must also follow each processor’s brand guidelines (Apple, PayPal, Google) to remain compliant.

Target Elements with External CSS

The SDK adds data-paynext-* attributes to key elements, enabling CSS targeting from external stylesheets without modifying JavaScript:

Attribute	Element
`data-paynext-component="checkout"`	Main checkout container
`data-paynext-version="1.0"`	SDK version attribute
`data-paynext-element="card-number-wrapper"`	Card number field outer wrapper
`data-paynext-element="card-number-container"`	Card number input container (receives focus styles)
`data-paynext-element="card-number-input"`	Card number input field
`data-paynext-element="card-number-label"`	Card number label
`data-paynext-element="card-number-error-label"`	Card number validation error
`data-paynext-element="card-name-wrapper"`	Cardholder name field outer wrapper
`data-paynext-element="card-name-container"`	Cardholder name input container (receives focus styles)
`data-paynext-element="card-name-input"`	Cardholder name input field
`data-paynext-element="card-name-label"`	Cardholder name label
`data-paynext-element="card-name-error-label"`	Cardholder name validation error
`data-paynext-element="submit-button"`	Submit/Pay button

external-styles.css

/* Target the checkout container for CSS variable overrides */
[data-paynext-component="checkout"] {
  --paynext-sdk-border: #e5e7eb;
  --paynext-sdk-border-focus: #6366f1;
  --paynext-sdk-input-focus-shadow: 0 0 0 3px rgba(99, 102, 241, 0.15);
}

/* Target specific input containers */
[data-paynext-element="card-number-container"],
[data-paynext-element="card-name-container"] {
  transition: border-color 0.2s ease;
}

/* Style the submit button */
[data-paynext-element="submit-button"] {
  transition: transform 0.1s ease;
}

[data-paynext-element="submit-button"]:hover {
  transform: translateY(-1px);
}

Combine external CSS with cssVariables for maximum flexibility. Use external CSS for media queries and pseudo-states, and cssVariables for brand tokens.

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 = {
  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'
    },
    className: 'hover:transform hover:scale-105 hover:shadow-lg active:scale-95'
  }
}

Use transforms and shadows for clear hover feedback without layout shifts.

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',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#0ead2e] focus:ring-4 focus:ring-green-100'
  }
}

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',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#F7CA00] focus:ring-4 focus:ring-yellow-100'
  },
}

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',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#2AA89B] focus:ring-4 focus:ring-teal-100'
  }
}

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.

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'
    },
    className: 'hover:bg-gray-800 hover:border-gray-600 active:scale-98'
  }
}

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'
    },
    className: 'hover:bg-blue-700 focus:ring-4 focus:ring-blue-100'
  }
}

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)'
      },
      className: 'focus:border-indigo-500 focus:ring-2 focus:ring-indigo-200 hover:border-gray-400'
    },
    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'
      },
      className: 'flex items-start gap-2'
    },
    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
Performance optimization: Hardware-accelerated transitions
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'
      },
      className: 'focus:border-blue-500 focus:outline-none'
    },
    label: {
      styles: {
        color: '#374151',
        fontSize: '14px',
        fontWeight: '600',
        marginBottom: '6px',
        display: 'block'
      }
    },
    error: {
      styles: {
        color: '#ef4444',
        fontSize: '13px',
        marginTop: '4px'
      },
      className: 'flex items-center gap-1'
    },
    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'
    },
    className: 'hover:bg-blue-700 active:scale-98 disabled:opacity-50'
  },

  // 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'
    },
    className: 'hover:bg-gray-50 hover:border-gray-400'
  },

  // Braintree button styling
  BraintreeButton: {
    styles: {
      backgroundColor: '#6366f1',
      color: 'white',
      border: 'none',
      borderRadius: '8px',
      padding: '14px 20px',
      fontSize: '15px',
      fontWeight: '600',
      cursor: 'pointer'
    },
    className: 'hover:bg-indigo-700 focus:ring-4 focus:ring-indigo-100'
  },

  // Cash App Pay button styling
  CashAppButton: {
    styles: {
      backgroundColor: '#14d13a',
      color: '#ffffff',
      border: 'none',
      borderRadius: '12px',
      fontSize: '16px',
      fontWeight: '600',
      height: '40px',
      cursor: 'pointer',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#0ead2e] focus:ring-4 focus:ring-green-100'
  },

  // Amazon Pay button styling
  AmazonPayButton: {
    styles: {
      backgroundColor: '#FFD814',
      color: '#0F1111',
      border: 'none',
      borderRadius: '8px',
      fontSize: '14px',
      fontWeight: '500',
      height: '40px',
      cursor: 'pointer',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#F7CA00] focus:ring-4 focus:ring-yellow-100'
  },

  // Pix button styling (icon-only button — text properties have no effect)
  PixButton: {
    styles: {
      backgroundColor: '#32BCAD',
      border: 'none',
      borderRadius: '8px',
      height: '40px',
      cursor: 'pointer',
      transition: 'background-color 0.2s ease'
    },
    className: 'hover:bg-[#2AA89B] focus:ring-4 focus:ring-teal-100'
  },

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

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

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

Use CSS custom properties for design system integration, enabling centralized management, easy theme switching, and team collaboration. For theme-level tokens, prefer cssVariables over inline styles.

For older browsers, provide fallback values: backgroundColor: 'var(--color-primary, #3b82f6)'

Follow Common Styling Patterns

Responsive Design

Mobile-First Approach

Design your checkout form with mobile users in mind first, then enhance for larger screens:

mobile-first.constant.ts

const responsiveStyles: StylesConfig = {
  Input: {
    field: {
      styles: {
        fontSize: '16px', // Prevents zoom on iOS
        padding: '14px 16px', // Larger touch targets
        borderRadius: '8px'
      },
      className: 'w-full sm:max-w-md' // Full width on mobile, constrained on desktop
    }
  },
  SubmitButton: {
    styles: {
      padding: '16px 24px', // Generous padding for touch
      fontSize: '16px',
      width: '100%'
    },
    className: 'sm:w-auto sm:min-w-[200px]' // Full width on mobile, auto on desktop
  }
}

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
      },
      className: 'focus:ring-4 focus:ring-blue-500 focus:ring-opacity-50' // Clear focus indicator
    },
    error: {
      styles: {
        color: '#dc2626', // High contrast red
        fontSize: '14px'
      },
      className: 'flex items-center gap-2' // Space for error icon
    },
    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'
    },
    className: 'focus:ring-4 focus:ring-offset-2' // Clear focus ring
  }
}

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: {
        // Use CSS custom properties for dynamic theming
        backgroundColor: 'var(--input-bg, #ffffff)',
        borderColor: 'var(--input-border, #d1d5db)',
        // Prefer transform over changing layout properties
        transition: 'border-color 0.2s ease, box-shadow 0.2s ease'
      }
    }
  },
  SubmitButton: {
    styles: {
      // Use will-change for animations
      willChange: 'transform',
      transition: 'transform 0.1s ease'
    },
    className: 'hover:scale-105 active:scale-95' // Hardware-accelerated transforms
  }
}

Brand Integration

Color Consistency

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

Typography Matching

Match your website’s typography by using the same font families and weights in the checkout form.

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'
      },
      className: 'focus:border-blue-400 focus:ring-blue-400'
    },
    label: {
      styles: { color: '#e5e7eb' }
    },
    error: {
      styles: { color: '#f87171' }
    }
  },
  SubmitButton: {
    styles: {
      backgroundColor: '#3b82f6',
      color: '#ffffff'
    },
    className: 'hover:bg-blue-600'
  }
}

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'
      },
      className: 'focus:border-blue-500'
    },
    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'
    },
    className: 'hover:bg-black hover:text-white'
  }
}

Getting Started

Use Cases

Customization

Constants

CSS-in-JS Styling

CSS Class Names

Implement Brand Styles

Configure StylesConfig

Core Elements

Digital Wallet Buttons

Pix Button

Pix Form

Target Elements with External CSS

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

CSS-in-JS Styling

CSS Class Names

​Implement Brand Styles

​Configure StylesConfig

​Core Elements

​Digital Wallet Buttons

​Pix Button

​Pix Form

​Target Elements with External CSS

​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

Target Elements with External CSS

Use Advanced Styling Patterns

Review Complete Styling Example

Apply Best Practices

Follow Common Styling Patterns

Responsive Design

Brand Integration

Common Styling Patterns