> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Theming

> Customize the ABHA SDK colors to match your application's branding

# ABHA SDK - Customizing the Theme

The ABHA SDK supports full color-token overriding. You can pass a `theme` object during initialization to match your application's branding.

## Passing theme to initAbhaApp

The `theme` parameter is an optional key in `initAbhaApp`. Pass it alongside your other configuration:

| Name    | Type     | Required    | Description                                                                                                                          |
| ------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `theme` | `object` | ⚙️ Optional | Color token overrides to match your organisation's design system. All keys are optional — only supply the tokens you want to change. |

```javascript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  clientId: "ext",
  theme: {
    // pass only the tokens you want to override
  },
  data: { /* ... */ },
  onSuccess: (params) => { /* ... */ },
  onError: (params) => { /* ... */ },
});
```

## Default Theme Colors

If no theme is provided, the SDK uses the following default values:

```typescript theme={null}
const defaultAbhaColors = {
  semantic: {
    error: '#BD0F0F',
    warning: '#FCB069',
    success: '#27B961',
  },
  primary: {
    brand: '#6B5CE0', // Main buttons, radios, and active states
  },
  surface: {
    base: '#FFFFFF',      // Background of pages
    subtle: '#F2F4F7',    // Card backgrounds
    muted: '#E4E7EC',     // Dividers and borders
    strong: '#BEC5D0',
    success: '#D5F6E2',   // Success background alerts
    neutral: '#0000000D',
    danger: '#DD3F3F',
    abhaCard: '#232477',  // Specific background for the ABHA ID card
  },
  content: {
    primary: '#111B31',   // Heading and main text
    secondary: '#4B596D', // Subtext
    muted: '#9EA8B8',     // Disabled or placeholder text
    success: '#1B7E43',   // Success text
    enabled: '#ffffff',   // Enabled button text color
  },
  qrCodeColors: {
    fgColor: '#000000',   // Color of the QR code dots
    bgColor: '#FFFFFF'    // Background of the QR code
  }
};
```

## Overriding the Theme

To customize the look, add the `theme` key to your `initAbhaApp` configuration:

```typescript theme={null}
window.initAbhaApp({
  containerId: "sdk_container",
  clientId: "ext",
  theme: {
    primary: {
      brand: '<your_org_primary_color>',    // Brand color
    },
    semantic: {
      error: '<your_semantic_error_color>',
      warning: '<your_semantic_warning_color>',
      success: '<your_semantic_success_color>',
    },
    surface: {
      base: '<your_base_color>',            // Background of pages
      subtle: '<your_subtle_color>',        // Card backgrounds
      muted: '<your_muted_color>',          // Dividers and borders
      strong: '<your_strong_color>',
      success: '<your_success_color>',      // Success background alerts
      neutral: '<your_neutral_color>',
      danger: '<your_danger_color>',
      abhaCard: '<your_abhaCard_color>',    // Specific background for the ABHA ID card
    },
    content: {
      primary: '<your_content_primary_color>',     // Heading and main text
      secondary: '<your_content_secondary_color>', // Subtext
      muted: '<your_content_muted_color>',         // Disabled or placeholder text
      success: '<your_content_success_color>',     // Success text
      enabled: '<enabled_button_text_color>',      // Enabled button text color
    },
    qrCodeColors: {
      fgColor: '<your_qrcode_dot_color>',  // Color of the QR code dots
      bgColor: '<your_qrcode_bg_color>'    // Background of the QR code
    }
  },
  data: {
    orgIconUrl: "https://your-domain.com/logo.png",
    // ... rest of your data
  },
  onSuccess: (params) => { /* ... */ },
  onError: (params) => { /* ... */ },
  // ... other methods
});
```

## Troubleshooting

### Common Theming Issues

#### 1. Button Not Visible or Hard to See

**Problem**: A button appears invisible, blends into the background, or is difficult to read.

**Cause**: This typically happens when `primary.brand` and `content.enabled` are too similar (e.g., both set to white or both dark), making the button label invisible against its background.

**Solution**:

* Ensure `primary.brand` (button background) and `content.enabled` (button text) have sufficient contrast.
* A dark `primary.brand` should pair with a light `content.enabled` (e.g., `#ffffff`), and vice versa.

```typescript theme={null}
theme: {
  primary: {
    brand: ‘#1A237E’,   // Dark button background
  },
  content: {
    enabled: ‘#FFFFFF’, // Light text on button — must contrast with brand
  },
}
```

#### 2. Color Discrepancy — Overrides Not Taking Effect

**Problem**: You passed a theme but some colors still appear as defaults.

**Cause**: Token keys may be misspelled, nested incorrectly, or using the wrong casing.

**Solution**:

* Double-check that your token keys exactly match the structure in [Default Theme Colors](#default-theme-colors). The SDK performs a shallow merge — missing or misnamed keys fall back to defaults silently.
* Verify nesting: tokens like `surface.base` must be passed as `surface: { base: ‘...’ }`, not as a flat key.

```typescript theme={null}
// ❌ Wrong — flat key, will be ignored
theme: {
  ‘surface.base’: ‘#F9FAFB’,
}

// ✅ Correct — nested object
theme: {
  surface: {
    base: ‘#F9FAFB’,
  },
}
```

#### 3. Success / Error States Look Off

**Problem**: Success alerts, error messages, or validation states are visually inconsistent or unreadable.

**Cause**: Overriding only `semantic.success` without also updating `surface.success` and `content.success` (or vice versa) breaks the foreground/background pairing for state banners.

**Solution**: Always override semantic state colors as a group — the background surface token, the text content token, and the semantic indicator token together.

| State   | Tokens to keep in sync                                   |
| ------- | -------------------------------------------------------- |
| Success | `semantic.success`, `surface.success`, `content.success` |
| Error   | `semantic.error`, `surface.danger`                       |
| Warning | `semantic.warning`                                       |

#### 4. ABHA Card Color Not Changing

**Problem**: The ABHA ID card background color is not updating despite passing a theme.

**Solution**: The card background is controlled by `surface.abhaCard`, not `surface.base` or `primary.brand`. Pass it explicitly:

```typescript theme={null}
theme: {
  surface: {
    abhaCard: ‘#1A237E’, // Override the ABHA card background
  },
}
```

#### 5. QR Code Invisible or Unreadable

**Problem**: The QR code is not scannable or appears blank.

**Cause**: `qrCodeColors.fgColor` and `qrCodeColors.bgColor` may have been set to the same or similar colors.

**Solution**: Maintain high contrast between the QR dot color and background — black on white is the most reliable combination for scanner compatibility.

```typescript theme={null}
theme: {
  qrCodeColors: {
    fgColor: ‘#000000’, // QR dots — keep dark
    bgColor: ‘#FFFFFF’, // QR background — keep light
  },
}
```