Customization

To customise the widget, pass CSS variables through the customCss prop. You can pass a string of CSS declarations or a key-value object — both formats work.

import { Pay } from '0xtrails/widget'

<Pay
  apiKey="YOUR_API_KEY"
  customCss={`
    --trails-primary: rgb(99 102 241);
    --trails-border-radius-button: 8px;
  `}
/>

// Object form also accepted
<Pay
  apiKey="YOUR_API_KEY"
  customCss={{
    '--trails-primary': 'var(--your-brand-primary)',
    '--trails-bg-primary': 'var(--your-brand-background)',
  }}
/>

Match your brand colours

Override the primary colour and its interactive states:

<Pay
  apiKey="YOUR_API_KEY"
  customCss={`
    --trails-primary: rgb(99 102 241);
    --trails-primary-hover: rgb(79 70 229);
    --trails-primary-disabled: rgb(209 213 219);
    --trails-primary-disabled-text: rgb(107 114 128);
    --trails-focus-ring: rgb(99 102 241);
    --trails-widget-border: 2px solid rgb(99 102 241);
  `}
/>

To pull in colours from your existing design system, reference your own CSS variables directly:

customCss={{
  '--trails-primary': 'var(--color-brand-500)',
  '--trails-primary-hover': 'var(--color-brand-600)',
  '--trails-bg-primary': 'var(--color-surface)',
  '--trails-text-primary': 'var(--color-text-default)',
}}

Set the border radius style

Rounded theme:

customCss={`
  --trails-border-radius-widget: 32px;
  --trails-border-radius-button: 24px;
  --trails-border-radius-input: 20px;
  --trails-border-radius-dropdown: 16px;
`}

Square / no-radius theme:

customCss={`
  --trails-border-radius-widget: 0px;
  --trails-border-radius-button: 0px;
  --trails-border-radius-input: 0px;
  --trails-border-radius-dropdown: 0px;
  --trails-border-radius-container: 0px;
`}

Set the font family

customCss={`
  --trails-font-family: "Inter", "SF Pro Display", -apple-system, sans-serif;
`}

Monospace:

customCss={`
  --trails-font-family: "Fira Code", "Monaco", monospace;
`}

Configure dark mode

Use the theme prop for light/dark/auto. If you need to override colours for a specific theme, combine theme with customCss:

<Pay
  apiKey="YOUR_API_KEY"
  theme="dark"
  customCss={`
    --trails-bg-primary: rgb(15 23 42);
    --trails-bg-secondary: rgb(30 41 59);
    --trails-text-primary: rgb(248 250 252);
    --trails-border-primary: rgb(51 65 85);
    --trails-primary: rgb(99 102 241);
  `}
/>

Advanced: glassmorphism

customCss={`
  --trails-bg-primary: rgba(255, 255, 255, 0.1);
  --trails-bg-secondary: rgba(255, 255, 255, 0.05);
  --trails-border-primary: rgba(255, 255, 255, 0.2);
  --trails-shadow: 0 8px 32px 0 rgba(31, 38, 135, 0.37);
`}

Advanced: disable default CSS

To apply a fully custom stylesheet without Trails’ defaults interfering:

<Pay
  apiKey="YOUR_API_KEY"
  disableCss={true}
/>

Global CSS overrides

Variables cascade as normal CSS custom properties. You can set them globally or scope them to a container:

/* Apply to all widget instances */
:root {
  --trails-primary: #6366f1;
}

/* Scope to a specific container */
.my-payment-section {
  --trails-primary: #10b981;
}

CSS variable reference

Typography

Variable	Default
`--trails-font-family`	`ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif`

Border radius

Variable	Applies to	Default
`--trails-border-radius-widget`	Main widget container	`32px`
`--trails-border-radius-button`	Primary buttons	`24px`
`--trails-border-radius-input`	Input fields	`24px`
`--trails-border-radius-dropdown`	Dropdown menus	`12px`
`--trails-border-radius-container`	Generic containers	`8px`
`--trails-border-radius-list`	Token lists	`8px`
`--trails-border-radius-list-button`	List item buttons	`12px`
`--trails-border-radius-large-button`	Large action buttons	`16px`

Variable	Default
`--trails-widget-border`	`none`
`--trails-shadow`	`0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)`

