Skip to main content

​
Overview

The Trails widget is fully customizable through CSS variables, allowing you to match your brand and design system. You can customize colors, typography, spacing, border radius, shadows, and more.

​
CSS Variable Reference

​
Typography

VariableDescriptionDefault Value
--trails-font-familyFont family for all textui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif

​
Border Radius

VariableDescriptionDefault Value
--trails-border-radius-widgetMain widget container32px
--trails-border-radius-buttonPrimary buttons24px
--trails-border-radius-inputInput fields24px
--trails-border-radius-dropdownDropdown menus12px
--trails-border-radius-containerGeneric containers8px
--trails-border-radius-listToken lists8px
--trails-border-radius-list-buttonList item buttons12px
--trails-border-radius-large-buttonLarge action buttons16px

​
Widget Structure

VariableDescriptionDefault Value
--trails-widget-borderMain widget bordernone
--trails-shadowWidget shadow0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)

​
Primary Colors

VariableDescriptionDefault Value
--trails-primaryPrimary brand colorrgb(59 130 246)
--trails-primary-hoverPrimary hover statergb(37 99 235)
--trails-primary-disabledDisabled primary elementsrgb(209 213 219)
--trails-primary-disabled-textDisabled text colorrgb(107 114 128)

​
Background Colors

VariableDescriptionDefault Value
--trails-bg-primaryMain backgroundrgb(255 255 255)
--trails-bg-secondarySecondary backgroundrgb(249 250 251)
--trails-bg-tertiaryTertiary backgroundrgb(243 244 246)
--trails-bg-cardCard backgroundsrgb(255 255 255)
--trails-bg-overlayModal overlaysrgb(255 255 255)

​
Text Colors

VariableDescriptionDefault Value
--trails-text-primaryPrimary textrgb(17 24 39)
--trails-text-secondarySecondary textrgb(75 85 99)
--trails-text-tertiaryTertiary textrgb(107 114 128)
--trails-text-mutedMuted textrgb(156 163 175)
--trails-text-inverseInverse text (on dark backgrounds)rgb(255 255 255)

​
Border Colors

VariableDescriptionDefault Value
--trails-border-primaryPrimary bordersrgb(229 231 235)
--trails-border-secondarySecondary bordersrgb(209 213 219)
--trails-border-tertiaryTertiary bordersrgb(243 244 246)

​
Interactive States

VariableDescriptionDefault Value
--trails-hover-bgHover backgroundrgb(243 244 246)
--trails-hover-textHover text colorrgb(17 24 39)
--trails-focus-ringFocus ring colorrgb(59 130 246)

​
Status Colors

VariableDescriptionDefault Value
--trails-success-bgSuccess backgroundrgb(240 253 244)
--trails-success-textSuccess textrgb(22 163 74)
--trails-success-borderSuccess borderrgb(187 247 208)
--trails-warning-bgWarning backgroundrgb(255 251 235)
--trails-warning-textWarning textrgb(217 119 6)
--trails-warning-borderWarning borderrgb(253 230 138)
--trails-error-bgError backgroundrgb(254 242 242)
--trails-error-textError textrgb(220 38 38)
--trails-error-borderError borderrgb(254 202 202)

​
Input Fields

VariableDescriptionDefault Value
--trails-input-bgInput backgroundrgb(255 255 255)
--trails-input-borderInput borderrgb(209 213 219)
--trails-input-textInput text colorrgb(17 24 39)
--trails-input-placeholderPlaceholder textrgb(156 163 175)
--trails-input-focus-borderFocus border colorrgb(59 130 246)
--trails-input-focus-ringFocus ring colorrgb(59 130 246)
VariableDescriptionDefault Value
--trails-dropdown-bgDropdown backgroundrgb(255 255 255)
--trails-dropdown-borderDropdown borderrgb(229 231 235)
--trails-dropdown-textDropdown textrgb(17 24 39)
--trails-dropdown-hover-bgDropdown item hoverrgb(249 250 251)
--trails-dropdown-selected-bgSelected item backgroundrgb(243 244 246)
--trails-dropdown-selected-textSelected item textrgb(17 24 39)
--trails-dropdown-focus-borderDropdown focus borderrgb(59 130 246)

​
Lists

VariableDescriptionDefault Value
--trails-list-bgList backgroundrgb(255 255 255)
--trails-list-borderList borderrgb(229 231 235)
--trails-list-hover-bgList item hoverrgb(249 250 251)

​
Typography Customization

​
Custom Fonts

<TrailsWidget
  mode="pay"
  toAddress="0x..."
  customCss={`
    --trails-font-family: "Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  `}
/>

​
Monospace Theme

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="swap"
  customCss={`
    --trails-font-family: "Fira Code", "Monaco", "Consolas", monospace;
  `}
/>

​
Border Radius Customization

​
Rounded Theme

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  customCss={`
    --trails-border-radius-widget: 32px;
    --trails-border-radius-button: 24px;
    --trails-border-radius-input: 20px;
    --trails-border-radius-dropdown: 16px;
  `}
/>

​
Square Theme

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="fund"
  toAddress="0x..."
  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;
  `}
/>

​
Advanced Customization

​
Custom Shadows

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="swap"
  customCss={`
    --trails-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);
  `}
/>

​
Glassmorphism Effect

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  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);
  `}
/>

​
Best Practices

​
1. Maintain Accessibility

Ensure sufficient color contrast between text and backgrounds: 
// Good contrast example
customCss={`
  --trails-text-primary: rgb(17 24 39);
  --trails-bg-primary: rgb(255 255 255);
`}

​
2. Consistent Border Radius

Use a consistent border radius scale: 
customCss={`
  --trails-border-radius-widget: 16px;
  --trails-border-radius-button: 12px;
  --trails-border-radius-input: 8px;
  --trails-border-radius-dropdown: 6px;
`}

​
3. Brand Alignment

Match your existing design system: 
// Example matching your brand colors
customCss={{
  '--trails-primary': 'var(--your-brand-primary)',
  '--trails-bg-primary': 'var(--your-brand-background)',
  '--trails-text-primary': 'var(--your-brand-text)',
}}

​
4. Test in Both Light and Dark Modes

Consider how your customizations work with the theme prop: 
<TrailsWidget
  apiKey="YOUR_API_KEY"
  theme="dark"
  customCss={`
    /* Your dark theme customizations */
  `}
/>

​
CSS Variable Inheritance

The widget uses CSS custom properties (variables) that cascade through the component tree. You can override any variable at any level: 
/* Global override */
:root {
  --trails-primary: #your-brand-color;
}

/* Component-specific override */
.my-widget-container {
  --trails-primary: #different-color;
}