Dark Mode
It’s effortless to switch Dark Mode in Phoenix. You can enable Dark Mode by default or create a Dark/Light switch if you want. To set the default mode "Dark",you can also set system default theme in Phoenix. Please see the configuration page.
Toggle Dark Mode
Toggling dark mode is very easy in Phoenix. You can toggle dark, light or auto mode by using checkbox, radio input, switch input and custom icon component.
<div class="row g-4">
<div class="col">
<h5 class="text-base mb-2">Checkbox </h5>
<div class="form-check"><input class="form-check-input" id="flexCheckDefault" type="checkbox" data-theme-control="phoenixTheme" /><label class="form-check-label" for="flexCheckDefault">Dark mode</label></div>
</div>
<div class="col">
<h5 class="text-base mb-2">Switch Input</h5>
<div class="form-check form-switch ps-0"><input class="form-check-input ms-0 me-2" id="switchDarkModeExample" type="checkbox" data-theme-control="phoenixTheme" /><label for="switchDarkModeExample">Dark Mode</label></div>
</div>
<div class="col">
<h5 class="text-base mb-2">Custom icon</h5>
<div class="theme-control-toggle fa-ion-wait pe-2"><input class="form-check-input ms-0 theme-control-toggle-input" id="themeControlToggleDoc" type="checkbox" data-theme-control="phoenixTheme" value="dark" /><label class="mb-0 theme-control-toggle-label theme-control-toggle-light" for="themeControlToggleDoc" data-bs-toggle="tooltip" data-bs-placement="left" title="Switch theme"><span class="icon" data-feather="moon"></span></label><label class="mb-0 theme-control-toggle-label theme-control-toggle-dark" for="themeControlToggleDoc" data-bs-toggle="tooltip" data-bs-placement="left" title="Switch theme"><span class="icon" data-feather="sun"></span></label></div>
</div>
<div class="col">
<h5 class="text-md mb-2">Dropdown</h5>
<div class="dropdown theme-control-dropdown"><button class="btn btn-sm btn-phoenix-secondary dropdown-toggle dropdown-caret-none" type="button" id="themeSwitchDropdown" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="fas fa-sun" data-theme-dropdown-toggle-icon="light"></span><span class="fas fa-moon" data-theme-dropdown-toggle-icon="dark"></span><span class="fas fa-adjust" data-theme-dropdown-toggle-icon="auto"></span></button>
<div class="dropdown-menu dropdown-caret border py-0 mt-2" aria-labelledby="themeSwitchDropdown">
<div class="rounded-md py-2"><button class="dropdown-item flex items-center gap-2" type="button" value="light" data-theme-control="phoenixTheme"><span class="fas fa-sun"></span>Light<span class="fas fa-check dropdown-check-icon ms-auto text-body-quaternray"></span></button><button class="dropdown-item flex items-center gap-2" type="button" value="dark" data-theme-control="phoenixTheme"><span class="fas fa-moon" data-fa-transform=""></span>Dark<span class="fas fa-check dropdown-check-icon ms-auto text-body-quaternray"></span></button><button class="dropdown-item flex items-center gap-2" type="button" value="auto" data-theme-control="phoenixTheme"><span class="fas fa-adjust" data-fa-transform=""></span>Auto<span class="fas fa-check dropdown-check-icon ms-auto text-body-quaternray"></span></button></div>
</div>
</div>
</div>
<div class="col-12">
<h5 class="text-base mb-2">Radio button</h5>
<div class="form-check-inline"><input class="form-check-input" id="flexRadioDefault1" type="radio" value="light" data-theme-control="phoenixTheme" /><label class="form-check-label" for="flexRadioDefault1">Light</label></div>
<div class="form-check-inline"><input class="form-check-input" id="flexRadioDefault2" type="radio" value="dark" data-theme-control="phoenixTheme" /><label class="form-check-label" for="flexRadioDefault2">Dark</label></div>
<div class="form-check-inline"><input class="form-check-input" id="flexRadioDefault3" type="radio" value="auto" data-theme-control="phoenixTheme" /><label class="form-check-label" for="flexRadioDefault3">Auto</label></div>
</div>
</div>Checkbox
Switch Input
Custom icon
Dropdown
Radio button
Toggling dark mode manually
<h5 class="mb-3">1. Custom dark mode selector</h5>
<p class="mb-3">Phoenix Tailwind supports class-based dark mode using predefined color variables. To enable dark mode with a custom selector (instead of prefers-color-scheme), add the following after importing Tailwind and Hummingbird styles:</p><pre><code class="language-css">@custom-variant dark (&:where(.dark, .dark *), .dark);</code></pre>
<p class="mt-3 mb-7">The <code>.dark </code> class is typically added or removed on the <code><html></code> element.</p>
<h5 class="mb-3">2. Set the initial theme</h5>
<p class="mb-3">Add this inline script inside the <code><head></code> tag to ensure the correct theme is applied before the page renders. This prevents flash issues and respects both the user’s saved preference in localStorage and their system’s <code>prefers-color-scheme </code>setting.</p><pre><code class="language-js"><script>
// On page load or when changing themes, best to add inline in head to avoid FOUC
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
</script></code></pre>1. Custom dark mode selector
Phoenix Tailwind supports class-based dark mode using predefined color variables. To enable dark mode with a custom selector (instead of prefers-color-scheme), add the following after importing Tailwind and Hummingbird styles:
@custom-variant dark (&:where(.dark, .dark *), .dark);The .dark class is typically added or removed on the <html> element.
2. Set the initial theme
Add this inline script inside the <head> tag to ensure the correct theme is applied before the page renders. This prevents flash issues and respects both the user’s saved preference in localStorage and their system’s prefers-color-scheme setting.
<script>
// On page load or when changing themes, best to add inline in head to avoid FOUC
document.documentElement.classList.toggle(
"dark",
localStorage.theme === "dark" ||
(!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
</script>How to use
<p class="mb-3">Phoenix Tailwind supports dark mode out of the box, and all components are fully compatible with it. No additional configuration is required to enable dark mode styles.</p>
<p class="mb-3">To apply additional styling specifically for dark mode, use the <code>dark: </code> variant alongside utility classes. This ensures that elements automatically adjust their appearance whenever the <code>.dark </code>class is active.</p><pre><code class="language-html"><div class="bg-subtle text-primary dark:text-secondary">
<p>This content adapts to dark mode</p>
</div></code></pre>
<p class="mt-7 mb-3">In addition to using the <code>dark:</code> variant, Phoenix Tailwind’s theme variables can be directly overridden within a dark scope:</p><pre class="language-css"><code class="lang-css">:root, :host {
@variant dark {
--color-primary: var(--color-blue-400);
--color-secondary: var(--color-purple-400);
}
}
</code></pre>Phoenix Tailwind supports dark mode out of the box, and all components are fully compatible with it. No additional configuration is required to enable dark mode styles.
To apply additional styling specifically for dark mode, use the dark: variant alongside utility classes. This ensures that elements automatically adjust their appearance whenever the .dark class is active.
<div class="bg-subtle text-primary dark:text-secondary">
<p>This content adapts to dark mode</p>
</div>In addition to using the dark: variant, Phoenix Tailwind’s theme variables can be directly overridden within a dark scope:
:root, :host {
@variant dark {
--color-primary: var(--color-blue-400);
--color-secondary: var(--color-purple-400);
}
}
Using the Dark CSS classes in HTML
<h5 class="mb-4">You can keep a style constant regardless of dark mode</h5>
<p>If you want a component to retain it’s color as it is regardless of the dark mode, you can use the following classes -</p>
<p> <code>[data-hb-theme="dark"]</code> - It will keep the color dark even if the current mode is light</p>
<p>The following example illustrate the color persistency -</p>
<div class="row gx-4">
<div class="col-12">
<h5 class="mb-3">Keep the color dark even if the current mode is light</h5>
<div class="card bg-body-highlight mb-3" data-hb-theme="dark">
<div class="card-body">
<p class="mb-0 text-body-tertiary font-bold">This element will retain its color if you switch between light and dark modes.</p>
</div>
</div><pre class="mt-2"><code class="language-html"><div class="card bg-body-highlight" data-hb-theme="dark">
<div class="card-body">
<p class="mb-0 text-body-tertiary font-bold">This element will retain its color if you switch between light and dark modes.</p>
</div>
</div></code></pre>
</div>
</div>
<h6 class="text-base mt-6">Override Background and Text color only for dark mode</h6>
<p>If you want to use a different text color or background color rather than the default dark theme color for any element, you can use the special "dark" classes: </p>
<ul>
<li> <code>dark:bg-* </code></li>
<li><code>dark:text-* </code></li>
</ul>
<p class="mb-3">The following element illustrates the example:</p>
<div class="mb-3 card bg-light dark:bg-primary">
<div class="card-body">
<p class="mb-0 font-bold dark:text-white">This element will get different bg color rather than the default dark theme color.</p>
</div>
</div><pre class="mt-2"><code class="language-html"><div class="card bg-light dark:bg-primary">
<div class="card-body">
<p class="mb-0 font-bold dark:text-white">This element will get different bg color rather than the default dark theme color.</p>
</div>
</div></code></pre>You can keep a style constant regardless of dark mode
If you want a component to retain it’s color as it is regardless of the dark mode, you can use the following classes -
[data-hb-theme="dark"] - It will keep the color dark even if the current mode is light
The following example illustrate the color persistency -
Keep the color dark even if the current mode is light
This element will retain its color if you switch between light and dark modes.
<div class="card bg-body-highlight" data-hb-theme="dark">
<div class="card-body">
<p class="mb-0 text-body-tertiary font-bold">This element will retain its color if you switch between light and dark modes.</p>
</div>
</div>Override Background and Text color only for dark mode
If you want to use a different text color or background color rather than the default dark theme color for any element, you can use the special "dark" classes:
-
dark:bg-* dark:text-*
The following element illustrates the example:
This element will get different bg color rather than the default dark theme color.
<div class="card bg-light dark:bg-primary">
<div class="card-body">
<p class="mb-0 font-bold dark:text-white">This element will get different bg color rather than the default dark theme color.</p>
</div>
</div>Emit JavaScript event on color scheme change
<p>When you switch between the dark and light mode, or change any settings from the global theme config at runtime, we emit an event <code>clickControl</code>.<br />We used this event to update colors using JavaScript. For example, the charts change their colors using this event. You can catch and use this event with the following code snippet:</p><pre><code class="lang-js">const themeController = document.body;
themeController.addEventListener(
"clickControl",
({ detail: { control, value } }) => {
if (control === "phoenixTheme") {
// value will be localStorage theme value (dark/light/auto)
const mode = value === 'auto' ? window.phoenix.utils.getSystemTheme() : value;
console.log(mode)
// your code here
}
}
);</code></pre>When you switch between the dark and light mode, or change any settings from the global theme config at runtime, we emit an event clickControl.
We used this event to update colors using JavaScript. For example, the charts change their colors using this event. You can catch and use this event with the following code snippet:
const themeController = document.body;
themeController.addEventListener(
"clickControl",
({ detail: { control, value } }) => {
if (control === "phoenixTheme") {
// value will be localStorage theme value (dark/light/auto)
const mode = value === 'auto' ? window.phoenix.utils.getSystemTheme() : value;
console.log(mode)
// your code here
}
}
);
