# 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;
}
```<div data-gb-custom-block data-tag="hint" data-style='warning'>CSS overrides may break in future SDK versions. Prefer using the `theme` configuration when possible.</div>

***

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alternativepayments.io/web-sdk/theming.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.