SutraUI (Sutra UI v0.4.0)

Sutra UI - We define the rules, so you don't have to.

A pure Phoenix LiveView UI component library with 55 components, CSS-first theming, and colocated JavaScript hooks. Built for Phoenix 1.8+ and Phoenix LiveView 1.2+ with Tailwind CSS v4.

Quick Start

# mix.exs
{:sutra_ui, "~> 0.4.0"}

# lib/my_app_web.ex
defp html_helpers do
  quote do
    use SutraUI
  end
end

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

See the Installation Guide for detailed setup instructions.

Requirements

Dependency	Version	Notes
Elixir	1.20+	Matches the package constraint
Phoenix	1.8+	Required for colocated hooks
Phoenix LiveView	1.2+	Current supported LiveView line
Tailwind CSS	v4	CSS-first configuration

Why Phoenix 1.8+?

Sutra UI uses colocated hooks - JavaScript hooks defined alongside components. Runtime hooks need no app-side hook file; extracted hooks such as dialog and animated response are merged into LiveSocket.

Components by Category

Foundation

Basic building blocks for any interface.

Component	Description
`SutraUI.Button`	Buttons with 6 variants and 4 sizes
`SutraUI.Badge`	Status indicators
`SutraUI.Spinner`	Loading indicators
`SutraUI.Kbd`	Keyboard shortcut display

Form Controls

Complete form toolkit with validation support.

Component	Description
`SutraUI.Input`	Text, email, password, number, date inputs
`SutraUI.Textarea`	Multi-line text input
`SutraUI.Checkbox`	Checkbox input
`SutraUI.Switch`	Toggle switch
`SutraUI.RadioGroup`	Radio button groups
`SutraUI.Select`	Searchable dropdown (hook)
`SutraUI.Slider`	Range slider (hook)
`SutraUI.RangeSlider`	Dual-handle range (hook)
`SutraUI.LiveSelect`	LiveComponent async searchable select (hook)
`SutraUI.Label`	Form labels
`SutraUI.SimpleForm`	Form with auto-styling
`SutraUI.InputGroup`	Input with prefix/suffix
`SutraUI.InputOTP`	One-time password inputs (hook)
`SutraUI.FileUpload`	LiveView upload dropzone
`SutraUI.FilterBar`	Filter controls layout

Layout

Structure and organize content.

Component	Description
`SutraUI.Card`	Content container
`SutraUI.Header`	Page headers
`SutraUI.Table`	Data tables
`SutraUI.Item`	List items
`SutraUI.Drawer`	Navigation drawer (hook)
`SutraUI.Stepper`	Multi-step progress indicators
`SutraUI.StepperWizard`	Multi-step wizard shell
`SutraUI.TreeView`	Hierarchical navigation trees

Feedback

Communicate status and progress.

Component	Description
`SutraUI.Alert`	Alert messages
`SutraUI.Flash`	Phoenix flash messages
`SutraUI.Toast`	Toast notifications (hook)
`SutraUI.Progress`	Progress bars
`SutraUI.Skeleton`	Loading placeholders
`SutraUI.Empty`	Empty states
`SutraUI.LoadingState`	Loading indicators

Overlay

Layered UI elements.

Component	Description
`SutraUI.Dialog`	Modal dialogs (hook)
`SutraUI.Popover`	Click-triggered popups (hook)
`SutraUI.Tooltip`	Hover and focus tooltips (hook)
`SutraUI.DropdownMenu`	Dropdown menus (hook)
`SutraUI.ContextMenu`	Right-click action menus (hook)
`SutraUI.HoverCard`	Hover preview cards (hook)
`SutraUI.Command`	Command palette (hook)

Navigation

Help users move through your app.

Component	Description
`SutraUI.Tabs`	Tab panels (hook)
`SutraUI.Accordion`	Collapsible sections
`SutraUI.Breadcrumb`	Breadcrumb trails
`SutraUI.Pagination`	Page navigation
`SutraUI.TabNav`	Routed tab-style navigation

Display

Present content and media.

Component	Description
`SutraUI.Avatar`	User avatars
`SutraUI.Carousel`	Image carousels (hook)
`SutraUI.ThemeSwitcher`	Light/dark theme event button (hook)
`SutraUI.Separator`	Visual content dividers
`SutraUI.Marquee`	Scrolling content banners
`SutraUI.Calendar`	Monthly calendar grid
`SutraUI.Timeline`	Chronological event lists

AI

Composable primitives for AI-assisted interfaces.

Component	Description
`SutraUI.Response`	Text responses with reveal styles, or streamed Markdown
`SutraUI.Activity`	Safe user-facing agent progress with slot-owned rows

Theming

Sutra UI uses CSS variables compatible with shadcn/ui themes.

:root {
  --primary: oklch(0.65 0.20 260);
  --primary-foreground: oklch(0.98 0 0);
}

See the Theming Guide for complete customization options.

Accessibility

Sutra UI components use accessibility patterns appropriate to their behavior:

Semantic HTML elements
ARIA roles and attributes for composite widgets
Keyboard navigation for interactive components
Focus management where applicable
Screen reader support for status-style components

See the Accessibility Guide for details.

Guides

Installation - Setup and configuration
Theming - Customize colors and styles
Accessibility - ARIA and keyboard support
JavaScript Hooks - Colocated hook patterns

Quick Reference

Components Cheatsheet - All components at a glance
Forms Cheatsheet - Form patterns and validation

Summary

Functions

__using__(opts)

Use Sutra UI in your Phoenix application.

Functions

using(opts)

(macro)

Use Sutra UI in your Phoenix application.

This macro imports Sutra UI function components for use in your templates. SutraUI.LiveSelect is a LiveComponent; render it with <.live_component module={SutraUI.LiveSelect} ... />. The macro imports its decode/1 and normalize_options/1 helpers.

Example

defmodule MyAppWeb do
  def html_helpers do
    quote do
      use SutraUI
    end
  end
end