Skip to main content

​
Overview

Theme Switching in Userpilot allows you to dynamically adapt in-app experiences, such as modals, tooltips, banners, and checklists, to match your application’s active theme (for example, light mode or dark mode). This is especially useful for products that support multiple visual themes and want Userpilot content to feel native, consistent, and seamless within the host application. By using the userpilot.theme() function, you can control which theme Userpilot uses at runtime, ensuring that content shown in live mode always aligns with your product’s UI state.

​
Use cases

  • Light/Dark mode support: When your application allows users to toggle between light and dark modes, Userpilot content should adapt automatically to avoid visual clashes or accessibility issues.
  • Brand or tenant-based theming: For multi-tenant or white-labeled products, different customers may use different brand themes. Theme Switching ensures the right Userpilot theme is applied per tenant or account.
  • Improved accessibility and readability: Ensuring correct contrast, background, and typography based on the theme improves usability and WCAG compliance.

​
How theme switching works in Userpilot

Userpilot supports theme control via a JavaScript API methoduserpilot.theme(). This method tells Userpilot which theme should be active so that all live content (flows, tooltips, banners, etc.) renders using the correct theme styles.
Important: Theme switching affects content shown in live mode. It does not change your app’s theme, only how Userpilot content is displayed.

​
How to switch between themes for live content

  1. First, make sure you have created the relevant themes (e.g. light, dark) in your Userpilot theme settings.
  2. Your application should already know which theme is active (for example, from user preferences, system settings, or a global state).
  3. When the theme changes (or on initial page load), call the Userpilot API with the appropriate theme name:
userpilot.theme('dark');
or 
userpilot.theme('light');
  1. Once set, any Userpilot content that appears in live mode will automatically render using the selected theme. without needing to reload the page or re-trigger flows.
  • You can dynamically change the primary color of a theme using
    userpilot.theme({ primary: "PRIMARY_COLOR" }).This allows you to customize the primary color per user or account without the need to create and maintain 20+ separate themes. It’s especially useful for applications that support color customization or white-labeling.
  • You can disable the applied theme at any time by calling userpilot.theme(0). This stops the selected theme from rendering on live Userpilot content without needing a page reload or flow re-trigger.

​
Best practices

  1. Call userpilot.theme() early in your app lifecycle (e.g. after user login or app initialization)
  2. Re-call the method when the theme changes, especially if users can toggle themes at runtime
  3. Keep theme naming consistent between your app and Userpilot (e.g. light, dark, high-contrast)
  4. Test in live mode, not just previews, to ensure the behavior matches real user experiences