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+.

• Zero JavaScript dependencies - No React, no npm packages, no node_modules bloat. Just Phoenix LiveView.
• CSS-first theming - Customize colors with CSS variables. No build step, no config files.
• Copy-paste friendly - Like shadcn/ui, components are meant to be understood and modified.
• Server-driven - All state lives on the server. No client-side state sync headaches.
• Production-ready - 776 tests, full accessibility support, dark mode included.
• LLM-friendly - Includes usage_rules.md with guidelines for AI assistants working with this codebase.

• 44 Components - Buttons, forms, dialogs, tables, and more
• Pure LiveView - No external JavaScript frameworks
• Colocated Hooks - JS hooks live with their components (Phoenix 1.8+)
• CSS Variables - Override any color in one line
• Accessible - WCAG 2.1 AA compliant, keyboard navigable
• Dark Mode - Built-in light/dark theme support
• Lightweight - ~2500 lines of CSS, minimal JS hooks

# 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

mix sutra_ui.install

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

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.

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.

Update your deployment aliases in mix.exs:

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

<.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>

Sutra UI uses CSS custom properties for theming. Override them in your app.css after 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);
}

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 */
}

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

• button - Buttons with variants (primary, secondary, destructive, outline, ghost, link)
• input - Text inputs (text, email, password, number, date, etc.)
• textarea - Multi-line text input
• checkbox - Checkbox input
• switch - Toggle switch
• radio_group - Radio button groups
• select - Custom dropdown with search
• slider - Range slider
• range_slider - Dual-handle range slider
• live_select - Async searchable select with tags
• simple_form - Form with auto-styling
• input_group - Input with prefix/suffix
• filter_bar - Filter controls layout

• card - Content container with header/footer
• header - Page header with title/actions
• table - Data table
• item - List item component
• drawer - Collapsible drawer navigation

• alert - Alert messages
• badge - Status badges
• progress - Progress bar
• spinner - Loading spinner
• skeleton - Loading placeholder
• empty - Empty state
• loading_state - Loading indicator with message
• toast - Toast notifications

• dialog - Modal dialogs
• popover - Click-triggered popups
• tooltip - Hover tooltips
• dropdown_menu - Dropdown menus
• command - Command palette with search

• tabs - Tab panels
• accordion - Collapsible sections
• breadcrumb - Breadcrumb navigation
• pagination - Page navigation
• nav_pills - Pill-style navigation
• tab_nav - Tab-style navigation

• avatar - User avatars with fallback
• carousel - Image/content carousel
• kbd - Keyboard shortcut display
• label - Form labels
• theme_switcher - Light/dark mode toggle

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

• CSS-first styling patterns
• Required ID attributes for hook-based components
• Event naming conventions (sutra-ui:* namespace)
• Component structure patterns
• Testing conventions

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

All components follow WAI-ARIA patterns:

• Semantic HTML elements
• Proper ARIA roles and attributes
• Keyboard navigation (Tab, Arrow keys, Enter, Escape)
• Focus management and visible focus indicators
• Screen reader announcements

• Chrome/Edge 120+
• Firefox 120+
• Safari 17+

Requires support for:

• CSS @layer
• CSS custom properties
• CSS :has() selector
• <dialog> element
• Popover API (progressive enhancement)

MIT License - see LICENSE for details.

• HexDocs - Full API reference
• Installation Guide - Setup for Phoenix 1.8+ and Tailwind v4
• Theming Guide - CSS variables, OKLCH colors, shadcn themes
• Accessibility Guide - ARIA patterns, keyboard navigation
• JavaScript Hooks - Colocated hooks, custom events
• Components Cheatsheet - Quick reference for all 44 components
• Forms Cheatsheet - Form patterns and validation

• GitHub
• Changelog