Customization

Customize the Trails widget appearance with CSS variables

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

Widget structure

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)