Sutra UI

Hex.pmHex DocsLicense

We define the rules, so you don’t have to.

A pure Phoenix LiveView UI component library inspired by shadcn/ui.

Built for Phoenix 1.8+, Tailwind CSS v4, and Phoenix LiveView 1.1+.

Why Sutra UI?

Features

Installation

1. Add Dependency

# mix.exs
def deps do
  [
    {:sutra_ui, "~> 0.3.0"},
    {:jason, "~> 1.0"}  # Required for dropdown_menu and live_select
  ]
end

Then run:

mix deps.get

2. Run the Installer

mix sutra_ui.install

This handles CSS setup and adds use SutraUI to your web module’s html_helpers.

3. Delete core_components.ex

Sutra UI replaces Phoenix’s default core_components.ex. Delete it and remove its import:

rm lib/my_app_web/components/core_components.ex

In your my_app_web.ex, remove the import MyAppWeb.CoreComponents line.

4. Runtime Hooks (No JS Setup Required)

Sutra UI uses Phoenix 1.8+ runtime colocated hooks.

You do not need to import or register Sutra UI hooks in assets/js/app.js. Just render components and their hooks load automatically.

5. Deployment Setup

Update your deployment aliases in mix.exs:

"assets.deploy": [
  "compile",  # Required: extracts colocated hooks
  "esbuild my_app --minify",
  "tailwind my_app --minify",
  "phx.digest"
]

Usage

<.button>Click me</.button>

<.button variant="destructive">Delete</.button>

<.dialog id="confirm-dialog">
  <:trigger>
    <.button variant="outline">Open Dialog</.button>
  </:trigger>
  <:title>Confirm Action</:title>
  <:description>Are you sure you want to continue?</:description>
  <:footer>
    <.button variant="outline" phx-click={hide_dialog("confirm-dialog")}>
      Cancel
    </.button>
    <.button phx-click="confirm">Confirm</.button>
  </:footer>
</.dialog>

Theme Customization

Sutra UI uses CSS custom properties for theming. Override them in your app.cssafter importing sutra_ui.css:

@import "../../deps/sutra_ui/priv/static/sutra_ui.css";

/* Custom theme overrides */
:root {
  /* Primary brand color (buttons, links, focus rings) */
  --primary: oklch(0.65 0.20 145);        /* Green */
  --primary-foreground: oklch(0.98 0 0);  /* White text on primary */

  /* Destructive actions (delete buttons, error states) */
  --destructive: oklch(0.55 0.25 30);     /* Red */

  /* Border radius */
  --radius: 0.5rem;
}

/* Dark mode overrides */
.dark {
  --primary: oklch(0.70 0.18 145);
  --destructive: oklch(0.65 0.22 25);
}

Using shadcn/ui Themes

Since Sutra UI uses the same CSS variable names as shadcn/ui, you can copy theme variables directly from shadcn/ui themes and paste them into your app.css:

@import "../../deps/sutra_ui/priv/static/sutra_ui.css";

/* Paste your shadcn theme here - it just works! */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.141 0.005 285.823);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.141 0.005 285.823);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.141 0.005 285.823);
  --primary: oklch(0.21 0.006 285.885);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.967 0.001 286.375);
  --secondary-foreground: oklch(0.21 0.006 285.885);
  --muted: oklch(0.967 0.001 286.375);
  --muted-foreground: oklch(0.552 0.016 285.938);
  --accent: oklch(0.967 0.001 286.375);
  --accent-foreground: oklch(0.21 0.006 285.885);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  --border: oklch(0.92 0.004 286.32);
  --input: oklch(0.92 0.004 286.32);
  --ring: oklch(0.705 0.015 286.067);
  --radius: 0.5rem;
}

.dark {
  /* Dark mode variables from shadcn */
}

CSS Variables Reference

Variable Description Usage
--background Page background bg-background
--foreground Default text color text-foreground
--card Card backgrounds bg-card
--card-foreground Card text text-card-foreground
--popover Popover/dropdown backgrounds bg-popover
--popover-foreground Popover text text-popover-foreground
--primary Primary brand color bg-primary, text-primary
--primary-foreground Text on primary backgrounds text-primary-foreground
--secondary Secondary/muted actions bg-secondary
--secondary-foreground Text on secondary text-secondary-foreground
--muted Muted backgrounds bg-muted
--muted-foreground Muted/placeholder text text-muted-foreground
--accent Hover/active states bg-accent
--accent-foreground Text on accent text-accent-foreground
--destructive Error/danger color bg-destructive
--destructive-foreground Text on destructive text-destructive-foreground
--border Border color border-border
--input Input border color border-input
--ring Focus ring color ring-ring
--radius Base border radius Used by rounded-lg, etc.

Color Format

Sutra UI uses OKLCH colors for better perceptual uniformity:

--primary: oklch(0.623 0.214 259.815);
/*         oklch(L     C     H      )
           L = Lightness (0-1)
           C = Chroma (0-0.4, saturation)
           H = Hue (0-360, color wheel)
*/

Common hues: Red ~30, Orange ~70, Yellow ~100, Green ~145, Cyan ~195, Blue ~260, Purple ~300, Pink ~350

Components

Form Controls

Layout

Feedback

Overlay

Navigation

Display

For AI Assistants

This library includes usage_rules.md with detailed guidelines for AI assistants (LLMs) working with this codebase. The file covers:

If you’re using an AI assistant to help modify or extend Sutra UI components, point it to usage_rules.md for context.

Accessibility

All components follow WAI-ARIA patterns:

Browser Support

Requires support for:

License

MIT License - see LICENSE for details.

Documentation

Links