Custom Theme

FloPay ships six first-class theme bundles plus a 'classic' no-op marker. Pass a single theme value to FloPayCheckout, FloPayAutomaticPaymentButton, or SplitCardForm and the SDK styles both the Stripe-rendered fields and the React-rendered wrapper, submit button, and inputs from the same source.

Bundled Themes

All bundles are built around FloPay blue (#1785E0 on light bundles, #60A5FA on dark bundles).

One Prop, Consistent Look

'use client';

import { FloPayCheckout } from '@flopay/react';

export default function ThemedCheckoutPage() {
  return (
    <FloPayCheckout
      sessionId="your-session-uuid"
      theme="bold-dark"
      onComplete={(result) => console.log('Paid!', result)}
    />
  );
}

The same theme value styles the Stripe Elements inside the iframe and the React-rendered wrapper, title, submit button, and name input. No second prop to keep in sync.

Switching Bundles Side-By-Side

'use client';

import { FloPayCheckout } from '@flopay/react';

export function ThemeGallery({ sessionId }: { sessionId: string }) {
  return (
    <div
      style={{
        display: 'grid',
        gap: '1.5rem',
        gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
      }}
    >
      <section>
        <h3>Modern Light</h3>
        <FloPayCheckout sessionId={sessionId} theme="modern-light" />
      </section>
      <section>
        <h3>Bold Dark</h3>
        <FloPayCheckout sessionId={sessionId} theme="bold-dark" />
      </section>
      <section>
        <h3>Glass Dark</h3>
        <FloPayCheckout sessionId={sessionId} theme="glass-dark" />
      </section>
    </div>
  );
}

Resolution Precedence

When multiple styling props are present, the SDK resolves them from highest priority to lowest:

1. Explicit appearance — overrides the theme's appearance (palette + Stripe rules).
2. Explicit buttonsStyles — merges per-field on top of the theme's button layout.
3. theme bundle.
4. Legacy buttonsTheme preset (back-compat for older integrations).
5. Hardcoded defaults.

This means you can drop a theme onto the component and then surgically override just the fields you need:

<FloPayCheckout
  sessionId={sessionId}
  theme="modern-light"
  buttonsStyles={{
    submitButton: { backgroundColor: '#0F172A' },
  }}
/>

<FloPayCheckout
  sessionId={sessionId}
  theme="glass-dark"
  appearance={{
    rules: {
      '.Input': { border: '1px solid rgba(255,255,255,0.3)' },
    },
  }}
/>

Picking A Bundle Programmatically

Import the bundle map from @flopay/shared if you need to reference the appearance or button-layout directly (for example, to render a preview swatch outside the SDK):

import { THEMES, resolveTheme } from '@flopay/shared';

const glassDark = THEMES['glass-dark'];
// { appearance: FloPayAppearance, buttonsLayout: ButtonsLayoutStyles }

const bundle = resolveTheme('bold-light');
if (bundle) {
  console.log(bundle.appearance.variables?.colorPrimary);
}

resolveTheme('classic') returns undefined — 'classic' is a marker, not a bundle, so the SDK falls through to its hardcoded defaults.

Migrating From buttonsTheme

Legacy values still resolve via the back-compat shim, but new code should use theme:

buttonsTheme is silently ignored when theme is supplied alongside it, so a single-line swap is safe.

See Also

• Theming guide — full reference for theme, appearance, and buttonsStyles
• Shared constants reference — every *_APPEARANCE, BUTTONS_LAYOUT_*, and THEMES export