Installation

Get up and running with Sutra UI in your Phoenix project.

Sutra UI requires Phoenix 1.8+, LiveView 1.2+, and Tailwind CSS v4.

Quick Install

The fastest way to get started. Add the dependency and run the installer: 

# mix.exs
def deps do
  [
    {:sutra_ui, "~> 0.4.0"}
  ]
end

Then run: 

mix deps.get
mix sutra_ui.install

The installer configures your CSS and web module automatically. Runtime colocated hooks work from the rendered components; extracted hooks such as dialog and animated response should be merged into your LiveSocket.

Manual Installation

If you prefer to configure things manually, follow these steps:

1

Add the dependency

Add sutra_ui to your dependencies in mix.exs : 

def deps do
  [
    {:sutra_ui, "~> 0.4.0"}
  ]
end

Then fetch the dependencies: 

mix deps.get
2

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.

3

Setup CSS

In your assets/css/app.css , add the Sutra UI source path and import after the Tailwind import: 

@import "tailwindcss";

/* Sutra UI */
@source "../../deps/sutra_ui/lib";
@import "../../deps/sutra_ui/priv/static/sutra_ui.css";
4

Import components

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

defp html_helpers do
  quote do
    use SutraUI
    # ... other imports
  end
end

This imports all components. You can also import selectively: 

# Import only what you need
import SutraUI.Button
import SutraUI.Input
5

Merge extracted hooks

In assets/js/app.js , merge the generated Sutra UI hooks into your LiveSocket hook map: 

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

const liveSocket = new LiveSocket("/live", Socket, {
  hooks: {...sutraUiHooks}
})
6

Verify installation

Start your Phoenix server and try a component: 

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

If everything is set up correctly, you should see a styled button.

Next Steps

Now that you have Sutra UI installed:

Icons

Sutra UI does not include an icon component — you're free to use any icon library you prefer. We recommend Lucide as it pairs well with our design aesthetic. Add the dependency to your mix.exs, create a Tailwind plugin, and use icons as CSS classes:

mix.exs 
{:lucide_icons,
 github: "lucide-icons/lucide",
 sparse: "icons",
 app: false,
 compile: false,
 depth: 1}

Then use icons anywhere with Tailwind classes: 

<span class="lucide--check size-4" />