Theming & Customization

The SDK accepts a theme object that controls the visual appearance of the card form inside the iframe. You only need to override the properties you want to change — everything else falls back to the default theme.

Basic theming

import { ZatlasCardCapture } from '@zatlas/card-capture';

const zatlas = new ZatlasCardCapture({
  publishableKey: 'pk_sandbox_your_key',
  theme: {
    colors: {
      primary: '#6D28D9',
      borderFocus: '#6D28D9',
      background: '#FAFAFA',
    },
    borders: {
      radius: '12px',
    },
  },
});

You only pass the values you want to change. The SDK deep-merges your overrides with the default theme.

Pre-built themes

The SDK ships three theme helpers:

Export	Description
`defaultTheme`	Light theme with teal accents (matches Zatlas platform design)
`darkTheme`	Dark background with lighter accents
`mergeTheme(partial)`	Deep-merges a partial theme object with `defaultTheme`

import { darkTheme } from '@zatlas/card-capture';

const zatlas = new ZatlasCardCapture({
  publishableKey: 'pk_sandbox_your_key',
  theme: darkTheme,
});

To extend the dark theme:

import { darkTheme, mergeTheme } from '@zatlas/card-capture';

const customDark = mergeTheme({
  ...darkTheme,
  colors: {
    ...darkTheme.colors,
    primary: '#10B981',
    borderFocus: '#10B981',
  },
});

const zatlas = new ZatlasCardCapture({
  publishableKey: 'pk_sandbox_your_key',
  theme: customDark,
});

Runtime updates

You can change the theme after initialization with updateTheme(). This is useful for toggling between light and dark mode:

import { darkTheme } from '@zatlas/card-capture';

// Toggle to dark mode
zatlas.updateTheme(darkTheme);

// Or pass a partial override
zatlas.updateTheme({
  colors: {
    primary: '#34D399',
    background: '#1F2937',
    text: '#F9FAFB',
    border: '#374151',
    borderFocus: '#34D399',
    borderError: '#F87171',
    textPlaceholder: '#6B7280',
    buttonBackground: '#34D399',
  },
});

Color reference

Field colors

Property	Default (light)	Default (dark)	Description
`colors.background`	`#FFFFFF`	`#1F2937`	Field background
`colors.backgroundHover`	`#FAFBFC`	`#374151`	Background on hover
`colors.backgroundDisabled`	`#F5F5F7`	`#111827`	Background when disabled
`colors.text`	`#1A1B1C`	`#F9FAFB`	Input text color
`colors.textPlaceholder`	`#B6B7BF`	`#6B7280`	Placeholder text
`colors.textError`	`#D84B4B`	`#F87171`	Error/validation message text
`colors.textDisabled`	`#B6B7BF`	`#4B5563`	Disabled text

Border colors

Property	Default (light)	Default (dark)	Description
`colors.border`	`#B6B7BF`	`#374151`	Default border
`colors.borderHover`	`#CBCCD5`	`#4B5563`	Border on hover
`colors.borderFocus`	`#2D926E`	`#34D399`	Border on focus
`colors.borderError`	`#D84B4B`	`#F87171`	Border on validation error
`colors.borderSuccess`	`#2D926E`	`#34D399`	Border on valid input

Status colors

Property	Default (light)	Default (dark)	Description
`colors.primary`	`#2D926E`	`#34D399`	Primary accent (focus ring, CTA default)
`colors.success`	`#2D926E`	`#34D399`	Success accent (valid field border)

Icon colors

Property	Default (light)	Default (dark)	Description
`colors.icon`	`#6D6E75`	`#9CA3AF`	Card brand icon
`colors.iconError`	`#D84B4B`	`#F87171`	Icon on error
`colors.iconSuccess`	`#2D926E`	`#34D399`	Icon on success

CTA button

Property	Default	Description
`colors.buttonBackground`	`#2D926E`	Button background
`colors.buttonBackgroundHover`	`#20674E`	Button background on hover
`colors.buttonText`	`#FFFFFF`	Button text

