Skip to main content

​
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:
NameTypeRequiredDescription
themeobject⚙️ OptionalColor token overrides to match your organisation’s design system. All keys are optional — only supply the tokens you want to change.
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: 
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: 
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.
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. 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.
// ❌ 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.
StateTokens to keep in sync
Successsemantic.success, surface.success, content.success
Errorsemantic.error, surface.danger
Warningsemantic.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: 
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. 
theme: {
  qrCodeColors: {
    fgColor: ‘#000000’, // QR dots — keep dark
    bgColor: ‘#FFFFFF’, // QR background — keep light
  },
}