Introduction

What is Sutra UI?

Sutra UI is a component library for Phoenix LiveView applications. Unlike traditional component libraries that rely on JavaScript frameworks, Sutra UI is built entirely with Phoenix LiveView and Elixir, using colocated hooks for client-side interactivity where needed.

Components use semantic HTML, ARIA patterns where appropriate, and keyboard behavior for interactive controls. The styling is built on Tailwind CSS v4 with CSS variables, making it easy to customize themes.

Key Features

• Zero JavaScript Dependencies - All interactivity is powered by Phoenix LiveView colocated hooks. No npm packages required.
• Accessibility-minded - Semantic markup, visible focus states, screen reader support, and keyboard behavior where components need it.
• Dark Mode Built-in - Every component supports light and dark modes using CSS variables.
• Phoenix 1.8+ Ready - Built for modern Phoenix with LiveView 1.2+ and Tailwind CSS v4.
• Customizable - Override styles with Tailwind classes or customize the CSS variables to match your brand.

Runtime Colocated Hooks

Sutra UI uses Phoenix LiveView's colocated hooks feature (introduced in Phoenix 1.8). Most hooks are runtime hooks rendered by their component; extracted hooks are merged into your LiveSocket. Hook code is defined alongside HEEx templates using a special script tag syntax:

<div id="my-component" phx-hook=".MyHook">
<!-- Component content -->
</div>

<script :type={Phoenix.LiveView.ColocatedHook} name=".MyHook">
export default {
mounted() {
  // Hook logic here
}
}
</script>

Note the .MyHook naming convention with the dot prefix. This is required for local colocated hooks. Runtime hooks are rendered by their components, while extracted hooks are bundled through Phoenix's generated phoenix-colocated module.

Philosophy

Sutra UI follows a "CSS-first" approach to theming. Instead of JavaScript-based theme providers, components use CSS custom properties (variables) that can be changed at the document level. This means themes work without any JavaScript and can be changed instantly.

Components are designed to be composable. Complex UIs are built by combining simple, focused components rather than using monolithic "kitchen sink" components with dozens of props.

Getting Started

Ready to start using Sutra UI? Head over to the Installation Guide to add it to your Phoenix project.