Primary colours

Variable	Default
`--trails-primary`	`rgb(59 130 246)`
`--trails-primary-hover`	`rgb(37 99 235)`
`--trails-primary-disabled`	`rgb(209 213 219)`
`--trails-primary-disabled-text`	`rgb(107 114 128)`

Background colours

Variable	Default
`--trails-bg-primary`	`rgb(255 255 255)`
`--trails-bg-secondary`	`rgb(249 250 251)`
`--trails-bg-tertiary`	`rgb(243 244 246)`
`--trails-bg-card`	`rgb(255 255 255)`
`--trails-bg-overlay`	`rgb(255 255 255)`

Text colours

Variable	Default
`--trails-text-primary`	`rgb(17 24 39)`
`--trails-text-secondary`	`rgb(75 85 99)`
`--trails-text-tertiary`	`rgb(107 114 128)`
`--trails-text-muted`	`rgb(156 163 175)`
`--trails-text-inverse`	`rgb(255 255 255)`

Border colours

Variable	Default
`--trails-border-primary`	`rgb(229 231 235)`
`--trails-border-secondary`	`rgb(209 213 219)`
`--trails-border-tertiary`	`rgb(243 244 246)`

Interactive states

Variable	Default
`--trails-hover-bg`	`rgb(243 244 246)`
`--trails-hover-text`	`rgb(17 24 39)`
`--trails-focus-ring`	`rgb(59 130 246)`

Status colours

Variable	Default
`--trails-success-bg`	`rgb(240 253 244)`
`--trails-success-text`	`rgb(22 163 74)`
`--trails-success-border`	`rgb(187 247 208)`
`--trails-warning-bg`	`rgb(255 251 235)`
`--trails-warning-text`	`rgb(217 119 6)`
`--trails-warning-border`	`rgb(253 230 138)`
`--trails-error-bg`	`rgb(254 242 242)`
`--trails-error-text`	`rgb(220 38 38)`
`--trails-error-border`	`rgb(254 202 202)`

Input fields

Variable	Default
`--trails-input-bg`	`rgb(255 255 255)`
`--trails-input-border`	`rgb(209 213 219)`
`--trails-input-text`	`rgb(17 24 39)`
`--trails-input-placeholder`	`rgb(156 163 175)`
`--trails-input-focus-border`	`rgb(59 130 246)`
`--trails-input-focus-ring`	`rgb(59 130 246)`

Dropdowns

Variable	Default
`--trails-dropdown-bg`	`rgb(255 255 255)`
`--trails-dropdown-border`	`rgb(229 231 235)`
`--trails-dropdown-text`	`rgb(17 24 39)`
`--trails-dropdown-hover-bg`	`rgb(249 250 251)`
`--trails-dropdown-selected-bg`	`rgb(243 244 246)`
`--trails-dropdown-selected-text`	`rgb(17 24 39)`
`--trails-dropdown-focus-border`	`rgb(59 130 246)`

Lists

Variable	Default
`--trails-list-bg`	`rgb(255 255 255)`
`--trails-list-border`	`rgb(229 231 235)`
`--trails-list-hover-bg`	`rgb(249 250 251)`

SDK Documentation

Match your brand colours

Set the border radius style

Set the font family

Configure dark mode

Advanced: glassmorphism

Advanced: disable default CSS

Global CSS overrides

CSS variable reference

Typography

Border radius

Widget structure

Primary colours

Background colours

Text colours

Border colours

Interactive states

Status colours

Input fields

Dropdowns

Lists

​Match your brand colours

​Set the border radius style

​Set the font family

​Configure dark mode

​Advanced: glassmorphism

​Advanced: disable default CSS

​Global CSS overrides

​CSS variable reference

​Typography

​Border radius

​Widget structure

​Primary colours

​Background colours

​Text colours

​Border colours

​Interactive states

​Status colours

​Input fields

​Dropdowns

​Lists

Match your brand colours

Set the border radius style

Set the font family

Configure dark mode

Advanced: glassmorphism

Advanced: disable default CSS

Global CSS overrides

CSS variable reference

Typography

Border radius

Widget structure

Primary colours

Background colours

Text colours

Border colours

Interactive states

Status colours

Input fields

Dropdowns

Lists