Customisation

Surf SDK is built to match your product's visual identity. Customisation works at three levels: theme tokens, CSS class overrides, and layout modes.

---

Theme Tokens

Pass a theme object to the widget to override design tokens:

<SurfWidget
  theme={{
    colors: {
      primary: "#6366f1",         // buttons, active states, progress indicators
      primaryText: "#ffffff",     // text on primary-coloured surfaces
      background: "#f9fafb",      // widget background
      cardBackground: "#ffffff",  // card and modal backgrounds
      text: "#111827",            // primary body text
      textSecondary: "#6b7280",   // labels and descriptions
      apy: "#10b981",             // APY value highlight colour
      border: "#e5e7eb",          // dividers and outlines
      success: "#10b981",         // success state colour
    },
    borderRadius: "12px",
    fontFamily: "'Inter', sans-serif",
  }}
/>

Every colour, radius and font can be overridden to match your brand.

---

CSS Class Overrides

Every UI element in the widget carries a scoped .surf-* class under the [data-surf-widget] root. You can target any element without modifying the widget source:

[data-surf-widget] .surf-btn--primary {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
}
[data-surf-widget] .surf-card {
  box-shadow: 0 4px 24px rgba(0,0,0,0.08);
}
[data-surf-widget] .surf-stat-value--apy {
  font-size: 2rem;
}

Available class groups:

• .surf-card - card containers

• .surf-btn - buttons (with modifiers like --primary)

• .surf-modal - modal overlays

• .surf-tabs - tab navigation

• .surf-step - progress tracker steps

• .surf-amount-box - amount input area

• .surf-stat-value - statistic displays (with modifiers like --apy)

• .surf-activity-item - activity feed entries

All widget styles are scoped to [data-surf-widget]. There is zero risk of style conflicts with your existing application CSS.

---

Layout Modes

Four integration patterns let you control how much of the widget UI you own:

Mode	How to use	Best for
All-in-One	<SurfWidget />	Fastest integration. Drop in and done.
Provider + Context	<SurfProvider> + useSurf()	Scatter widget elements across your own layout
Individual Components	VaultCard, DepositModal, WithdrawModal, VaultActivityModal	Mix and match pre-built components into your design
Headless Hooks	useVault, useDeposit, useWithdraw, useBalance, useAgentMessages	Build a fully custom UI using your own design system

For headless integration, see Hooks and Headless Mode.