How to switch between light and dark mode

Userorbit supports both light and dark themes for the widget and customer portal. You can set a fixed theme, or let the widget automatically match your user system preference. This guide covers all the options.

Step 1: Open theme mode settings

Navigate to Settings → Design in your dashboard. At the top of the Design panel, you will find the Theme Mode selector with three options.

Step 2: Choose your mode

Select one of the following options:

Light — the widget always displays in light mode regardless of the user system or browser settings. Use this when your application is exclusively light-themed.
Dark — the widget always displays in dark mode. Use this when your application has a dark interface and you want the widget to match.
System — the widget automatically detects the user operating system or browser color scheme preference and switches between light and dark mode accordingly. This is the recommended option for applications that support both themes.

How system preference detection works

When you select System, the widget uses the prefers-color-scheme CSS media query to detect the user current preference. Here is how it behaves:

If the user operating system is set to dark mode (e.g., macOS dark appearance, Windows dark theme), the widget renders in dark mode.
If the user switches their system theme while viewing your application, the widget updates immediately without a page reload.
If the user browser does not support the media query (rare in modern browsers), the widget falls back to light mode.

Forcing a specific theme via the SDK

If your application manages its own theme toggle independently of the operating system, you can override the dashboard setting programmatically using the Userorbit SDK:

Pass the theme option when initializing the widget:

theme: "light" — forces light mode.
theme: "dark" — forces dark mode.
theme: "system" — follows the system preference.

This is useful when your application has its own dark mode toggle that does not necessarily match the OS-level setting. You can listen for your app theme change event and reinitialize or update the widget theme accordingly.

Customizing colors for each mode

When you configure colors in the Design settings, you set values for your currently selected mode. If you use the System option, make sure to configure colors for both light and dark modes:

Select Light mode in the preview toggle.
Configure your colors and verify they look correct.
Switch to Dark mode in the preview toggle.
Adjust colors for the dark variant — typically a darker background, lighter text, and potentially adjusted primary and accent colors for better contrast.
Save your changes.

Best practices

Always test both modes — even if you default to one mode, preview the other to catch contrast or readability issues.
Use the System option when possible — it respects user preferences and provides the best experience for users who have chosen a specific theme for accessibility or comfort reasons.
Match your app behavior — if your application supports dark mode, your Userorbit widget should too. A light widget inside a dark app creates a jarring experience.
Check accent colors — some colors that work well on a light background may not provide sufficient contrast on a dark background and vice versa.

Help Center