White-Label Themes
Implementation guide for white-label theming, brand-specific configurations, and dynamic theme switching.
White-Label Themes
Overview
This guide explains how to implement white-label theming in our React Native application, enabling the app to dynamically adapt its visual identity based on different brand configurations. It covers brand configuration structure, runtime theme switching, and integration with the app initialization flow.
Quick Start
Create a brand configuration file:
Purpose & Scope
This document provides implementation guidance for:
- Creating and organizing brand configurations
- Loading brand-specific themes during app initialization
- Switching brands at runtime
- Integrating white-label themes with the core theme system
- Handling brand-specific assets and feature flags
The guide is intended for developers implementing multi-brand or white-label solutions in our React Native application.
Prerequisites
Before implementing white-label themes, ensure you are familiar with:
- Theme Management - Core concepts
- Theme Implementation - Basic theme setup
- App Initialization - Initialization flow
- React Context and State Management concepts
Implementation Details
Brand Configuration Structure
The white-label system is built around a standardized BrandConfig type that defines all customizable aspects of a brand:
White-Label Store
The white-label configuration is managed through a central store:
White-Label Service
A service layer handles brand switching and persistence:
Theme Loader
A specialized loader handles loading brand configurations from different sources:
Integration with Theme Provider
To integrate white-label themes with the theme system, modify the ThemeProvider:
White-Label Hooks
Create hooks for accessing white-label configuration in components:
Usage Patterns
Brand-Specific Components
Components can consume the brand configuration to render brand-specific UI:
Brand Switcher UI
Create a UI component to allow users to switch between brands:
Feature Flag Usage
Use white-label feature flags to conditionally enable functionality:
Animation Strategies
Implement smooth animations when switching between brands:
Best Practices & Security
Performance Considerations
-
(Do ✅) Cache brand configurations
- Store loaded brand configs in memory cache
- Persist to device storage for faster startup
-
(Do ✅) Lazy load brand-specific assets
- Only load assets for the current brand
- Consider implementing asset preloading for faster switching
-
(Do ✅) Optimize theme merging
- Use memoization to prevent unnecessary re-renders
- Only merge the specific properties that differ
-
(Don't ❌) Load all brand assets at startup
- This increases bundle size and startup time
- Instead, load dynamically as needed
Troubleshooting
Common Issues and Solutions
| Issue | Possible Cause | Solution |
|---|---|---|
| Brand styles not applying | Incorrect theme merging | Verify theme merging logic in ThemeProvider |
| Missing brand assets | Incorrect path or bundling issue | Check asset paths and bundle configuration |
| Brand selection not persisting | Storage issue | Verify AsyncStorage implementation and permissions |
| Feature flags not working | Incorrect flag naming | Ensure feature flag names match between code and config |
| Slow brand switching | Large asset files | Optimize asset sizes and implement progressive loading |
Related Documents
Core References
- Theme Management - Core concepts and architecture overview
- Theme Implementation - Basic theming implementation
Architecture Documents
- App Initialization - Theme initialization during app startup
- Core Architecture - Overall application architecture
- Project Structure - Project organization including brand assets
UI & Assets
- Assets & Media Overview - Managing theme-specific assets
- component-patterns - Building brand-aware components
Theme Architecture
Reference document explaining core theming concepts and system design.
Theme Implementation
Guide for implementing basic theming in components.
Summary
Implementing white-label themes enables your application to dynamically adapt its visual identity based on different brand configurations. Key implementation points include:
- Creating a standardized brand configuration structure
- Loading brand configurations during the Pre-UI initialization stage
- Integrating with the core theme system through theme merging
- Providing hooks and utilities for accessing brand-specific data
- Implementing smooth animations for brand switching
By following these patterns, you can create a flexible, maintainable white-label solution that supports multiple brands within a single codebase.