ShadcnEx

Use shadcn/ui components in Phoenix LiveView. ShadcnEx extracts component metadata from the upstream shadcn/ui registry and generates Phoenix function components with matching props, variants, and slots.

Currently ships the new-york-v4 style with Tailwind CSS v4.

Installation

Add the dependency:

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

Run the installer to copy assets and patch your app.js/app.css:

mix shadcn.install

The installer will:

Copy hooks.js and shadcn_ex.css to your app's priv/static/shadcn_ex/
Patch assets/js/app.js with import statements (managed block)
Patch assets/css/app.css with a Tailwind v4 @source directive for class discovery

Each patch is shown as a diff with a y/N prompt before applying.

Installer Options

Flag	Description
`--force`	Skip prompts, auto-apply all patches (CI mode)
`--check`	Verify install completeness, exit non-zero on drift
`--no-tailwind-patch`	Skip `@source` patching in app.css
`--app <name>`	Target a specific app in an umbrella project

For umbrella projects, the installer auto-detects web apps (apps with an assets/ directory). If multiple are found, it prompts which to target. Use --app to skip the prompt.

Verifying Install in CI

mix shadcn.install --check

Returns exit code 0 if all managed blocks and assets are in place, non-zero otherwise.

Usage

Add use ShadcnEx to your LiveView or component module:

defmodule MyAppWeb.PageLive do
  use MyAppWeb, :live_view
  use ShadcnEx
end

Then use standard HEEx component syntax. Each shadcn sub-component maps to its own function component:

<.button variant="outline" size="sm">Save</.button>

<.card>
  <.card_title>Agents</.card_title>
  <.card_description>Runtime groups</.card_description>
  <.card_content>
    <.badge variant="secondary">Configured</.badge>
  </.card_content>
  <.card_footer>Synced just now</.card_footer>
</.card>

Validate Config

Optionally check that your project's Tailwind version and shadcn style are compatible:

mix shadcn.validate_config

For informational-only mode (no failure on warnings):

mix shadcn.validate_config --no-strict

JS Hooks

ShadcnEx ships a tiered hook system for components that need client-side interactivity. The installer patches your app.js automatically, but you can also import manually:

import { initHybridComponents, setupAutoInit } from "shadcn_ex/hooks"

// Initialize all [data-js-mount] elements currently in the DOM
initHybridComponents()

// Or auto-init on LiveView mount events
setupAutoInit()

Tier 1 — Vanilla JS

Safe hooks using only DOM APIs and optional vanilla JS libraries:

sidebar — toggle expanded/collapsed state via data-state attribute
sonner — toast notifications using CSS classes and design tokens
embla-carousel — carousel with optional autoplay (requires embla-carousel npm package)

Tier 2 — LiveView Bridges

Lightweight DOM utilities that bridge user interactions to LiveView server events:

command-palette — Cmd+K / Ctrl+K listener, toggles data-state, pushes LiveView event
drawer — open/close via trigger elements, CSS transitions, Escape to close

Tier 3 — Unsupported

React-only libraries that cannot run without a React runtime. These emit a one-time console warning with guidance:

recharts, react-day-picker, react-hook-form, base-ui, cmdk, vaul

For these components, use a React adapter (e.g., LiveSvelte, LiveReact) or a native Elixir alternative.

Compatibility

mix shadcn.validate_config detects:

shadcn style from config :shadcn_ex, :style or components.json
Tailwind major from assets/package.json (fallback: assets/css/app.css / tailwind config files)

Current behavior:

new-york-v4 requires Tailwind 4
new-york / default are treated as Tailwind 3
strict mode (default) fails on mismatch or missing required detection signals

Hardcoded Colors

The generated component registry includes a hardcoded_colors list per component, flagging Tailwind classes that use absolute colors (e.g., bg-white) rather than design tokens. Check ShadcnEx.Registry.component("button") to see which classes may need theme overrides.

Development

For library maintainers only.

Extract Manifest

Re-extract component metadata from upstream shadcn/ui:

mix shadcn.extract
mix shadcn.extract --style new-york-v4 --ref main

Generate Registry

Rebuild the Elixir registry from the manifest:

mix shadcn.codegen

Tests

npx tsx --test scripts/extract_shadcn.test.ts
mix test