Theming

The depositOS widget is fully themeable to match your application's design. You have granular control over colors, typography, border styles, and button appearance through the depositOSTheme configuration property.

For a visual, interactive approach to theme editing, try the Playground tool.

Theme Structure

The depositOSTheme property accepts a DepositOSTheme object:

const theme: DepositOSTheme = {
  mode: "dark",
  colors: {
    background: "#0B0B0F",
    backgroundSecondary: "#111116",
    textPrimary: "#FFFFFF",
    textSecondary: "rgba(255,255,255,0.5)",
    border: "rgba(255,255,255,0.06)",
    accent: "#3B82F6",
    accentText: "#FFFFFF",
    card: "#0F0F14",
    surface: "rgba(255,255,255,0.05)",
    backdrop: "rgba(0,0,0,0.6)",
    alertBackground: "rgba(59,130,246,0.1)",
    alertAccent: "#3B82F6",
    warningBackground: "rgba(234,179,8,0.1)",
    warningAccent: "#EAB308",
    errorBackground: "rgba(239,68,68,0.1)",
    errorAccent: "#EF4444",
    successBackground: "rgba(34,197,94,0.1)",
    successAccent: "#22C55E",
  },
  fontFamily: "Inter, system-ui, sans-serif",
  borderRadius: "1.25rem",
  borderWidth: "1px",
  logoHeight: "2rem",
  primaryButton: {
    background: "#3B82F6",
    textColor: "#FFFFFF",
    borderColor: "transparent",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
  secondaryButton: {
    background: "rgba(255,255,255,0.05)",
    textColor: "#FFFFFF",
    borderColor: "rgba(255,255,255,0.1)",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
};

Color Palette

All colors are set in the colors object within your theme.

Core Colors

| Property | Description | |---|---| | background | Main widget background | | backgroundSecondary | Secondary/nested background areas | | textPrimary | Primary text color | | textSecondary | Muted text, descriptions, labels | | border | Default border color for cards and dividers | | accent | Brand accent color used for highlights and interactive elements | | accentText | Text color on accent-colored backgrounds | | card | Card and panel background | | surface | Subtle surface overlays (hover states, inputs) | | backdrop | Modal/overlay backdrop color |

Alert State Colors

| Property | Description | |---|---| | alertBackground | Informational alert background | | alertAccent | Informational alert accent (icons, borders) | | warningBackground | Warning alert background | | warningAccent | Warning alert accent | | errorBackground | Error alert background | | errorAccent | Error alert accent | | successBackground | Success alert background | | successAccent | Success alert accent |

Button Styling

Both primaryButton and secondaryButton accept the same set of properties:

| Property | Description | |---|---| | background | Button background color | | textColor | Button text color | | borderColor | Button border color | | borderRadius | Button border radius | | padding | Button padding (CSS shorthand) |

primaryButton: {
  background: "#7C3AED",
  textColor: "#FFFFFF",
  borderColor: "transparent",
  borderRadius: "9999px", // Fully rounded
  padding: "0.875rem 2rem",
},
secondaryButton: {
  background: "transparent",
  textColor: "#7C3AED",
  borderColor: "#7C3AED",
  borderRadius: "9999px",
  padding: "0.875rem 2rem",
},

Quick Presets

Dark Theme

const darkTheme: DepositOSTheme = {
  mode: "dark",
  colors: {
    background: "#0B0B0F",
    backgroundSecondary: "#111116",
    textPrimary: "#FFFFFF",
    textSecondary: "rgba(255,255,255,0.5)",
    border: "rgba(255,255,255,0.06)",
    accent: "#3B82F6",
    accentText: "#FFFFFF",
    card: "#0F0F14",
    surface: "rgba(255,255,255,0.05)",
    backdrop: "rgba(0,0,0,0.6)",
    alertBackground: "rgba(59,130,246,0.1)",
    alertAccent: "#3B82F6",
    warningBackground: "rgba(234,179,8,0.1)",
    warningAccent: "#EAB308",
    errorBackground: "rgba(239,68,68,0.1)",
    errorAccent: "#EF4444",
    successBackground: "rgba(34,197,94,0.1)",
    successAccent: "#22C55E",
  },
  fontFamily: "Inter, system-ui, sans-serif",
  borderRadius: "1.25rem",
  borderWidth: "1px",
  logoHeight: "2rem",
  primaryButton: {
    background: "#3B82F6",
    textColor: "#FFFFFF",
    borderColor: "transparent",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
  secondaryButton: {
    background: "rgba(255,255,255,0.05)",
    textColor: "#FFFFFF",
    borderColor: "rgba(255,255,255,0.1)",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
};

Light Theme

const lightTheme: DepositOSTheme = {
  mode: "light",
  colors: {
    background: "#FFFFFF",
    backgroundSecondary: "#F8F9FA",
    textPrimary: "#111827",
    textSecondary: "rgba(17,24,39,0.5)",
    border: "rgba(0,0,0,0.08)",
    accent: "#2563EB",
    accentText: "#FFFFFF",
    card: "#FFFFFF",
    surface: "rgba(0,0,0,0.03)",
    backdrop: "rgba(0,0,0,0.4)",
    alertBackground: "rgba(37,99,235,0.08)",
    alertAccent: "#2563EB",
    warningBackground: "rgba(234,179,8,0.08)",
    warningAccent: "#CA8A04",
    errorBackground: "rgba(220,38,38,0.08)",
    errorAccent: "#DC2626",
    successBackground: "rgba(22,163,74,0.08)",
    successAccent: "#16A34A",
  },
  fontFamily: "Inter, system-ui, sans-serif",
  borderRadius: "1.25rem",
  borderWidth: "1px",
  logoHeight: "2rem",
  primaryButton: {
    background: "#2563EB",
    textColor: "#FFFFFF",
    borderColor: "transparent",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
  secondaryButton: {
    background: "rgba(0,0,0,0.03)",
    textColor: "#111827",
    borderColor: "rgba(0,0,0,0.1)",
    borderRadius: "0.75rem",
    padding: "0.75rem 1.5rem",
  },
};

Legacy Theming

For simpler use cases, you can use the shorthand theme and primaryColor properties instead of the full depositOSTheme object:

const config: DepositOSConfig = {
  // ...
  theme: "dark", // "light" | "dark"
  primaryColor: "#7C3AED", // Your brand color as a hex value
};

These provide basic theming with sensible defaults. If depositOSTheme is also provided, it takes precedence over theme and primaryColor.

Applying a Theme

Pass the theme object in your widget configuration:

const config: DepositOSConfig = {
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourAddress",
  apiKey: "dos_live_…",
  depositOSTheme: darkTheme,
};