gurujada/sutra_ui/sutra-ui

Sutra UI

Sutra UI is a Phoenix LiveView component library inspired by shadcn/ui. It is CSS-first, uses Phoenix patterns, and avoids external JavaScript/npm dependencies.

Public Surface

Use these from application code:

• use SutraUI in the Phoenix web module's html_helpers.
• Render components as function components such as <.button>, <.input>,

<.popover>, <.calendar>, <.activity>, <.relative_time>, and <.response>.

• Pass Phoenix globals (phx-*, data-*, aria-*) through component attrs.
• Use documented slots for custom content instead of inventing many narrow attrs.
• Use exposed JS helper functions only when the component module documents them.

Do not use these from application code:

• Do not call private helpers or internal CSS/JS implementation details.
• Do not invent attrs such as on_click, completed, content_class, or

framework-style callback props unless the component module documents them.

• Do not add React, npm packages, Alpine, Stimulus, or third-party JS widgets.
• Do not replace Phoenix form validation, uploads, navigation, or events with

client-side state machines.

• Do not write style= attributes on or around Sutra components; use classes.
• Do not put phx-click on a flash box, or use the native <dialog> or

window.confirm() for a Sutra dialog or confirmation: use confirm_host/1 and data-confirm, or confirm_dialog/1.

For exact attrs, slots, or event names, inspect the component module in lib/sutra_ui/*.ex. This skill teaches Sutra's composition model; source code is the API authority.

Load The Relevant Reference

• For exact copy-paste component examples, read cheatsheets/components.cheatmd.
• For forms, changesets, validation, uploads, and selection controls, read

cheatsheets/forms.cheatmd.

• For component philosophy, forms, hook behavior, CSS rules, and API selection,

read skill/patterns.md.

• For common UI compositions, including popover + calendar, wizard forms,

activity feeds, uploads, menus, and AI surfaces, read skill/recipes.md.

• For editing Sutra UI internals or adding components, read usage_rules.md.

When building a full interface, start from the recipes and component cheatsheet, then inspect the relevant modules for exact attrs and slots before writing HEEx.

Core Rules

• Compose atomic primitives. Prefer a small Sutra component plus slots over a

large custom wrapper with many attrs.

• Keep app state in the parent LiveView. Sutra components render and emit normal

Phoenix events; they do not own business workflows.

• Use field={@form[:name]} for Phoenix form fields. Sutra input/1 reads

id, name, value, and touched-field errors from the form field.

• Use Phoenix.Component.used_input?/1 behavior for live validation. Do not

show all empty-field errors just because one field was edited.

• Use native inputs for native jobs. <.input type="date"> is the browser date

input; <.calendar> is a composable calendar grid for custom date flows.

• Hook-based components need stable ids. Do not auto-generate changing ids.
• Under a Content-Security-Policy, pass nonce to components that render runtime

hooks and render <SutraUI.ThemeSwitcher.theme_script nonce={@csp_nonce} /> in the root layout. The policy script-src 'self' 'nonce-…'; style-src 'self'; img-src 'self' data: then works: Sutra renders no style= attributes (computed sizes use data-pct), so never add them. See skill/recipes.md.

• In Sutra library source, component styling belongs in priv/static/sutra_ui.css

with semantic classes. In application templates, use class for layout and local composition, but do not rewrite component internals with utility soup.

• Sutra UI does not export a general icon component or icon set. Use the host

app's existing icon helper when present, otherwise use inline accessible SVG. Do not invent SutraUI.Icon or assume the demo app's <.icon> helper exists in user applications.

• For AI interfaces, show safe user-facing progress. Do not render private

reasoning; use activity/1 for visible steps and response/1 for streamed text or Markdown.

Component Map

• Foundation: button, badge, spinner, kbd
• Forms: date_picker, date_range_picker, time_picker, datetime_picker (with

SutraUI.DateRules; datetime needs a zone), input, textarea, checkbox, switch, radio_group, select (real <select> + SutraUI list; options, field, multiple, searchable, native), slider, range_slider, live_select (LiveComponent), input_otp, file_upload, simple_form, input_group, label (filter_bar is deprecated: use LiveTable filters)

• Layout/data: card, header, table, item, separator, marquee,

calendar, timeline, tree_view, stepper, stepper_wizard, drawer

• Feedback: alert, flash, progress, skeleton, empty,

loading_state, toast_group (+ SutraUI.Toast.send/3), toast

• Overlays/actions: dialog, popover, tooltip, hover_card,

dropdown_menu, context_menu, command, command_palette

• Navigation: tabs (client-only, patch URL tabs, navigate tab bar), segmented, filter_tabs, accordion, breadcrumb, pagination,

tab_nav

• Display: avatar (status presence), avatar_group, carousel, theme_switcher, relative_time,

local_time

• AI: response, activity

Minimal Form Shape

<.form for={@form} phx-change="validate" phx-submit="save" class="form">
  <.input field={@form[:email]} type="email" label="Email" />
  <.input field={@form[:password]} type="password" label="Password" />
  <.button type="submit">Save</.button>
</.form>

def handle_event("validate", %{"user" => params}, socket) do
  changeset =
    %User{}
    |> Accounts.change_user(params)
    |> Map.put(:action, :validate)
 
  {:noreply, assign(socket, form: to_form(changeset))}
end

Common Mistakes

• Passing a callback prop when Phoenix should use phx-click, phx-change,

phx-submit, JS, or parent LiveView state.

• Using calendar/1 as a drop-in replacement for <input type="date">.
• Building a separate date picker component before composing popover/1,

calendar/1, and a parent LiveView.

• Showing all form errors immediately instead of respecting touched input state.
• Treating activity/1 as private reasoning output instead of safe progress.
• Hiding custom content behind rigid attrs when a slot would be simpler.
• Copying demo-specific layout or marketing copy into reusable app components.
• Dismissing a flash by clicking its box: only its × button closes it.
• Using window.confirm() or a second toast system: render toast_group once and

confirm_host once in the layout; confirm only what cannot be undone, offer Undo in a toast for the rest.

• Passing CSS values (width="200px", gap="1rem") to skeleton/1 or

carousel/1: pass classes (w-48, gap-4); the CSS form was removed in 0.5.

• Leaving the chevron on an icon-only dropdown_menu/1 trigger: pass

chevron={false}.