Field labels

Property	Default	Description
`colors.labelText`	`#6D6E75`	Label above each field

Property	Default	Description
`colors.bannerErrorBackground`	`#FEF2F2`	Banner background on payment decline
`colors.bannerErrorBorder`	`#FECACA`	Banner border
`colors.bannerErrorText`	`#781D1D`	Banner message text

Typography

Property	Default	Description
`typography.fontFamily`	`'Inter', system-ui, -apple-system, sans-serif`	Font stack
`typography.fontSize`	`14px`	Base font size
`typography.fontWeight`	`400`	Font weight
`typography.lineHeight`	`1.5`	Line height
`typography.letterSpacing`	`normal`	Letter spacing

Borders

Property	Default	Description
`borders.radius`	`6px`	Corner radius
`borders.width`	`1px`	Border width
`borders.style`	`solid`	Border style (`solid`, `dashed`, `dotted`)

Spacing

Property	Default	Description
`spacing.paddingX`	`12px`	Horizontal padding inside the field
`spacing.paddingY`	`10px`	Vertical padding inside the field
`spacing.iconGap`	`10px`	Gap between icon and input text

Shadows

Property	Default (light)	Default (dark)	Description
`shadows.focus`	`0 0 0 3px #A2E0C5`	`0 0 0 3px rgba(52,211,153,0.25)`	Focus ring shadow
`shadows.error`	`0 0 0 3px rgba(216,75,75,0.15)`	`0 0 0 3px rgba(248,113,113,0.25)`	Error state shadow

Transitions

Property	Default	Description
`transitions.duration`	`150ms`	Animation duration
`transitions.timing`	`ease-in-out`	Timing function

Container sizing & responsiveness

The SDK injects a secure iframe into the element you pass to card.mount(). The iframe auto-resizes its height to fit the card form content. To ensure a smooth experience on all screen sizes, follow these guidelines.

Sizing the container

Style your container element like you would a content block — give it a width, and let the iframe handle its own height:

<div id="card-element" style="width: 100%; max-width: 480px;"></div>

The iframe uses width: 100% to fill its container. You control the width; the SDK controls the height.

Never set a fixed height, max-height, or overflow: hidden on the container. The iframe needs to grow to fit all form fields and the CTA button. If the container clips the iframe, the guest will not see the submit button.

/* Bad — clips the card form */
#card-element {
  height: 300px;
  overflow: hidden;
}

/* Good — let the iframe grow */
#card-element {
  width: 100%;
  max-width: 480px;
}

How auto-sizing works

The card form renders inside the iframe (card number, expiry, CVC, cardholder name, email, and the CTA button).
The iframe measures its content height and notifies the SDK via postMessage.
The SDK sets the iframe’s pixel height to match.
While the content loads, the iframe starts at a minimum height of 420px to prevent layout shift.

Recommended container widths

The card form works best between 300px and 600px wide. Below 300px, fields become cramped. Above 600px, the form looks sparse — consider centering it with max-width.

Container width	Layout
300 — 480px	Ideal for mobile and embedded flows
480 — 600px	Comfortable on desktop

Flex and grid containers

If you place the card element inside a flexbox or grid parent, make sure the container can grow vertically:

/* Flexbox parent — works fine */
.payment-section {
  display: flex;
  flex-direction: column;
  gap: 16px;
}

/* Grid parent — works fine */
.payment-section {
  display: grid;
  gap: 16px;
}

Avoid align-items: center on a flex parent with a fixed height — it can push the card form out of view on mobile. Use align-items: stretch (the default) or flex-start instead.

Mobile considerations

The card form is fully responsive. The expiry and CVC fields stay side by side on all screen sizes — they only need a few characters each. No media queries are needed in your CSS.

For mobile-first layouts, make the container full-width with padding:

#card-element {
  width: 100%;
  padding: 0 16px;
}