Skip to main content
Version: v2

Theming and Styling

info

All theming and styling configuration is passed as part of the appearance object in the POST /sessions request payload. No code changes to the widget are needed.

Overview​

The CCG widget supports visual customization through the appearance configuration object. You can customize:

  • Button colors — primary and secondary palette
  • Typography — custom or open-source fonts
  • Border radius — for buttons and alert boxes
  • Button height — for Apple Pay and Google Pay buttons
  • Logo visibility — show or hide the header logo
  • Merchant logo — used in email templates
  • Privacy policy link — custom URL shown in the widget

For merchant logo and privacy policy configuration, see the dedicated docs:

Appearance Type Reference​

export type Appearance = {
  font: {
    fontSources: (CssFontSource | CustomFontSource)[];
    fontFamily: string;
  };
  palette?: {
    primary?: PaletteColors;
    secondary?: PaletteColors;
  };
  visibility?: {
    headerLogo?: boolean; // defaults to true
  };
  border?: {
    alertBoxBorderRadius?: string;
    /**
     * Border radius for Apple Pay and Google Pay buttons.
     * Defaults to 8px.
     */
    buttonBorderRadius?: string;
  };
  height?: {
    /**
     * Button height for Apple Pay and Google Pay buttons.
     * Defaults to 48px. Valid range: 40–55.
     */
    button?: number;
  };
  merchantLogo?: string;
  privacyPolicyUrl?: string;
};

export type PaletteColors = {
  light?: string;
  main: string;
  dark?: string;
  contrastText?: string;
};

export type CssFontSource = {
  /**
   * A URL pointing to a CSS file with @font-face definitions.
   * Example: https://fonts.googleapis.com/css?family=Open+Sans
   */
  cssSrc: string;
};

export type CustomFontSource = {
  /** The font family name */
  family: string;
  /** A valid src value pointing to your font file (.woff, .otf, .svg) */
  src: string;
  /** Defaults to 'normal' */
  style?: 'normal' | 'italic' | 'oblique';
  /** A valid CSS font-weight value */
  weight?: string;
};

Button Theming​

Customize the primary and secondary button colors using the palette field. Refer to MUI palette customization for guidance on color values.

Example: Customize button colors
const appearance = {
  palette: {
    primary: {
      dark: '#3e561a',
      main: '#5a7c26',
      light: '#7b9651',
      contrastText: '#ffffff',
    },
    secondary: {
      dark: '#b26e59',
      main: '#ff9e80',
      light: '#ffb199',
      contrastText: '#ffffff',
    },
  },
};

Border Radius​

Control the border radius of Apple Pay / Google Pay buttons and alert boxes.

const appearance = {
  border: {
    buttonBorderRadius: '12px',  // Apple Pay / Google Pay buttons
    alertBoxBorderRadius: '8px', // Alert/error boxes
  },
};

Button Height​

Adjust the height for Apple Pay and Google Pay buttons. Valid range: 40–55 (px). Defaults to 48.

const appearance = {
  height: {
    button: 52,
  },
};

Typography / Fonts​

You can include open-source font families (e.g. Google Fonts) or custom fonts hosted on your domain.

Example: Open-source font (Dosis via Google Fonts)
const appearance = {
  font: {
    fontFamily: 'Dosis, Arial, sans-serif',
    fontSources: [
      {
        cssSrc: 'https://fonts.googleapis.com/css?family=Dosis',
      },
    ],
  },
};
Example: Custom font (Optum Sans)
const appearance = {
  font: {
    fontFamily: "'Optum Sans', Arial, sans-serif",
    fontSources: [
      {
        family: 'Optum Sans',
        src: "url('https://wallet.healthsafepay.com/optum-sans.woff2')",
        style: 'normal',
        weight: '700',
      },
      {
        family: 'Optum Sans',
        src: "url('https://wallet.healthsafepay.com/optum-sans.woff2')",
        style: 'normal',
        weight: '400',
      },
    ],
  },
};

Header Logo Visibility​

Control whether the CCG header logo is shown in the widget.

const appearance = {
  visibility: {
    headerLogo: false, // hide the header logo
  },
};

Full Example​

Full appearance configuration example
const appearance = {
  palette: {
    primary: {
      main: '#0070C9',
      contrastText: '#ffffff',
    },
  },
  font: {
    fontFamily: 'Dosis, Arial, sans-serif',
    fontSources: [
      { cssSrc: 'https://fonts.googleapis.com/css?family=Dosis' },
    ],
  },
  border: {
    buttonBorderRadius: '10px',
  },
  height: {
    button: 48,
  },
  visibility: {
    headerLogo: true,
  },
  merchantLogo: 'https://your-domain.com/logo.png',
  privacyPolicyUrl: 'https://your-domain.com/privacy',
};