mix phia.theme (phia_ui v0.1.15)

Copy Markdown View Source

Manage PhiaUI color theme presets from the command line.

PhiaUI ships with 8 built-in color presets (zinc, slate, blue, rose, orange, green, violet, neutral). This task lets you list them, apply one as your project's active theme, export/import themes as JSON, and generate a static multi-theme CSS file for runtime color switching.

Commands at a glance

mix phia.theme list
mix phia.theme apply <theme_name>
mix phia.theme export <theme_name> [--format css|json]
mix phia.theme import <path_to_json>
mix phia.theme install [--output PATH] [--themes a,b,c]

list

Displays all available built-in presets with their primary OKLCH color value.

$ mix phia.theme list

PhiaUI — Available Themes

  NAME         LABEL                PRIMARY (light)
  --------------------------------------------------------
  blue         Blue                 oklch(0.546 0.245 262.881)
  green        Green                oklch(0.527 0.154 150.069)
  neutral      Neutral              oklch(0.205 0 0)
  orange       Orange               oklch(0.645 0.246 37.304)
  rose         Rose                 oklch(0.592 0.241 349.615)
  slate        Slate                oklch(0.208 0.042 265.755)
  violet       Violet               oklch(0.541 0.281 293.009)
  zinc         Zinc                 oklch(0.211 0.005 285.82)

apply

Applies a built-in preset by writing its CSS variables to the project's assets/css/theme.css (falls back to priv/static/theme.css if the assets path does not exist). Creates the file if it does not exist.

Use this command when you want a single, fixed theme for your project.

$ mix phia.theme apply zinc
Applied theme 'zinc' to assets/css/theme.css

$ mix phia.theme apply blue
$ mix phia.theme apply rose

After applying, refresh your browser or restart the Phoenix server to see the new colors.

export

Prints the JSON or CSS representation of a built-in theme to stdout. Redirect to a file to save it.

Use --format json (default) for a portable JSON representation that can later be re-imported or shared with a designer. Use --format css to get the scoped CSS blocks ready for manual inclusion.

$ mix phia.theme export zinc > my-brand.json
$ mix phia.theme export blue --format css
$ mix phia.theme export zinc --format json

The CSS output uses [data-phia-theme="<name>"] attribute selectors and is identical to what mix phia.theme install generates for each theme.

import

Imports a custom theme from a JSON file and writes its CSS variables to assets/css/theme.css. The JSON must follow the same schema produced by export --format json.

$ mix phia.theme import ./my-brand.json
Imported theme 'my-brand' to assets/css/theme.css

Typical workflow for a custom brand theme:

# 1. Export an existing theme as a starting point
$ mix phia.theme export zinc > my-brand.json

# 2. Edit my-brand.json to adjust colors, radius, etc.

# 3. Import it back
$ mix phia.theme import my-brand.json

install

Generates a phia-themes.css file containing all (or a selected subset of) themes, each scoped to [data-phia-theme="<name>"] attribute selectors. Also injects an @import into assets/css/app.css so TailwindCSS v4 picks up the file.

This is the command to use when you want runtime color switching — users can switch between themes without a page reload by changing the data-phia-theme attribute on <html> (handled automatically by the PhiaTheme JavaScript hook).

$ mix phia.theme install
Generated assets/css/phia-themes.css with 8 theme(s)
Injected @import into assets/css/app.css

# Write to a custom path
$ mix phia.theme install --output assets/css/my-themes.css

# Only include a subset of presets
$ mix phia.theme install --themes zinc,blue,rose

Options

  • --output PATH — output file path (default: "assets/css/phia-themes.css")
  • --themes LIST — comma-separated preset names (default: all 8 built-in themes)

Using the generated file

Once installed, activate a theme by setting the data-phia-theme attribute:

<!-- In your root layout -->
<html data-phia-theme="blue" class="dark">

Or use the PhiaTheme JavaScript hook for interactive runtime switching:

<button phx-hook="PhiaTheme" data-theme="rose">Switch to Rose</button>
<select phx-hook="PhiaTheme">
  <option value="zinc">Zinc</option>
  <option value="blue">Blue</option>
</select>

The hook reads the selected value and writes it to localStorage under the key phia-color-theme, then sets data-phia-theme on <html>.