Theming

Overview

Customize the appearance of SDK components to match your brand. Themes can be applied globally or per-component.

---

Theme Configuration

interface ThemeConfig {
  primaryColor?: string;      // Primary brand color
  secondaryColor?: string;    // Secondary/accent color
  backgroundColor?: string;   // Background color
  textColor?: string;         // Primary text color
  borderColor?: string;       // Border color
  errorColor?: string;        // Error state color
  successColor?: string;      // Success state color
  fontFamily?: string;        // Font family
  borderRadius?: string;      // Border radius
}

---

Applying Themes

Global Theme (Client Level)

Apply a theme to all components created by the client:

const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  theme: {
    primaryColor: '#0066cc',
    successColor: '#22c55e',
    errorColor: '#ef4444',
    fontFamily: 'Inter, system-ui, sans-serif',
    borderRadius: '8px',
  },
});

Per-Component Theme

Override the global theme for a specific component:

const invoiceList = client.components.invoiceList({
  containerId: 'invoices',
  customerId: 'cus_xxx',
  theme: {
    primaryColor: '#8b5cf6', // Override just this property
  },
});

---

Theme Properties

Colors

Property	Description	Default
primaryColor	Buttons, links, primary actions	#0066cc
secondaryColor	Secondary elements, accents	#6b7280
backgroundColor	Component background	#ffffff
textColor	Primary text color	#1a1a1a
borderColor	Borders and dividers	#e5e7eb
errorColor	Error states, validation	#ef4444
successColor	Success states	#22c55e

Typography

Property	Description	Default
fontFamily	Font stack	Inter, system-ui, sans-serif

Spacing & Shape

Property	Description	Default
borderRadius	Corner radius	8px

---

Preset Themes

Default

const defaultTheme = {
  primaryColor: '#0066cc',
  successColor: '#22c55e',
  errorColor: '#ef4444',
  textColor: '#1a1a1a',
  secondaryColor: '#6b7280',
  backgroundColor: '#ffffff',
  borderColor: '#e5e7eb',
  borderRadius: '8px',
  fontFamily: 'Inter, system-ui, sans-serif',
};

Dark Mode

const darkTheme = {
  primaryColor: '#3b82f6',
  successColor: '#10b981',
  errorColor: '#f87171',
  textColor: '#f9fafb',
  secondaryColor: '#9ca3af',
  backgroundColor: '#1f2937',
  borderColor: '#374151',
  borderRadius: '8px',
  fontFamily: 'Inter, system-ui, sans-serif',
};

Purple

const purpleTheme = {
  primaryColor: '#8b5cf6',
  successColor: '#34d399',
  errorColor: '#f87171',
  textColor: '#1e1b4b',
  secondaryColor: '#6366f1',
  backgroundColor: '#faf5ff',
  borderColor: '#ddd6fe',
  borderRadius: '12px',
  fontFamily: "'SF Pro Display', system-ui, sans-serif",
};

---

Example: Custom Branded Theme

const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  theme: {
    // Your brand colors
    primaryColor: '#FF5722',      // Orange primary
    successColor: '#4CAF50',      // Green success
    errorColor: '#F44336',        // Red error

    // Text and backgrounds
    textColor: '#212121',
    backgroundColor: '#FAFAFA',
    borderColor: '#E0E0E0',

    // Typography
    fontFamily: "'Roboto', sans-serif",

    // Shape
    borderRadius: '4px',          // Square corners
  },
});

---

CSS Custom Properties

The SDK uses CSS custom properties internally. You can also override styles using CSS:

/* Override SDK styles */
.alt-widget {
  --alt-primary: #FF5722;
  --alt-success: #4CAF50;
  --alt-danger: #F44336;
  --alt-text: #212121;
  --alt-background: #FAFAFA;
  --alt-border: #E0E0E0;
  --alt-font-family: 'Roboto', sans-serif;
  --alt-border-radius: 4px;
}

CSS overrides may break in future SDK versions. Prefer using the theme configuration when possible.

---

Live Theme Editor

The SDK examples include a live theme editor for testing different color combinations. Run the examples locally to experiment with themes before implementing.

cd partner-sdk/examples
npm install
npm run dev

Then visit http://localhost:5173/custom-theme.html to use the interactive theme editor.