# Theme System Guide
PhiaUI uses a **CSS-first theme system** inspired by DaisyUI. Themes are pre-generated as static
CSS with `[data-phia-theme]` attribute selectors. Activating a theme requires only setting an HTML
attribute — no JavaScript CSS injection, no runtime recalculation.
## Table of Contents
- [Quick Setup](#quick-setup)
- [How it Works](#how-it-works)
- [Built-in Color Presets](#built-in-color-presets)
- [Activating a Theme](#activating-a-theme)
- [Scoped Themes (ThemeProvider)](#scoped-themes-themeprovider)
- [Runtime Theme Switching (PhiaTheme)](#runtime-theme-switching-phiatheme)
- [Anti-FOUC Script](#anti-fouc-script)
- [Customising Themes](#customising-themes)
- [Custom Color Presets](#custom-color-presets)
- [Mix Tasks Reference](#mix-tasks-reference)
- [localStorage Reference](#localstorage-reference)
---
## Quick Setup
```bash
# 1. Generate the multi-theme CSS file
mix phia.theme install
# → creates assets/css/phia-themes.css
# → injects @import into assets/css/app.css automatically
# 2. Add the unified anti-FOUC script to (see below)
# 3. Activate a preset
#
```
---
## How it Works
### The two CSS files
PhiaUI uses two CSS files:
| File | Purpose |
|------|---------|
| `priv/static/theme.css` | Base `@theme` tokens, radius, typography, `@custom-variant dark` |
| `assets/css/phia-themes.css` | All 8 color presets as `[data-phia-theme]` selectors |
In your `app.css`:
```css
@import "tailwindcss";
@import "../../../deps/phia_ui/priv/static/theme.css";
@import "./phia-themes.css"; ← added by mix phia.theme install
```
### CSS cascade
Tailwind v4 generates `bg-primary` as `background-color: var(--color-primary)`.
CSS custom properties inherit through the DOM. A `[data-phia-theme="blue"]` on any
ancestor makes every `bg-primary` inside use the blue primary color — automatically.
```css
/* phia-themes.css (generated) */
[data-phia-theme="zinc"] {
--color-primary: oklch(0.141 0 0);
--color-primary-foreground: oklch(0.985 0 0);
/* ... all color tokens ... */
}
.dark [data-phia-theme="zinc"] {
--color-primary: oklch(0.985 0 0);
--color-primary-foreground: oklch(0.141 0 0);
}
[data-phia-theme="blue"] {
--color-primary: oklch(0.546 0.245 262.881);
/* ... */
}
```
### Dark + color theme composition
```html
```
The `.dark [data-phia-theme="blue"]` selector has specificity 0,2,0 and correctly
overrides the light-mode values. ✅
---
## Built-in Color Presets
| Preset | Key | Personality |
|--------|-----|-------------|
| Zinc | `zinc` | Neutral dark — shadcn/ui default |
| Slate | `slate` | Cool blue-grey |
| Blue | `blue` | Enterprise blue |
| Rose | `rose` | Modern rose/pink |
| Orange | `orange` | Energetic orange |
| Green | `green` | Success green |
| Violet | `violet` | Premium violet |
| Neutral | `neutral` | Pure grey |
Preview all presets:
```bash
mix phia.theme list
```
---
## Activating a Theme
### App-wide
Set `data-phia-theme` on the `` element in your `root.html.heex`:
```heex
```
Or hard-code it statically:
```html
```
### In a Phoenix LiveView layout
```elixir
defmodule MyAppWeb.Layouts do
use Phoenix.Component
def app(assigns) do
~H"""
...
<%= @inner_content %>
"""
end
end
```
---
## Scoped Themes (ThemeProvider)
`<.theme_provider>` sets `data-phia-theme` on a wrapper div, scoping the theme to
only the enclosed content. Ideal for multi-tenant apps, preview panels, or themed sections.
```heex
<%!-- Default app uses zinc, but this card uses rose --%>
<.theme_provider theme={:rose}>
<.card>
<.card_header>
<.card_title class="text-primary">Rose Card
<.card_content>
<.button>Rose Button
```
### With a struct (custom or tenant theme)
```elixir
# In your LiveView
def mount(_params, %{"org_id" => org_id}, socket) do
theme = MyApp.Orgs.get_theme(org_id) # returns %PhiaUi.Theme{}
{:ok, assign(socket, :org_theme, theme)}
end
```
```heex
<.theme_provider theme={@org_theme}>
<%= @inner_content %>
```
### nil theme — no-op
```heex
<%!-- No data-phia-theme attribute rendered --%>
<.theme_provider theme={nil}>
<.button>Uses default theme
```
### Required: phia-themes.css
`<.theme_provider>` requires `phia-themes.css` to be imported. Without it, the attribute
is set but no CSS custom properties are applied.
```bash
mix phia.theme install
```
---
## Runtime Theme Switching (PhiaTheme)
The `PhiaTheme` hook enables users to switch color presets without a page reload.
### Setup
```javascript
// assets/js/app.js
import PhiaTheme from "./phia_hooks/theme"
let liveSocket = new LiveSocket("/live", Socket, {
hooks: { PhiaTheme, PhiaDarkMode, /* other hooks */ }
})
```
### With a select element
```heex
```
### With buttons
```heex