PhoenixKit.ThemeConfig (phoenix_kit v2.7.0)

Theme configuration utilities for PhoenixKit's DaisyUI integration.

This module centralises the theme metadata used across the admin UI so that PhoenixKit and the consuming application stay in sync. Updating or adding a theme requires changing this module and the shared CSS asset only.

Host configuration

This is the page a host developer theming their app lands on, so the knobs live here too — a real install went un-branded for weeks because the one below was documented nowhere a themer would look:

config :phoenix_kit, dashboard_themes: [...] — which themes the admin picker offers. Defaults to :all (the entire daisyUI catalogue). Most branded hosts want exactly their pair:
```
config :phoenix_kit, dashboard_themes: ["phoenix-light", "phoenix-dark"]
```
Exactly two concrete themes — one light, one dark — render as a sun/moon toggle instead of a dropdown; any other shape (more themes, "system" in the list, or a same-base pair) keeps the dropdown, because three or more states need a menu and sun/moon semantics need both bases.
Palette overrides go through :theme_definitions — see the "Host configuration" section: override built-in palettes or define new named themes entirely from config. The old workaround (out-ranking the inline <style> from host CSS via html[data-theme=...] selectors) still works but is no longer needed.

Summary

Functions

all_theme_names()

Returns all theme names recognised by PhoenixKit.

base_map()

Returns a map of theme names to their base variant ("light" or "dark").

custom_theme_css()

Returns the custom PhoenixKit theme definitions as a CSS string.

custom_theme_variables()

Returns the raw custom theme variable map.

default_html_theme()

Returns the initial theme applied to the <html> element on first render.

default_theme()

Returns the logical default theme name stored in the user's preferences.

dropdown_themes(filter \\ :all)

Returns the ordered list of themes displayed in dropdown selectors.

host_theme_meta()

Host-defined themes only: %{name => %{label, base}} for the lookups.

label_map()

Returns a map of theme names to user-facing labels.

system_pair()

The light/dark pair the "system" theme resolves to.

theme_variables()

The effective per-theme variable maps: built-ins with host :theme_definitions merged in. Validated once and cached; raises on the first invalid entry rather than dropping it.

translated_label(theme)

Returns the translated, user-facing label for a theme key.

translated_label_map()

Returns a map of theme names to translated, user-facing labels.

Functions

all_theme_names()

Returns all theme names recognised by PhoenixKit.

base_map()

Returns a map of theme names to their base variant ("light" or "dark").

custom_theme_css()

Returns the custom PhoenixKit theme definitions as a CSS string.

Only custom PhoenixKit themes are included here; DaisyUI-built themes are shipped with the DaisyUI plugin.

custom_theme_variables()

Returns the raw custom theme variable map.

default_html_theme()

Returns the initial theme applied to the <html> element on first render.

default_theme()

Returns the logical default theme name stored in the user's preferences.

dropdown_themes(filter \\ :all)

Returns the ordered list of themes displayed in dropdown selectors.

Options

:all or nil - Returns all themes (default), built-in catalogue then host :theme_definitions names
List of theme names - Returns only the specified themes in order

Examples

# All themes
dropdown_themes()
dropdown_themes(:all)

# Only specific themes
dropdown_themes(["system", "light", "dark", "nord", "dracula"])

host_theme_meta()

Host-defined themes only: %{name => %{label, base}} for the lookups.

Fully validated — this is the path the JS embeds (base_map/0, label_map/0, system_pair/0) read from, so it applies the same rules as theme_variables/0 rather than trusting the raw config. An early version read the config directly; a definition the CSS validator would have rejected (or crashed on) sailed through here into inline scripts.

label_map()

Returns a map of theme names to user-facing labels.

system_pair()

The light/dark pair the "system" theme resolves to.

Derived from :dashboard_themes when it is a list: the first configured name whose base is light, and the first whose base is dark. Either half falls back to the built-in phoenix-* theme, so a host configuring only one side still resolves both. With no configuration (:all), the built-ins. The bootstrap script and every theme-JS block should take the pair from here rather than hardcoding phoenix-light/phoenix-dark — hardcoding broke system resolution for any host whose pair uses other names.

theme_variables()

The effective per-theme variable maps: built-ins with host :theme_definitions merged in. Validated once and cached; raises on the first invalid entry rather than dropping it.

translated_label(theme)

Returns the translated, user-facing label for a theme key.

@labels is a compile-time module attribute, so it can't hold macro-expanded gettext/1 calls directly — this function is the translated counterpart, with one literal gettext/1 call per theme so mix gettext.extract can find them.

translated_label_map()

Returns a map of theme names to translated, user-facing labels.

Same shape as label_map/0 but locale-aware — use this (not label_map/0) for anything rendered to a user, including client-side JS embeds built from a JSON-encoded map.