;
};
Themes and modes let you adapt the look and feel of your product to match different brand identities and user preferences — making BEEQ suitable for both consumer-facing apps and internal tools.
BEEQ also supports mixing modes within the same layout, so individual sections can use a different color scheme from the rest of the page.
Explore related sections: [Colors](/foundations/colors), [Global CSS Variables](/theming/global-css-variables), and [Customization](/theming/custom-theme).
***
## Applying themes
BEEQ lets you apply themes using either HTML attributes (recommended) or CSS classes, ensuring a consistent look for every application.
### Using HTML attributes
Set the `bq-theme` attribute on the `` element (recommended) or the `` tag.
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Using CSS classes
Alternatively, apply themes using CSS classes directly on the root element.
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
When applying a theme, maintain consistency and avoid mixing different themes throughout the app.
***
## Applying modes
Modes let you switch between light and dark color schemes to match user preferences or specific app needs. You can control modes globally or for specific sections using HTML attributes or CSS classes.
### Using HTML attributes
Set the `bq-mode` attribute to control the color scheme.
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Using CSS classes
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Combining modes
You can mix and match modes at various levels of your layout. For instance, you might use dark mode for the main section of your app and switch to light mode for a nested component.
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
***
## User's color scheme preferences
**BEEQ does not automatically detect or apply the user's preferred color scheme.** It is up to you to control whether users see light or dark mode in your app. To provide a better experience:
* Make the `prefers-color-scheme` setting your default.
* Allow users to switch this option in your app.
* Remember their choice and apply it when they log in or return to the app.
The `prefers-color-scheme` media query is not used by BEEQ automatically, as not all applications support dark mode, which might cause problems for those that don't.
### Example
Here is a working example showing how to read the user's preferred color scheme on load and let them toggle it using a `bq-switch`.
Toggle the `bq-switch` in the live preview below to switch between light and dark mode. You can also use the Mintlify top-bar toggle to change the page mode and see how the theme variables adapt.
:host {
flex-direction: column !important;
align-items: stretch !important;
padding: 0 !important;
}
.nav-bar {
display: flex;
justify-content: center;
background-color: var(--bq-ui--primary);
border-bottom: 1px solid var(--bq-stroke--primary);
}
.nav-bar__main {
flex: 1;
display: flex;
align-items: center;
flex-direction: row;
justify-content: flex-end;
gap: var(--bq-spacing-xl);
padding: var(--bq-spacing-m);
max-width: 1440px;
}
.nav-bar__mode {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
color: var(--bq-text--primary);
}
.main {
padding: var(--bq-spacing-m);
}
.main h1 {
margin-block-end: var(--bq-spacing-l);
color: var(--bq-text--primary);
}
.content {
background: var(--bq-ui--alt);
border: 2px dashed var(--bq-stroke--primary);
height: 10rem;
width: 100%;
}
Dashboard
`}
>
```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
.nav-bar {
display: flex;
justify-content: center;
background-color: var(--bq-ui--primary);
border-bottom: 1px solid var(--bq-stroke--primary);
}
.nav-bar__main {
flex: 1;
display: flex;
align-items: center;
flex-direction: column;
justify-content: end;
gap: var(--bq-spacing-xl);
padding: var(--bq-spacing-m);
max-width: 1440px;
@media (min-width: 600px) {
flex-direction: row;
}
}
.nav-bar__mode {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
color: var(--bq-text--primary);
}
.main {
padding: var(--bq-spacing-m);
h1 {
margin-block-end: var(--bq-spacing-l);
}
}
.content {
background: var(--bq-ui--alt);
border: 2px dashed var(--bq-stroke--primary);
height: 10rem;
width: 100%;
}
```
```ts TypeScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import type { BqSwitchCustomEvent } from '@beeq/core';
import "./styles.css";
const switcher = document.querySelector('bq-switch[name="mode"]') as HTMLBqSwitchElement | null;
if (!switcher) {
throw new Error('bq-switch[name="mode"] not found');
}
// Get the user's preferred color scheme when the page loads
const prefersDark = window.matchMedia
? window.matchMedia('(prefers-color-scheme: dark)').matches
: false;
// Reflect initial theme mode based on the user's color scheme
switcher.checked = prefersDark;
setThemeMode(prefersDark);
// Handle changes from the BEEQ switch button interaction
switcher.addEventListener('bqChange', (event: BqSwitchCustomEvent<{ checked: boolean }>) => {
setThemeMode(event.detail.checked);
});
function setThemeMode(isDark: boolean) {
document.documentElement.setAttribute('bq-mode', isDark ? 'dark' : 'light');
}
```
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
BEEQ Theme Mode
```
***
## Next steps
Follow the step-by-step guide to create and apply a fully custom theme to your app.
Explore the color tokens and base variables that power BEEQ themes and modes.