Installation

This guide walks you through setting up Sutra UI in your Phoenix application.

Prerequisites

Sutra UI requires:

Step 1: Add Dependencies

Add sutra_ui to your dependencies in mix.exs:

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

Then fetch dependencies:

mix deps.get

Step 2: Delete core_components.ex

Sutra UI provides a complete replacement for Phoenix's default core_components.ex, including the icon/1 component.

Delete the generated file:

rm lib/my_app_web/components/core_components.ex

Then remove the import from your lib/my_app_web.ex:

defmodule MyAppWeb do
  # ...

  defp html_helpers do
    quote do
      # Remove or comment out this line:
      # import MyAppWeb.CoreComponents
      
      use SutraUI  # Add this instead (Step 5)
      
      # ... other imports
    end
  end
end

Step 3: Configure Tailwind CSS v4

Sutra UI is built for Tailwind CSS v4, which uses a CSS-first configuration approach.

In your assets/css/app.css:

@import "tailwindcss";

/* Add Sutra UI source paths for Tailwind to scan */
@source "../../deps/sutra_ui/lib";

/* Import Sutra UI component styles */
@import "../../deps/sutra_ui/priv/static/sutra_ui.css";

/* Your app's custom styles below... */

Step 4: Setup JavaScript Hooks

Sutra UI components use colocated JavaScript hooks. Add the hooks import to your assets/js/app.js:

import { hooks as sutraUiHooks } from "phoenix-colocated/sutra_ui";

Then spread them into your LiveSocket configuration:

const liveSocket = new LiveSocket("/live", Socket, {
    params: { _csrf_token: csrfToken },
    hooks: { ...sutraUiHooks },  // Add other hooks here too
});

# mix.exs
"assets.deploy": [
  "compile",  # Must come first
  "esbuild my_app --minify",
  "tailwind my_app --minify",
  "phx.digest"
]

Step 5: Import Components

In your lib/my_app_web.ex, add use SutraUI to your html_helpers:

defmodule MyAppWeb do
  # ...

  defp html_helpers do
    quote do
      use SutraUI  # Imports all 44 components
      
      # ... other imports
    end
  end
end

Alternatively, import only the components you need:

defmodule MyAppWeb.SomeLive do
  use MyAppWeb, :live_view
  
  import SutraUI.Button
  import SutraUI.Dialog
  import SutraUI.Input
  
  # ...
end

Step 6: Verify Installation

Create a simple test to verify everything works:

<.button>Hello Sutra UI!</.button>

<.button variant="destructive">
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="mr-2 size-4" aria-hidden="true"><path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/><line x1="10" x2="10" y1="11" y2="17"/><line x1="14" x2="14" y1="11" y2="17"/></svg>
  Delete
</.button>

<.button variant="outline" size="sm">Small Outline</.button>

If you see styled buttons, you're ready to go!

Troubleshooting

Components render but have no styles

Cause: Tailwind isn't scanning the Sutra UI source files.

Fix: Ensure you have the @source directive in your app.css:

@source "../../deps/sutra_ui/lib";

Then restart your Phoenix server and asset watcher.

"undefined function" errors for components

Cause: Components not imported.

Fix: Add use SutraUI to your html_helpers or import specific components.

Conflicts with core_components

Cause: Both core_components.ex and Sutra UI define components like button/1, input/1, etc.

Fix: Delete lib/my_app_web/components/core_components.ex and remove its import from your web module (see Step 2).

Hook-based components don't work (Select, Dialog, Tabs, etc.)

Cause: Colocated hooks require Phoenix 1.8+.

Fix: Upgrade Phoenix:

# mix.exs
{:phoenix, "~> 1.8"}

Then run:

mix deps.update phoenix

CSS variables not applying

Cause: Sutra UI styles not imported or loaded after your overrides.

Fix: Ensure the import order is correct:

@import "tailwindcss";
@source "../../deps/sutra_ui/lib";
@import "../../deps/sutra_ui/priv/static/sutra_ui.css";

/* Your overrides AFTER sutra_ui.css */
:root {
  --primary: oklch(0.65 0.20 145);
}

Dark mode not working

Cause: Missing dark class on <html> element.

Fix: Add the theme switcher or manually toggle the class:

<.theme_switcher id="theme-toggle" />

Or control it manually:

document.documentElement.classList.toggle('dark')

Next Steps

• Theming Guide - Customize colors and styles
• Components Cheatsheet - Quick reference for all components
• JavaScript Hooks - Understanding colocated hooks