# Theming

## Overview

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

***

## Theme Configuration

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```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;
}
```

{% hint style="warning" %}
CSS overrides may break in future SDK versions. Prefer using the `theme` configuration when possible.
{% endhint %}

***

## 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.

```bash
cd partner-sdk/examples
npm install
npm run dev
```

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