Welcome to Petal Components
Shadcn-style Phoenix components that AI assistants can actually use.
Composable HEEx primitives (<.button>, <.modal>, <.table>, …), built on Tailwind v4, working in both LiveView and dead views. Plus a hosted MCP server so Claude Code, Cursor, Codex, and Windsurf write idiomatic petal_components instead of inventing raw Tailwind markup.
Live demo · GitHub · Hex · vs shadcn
Install
There are two ways to install. The first is fast and works for any AI-driven project. The second is the classic manual setup.
- The two-step way (recommended)
- Manual install
- Additional setup (VSCode snippets, Core Components conflicts, namespacing)
The two-step way (recommended)
1. Install the MCP server (once)
claude mcp add petal --transport http https://mcp.petal.build/mcp
For other AI coding tools (Cursor, Codex, Windsurf, Continue, Cline), see the per-tool setup snippets on the petal-components landing.
2. In your Phoenix project, tell your AI:
install petal_components
The agent calls get_install_instructions on the MCP, then patches your mix.exs, assets/css/app.css, assets/js/app.js and lib/<your_app>_web.ex to add the dependency, the Tailwind lines, the JS hooks and use PetalComponents, and finishes with mix compile --warnings-as-errors and a LiveView render check. Steps are idempotent. Works in umbrella apps too.
It can also call list_components and get_component <name> to read the real component schema before writing any HEEx, so the attrs and slots match what’s actually shipped.
Manual install
Prefer to do it by hand, or working in a project without an AI coding tool? Follow these steps.
Add the dependency
defp deps do
[
{:petal_components, "~> 4.18"},
]
end
Then mix deps.get.
If mix deps.get fails with a message naming websock_adapter, run mix deps.unlock websock_adapter && mix deps.get. Releases up to and including 4.18.0 declared websock_adapter ~> 0.5.7, and a new Phoenix 1.8 app locks 0.7.x. Later releases do not declare it.
Want the chat components (<Chat.conversation>, <Chat.markdown> and the rest)? Also add {:mdex, "~> 0.12"}. For <.qr_code>, add {:eqrcode, "~> 0.2"}. Nothing else needs an extra dependency.
Tailwind 4.1 or later
Phoenix 1.8 apps already run Tailwind 4.1 or later. An older app may still pin 4.0.x in config/config.exs. The @source not line below needs 4.1, so bump the version there:
config :tailwind,
version: "4.1.12",
default: [
args: ~w(
--input=assets/css/app.css
--output=priv/static/assets/app.css
),
cd: Path.expand("..", __DIR__)
]
Then run:
mix tailwind.install
CSS configuration
In Tailwind 4, tailwind.config.js is legacy. Configuration goes in CSS. Open assets/css/app.css and find the existing @import "tailwindcss" line (Phoenix 1.8 writes it as @import "tailwindcss" source(none);). Leave it exactly as it is, and don’t add a second one. Directly below it, add four lines:
@import "tailwindcss" source(none); /* already there */
@source "../../deps/petal_components/**/*.*ex";
@source not "../../deps/petal_components/lib/petal_components/showcase";
@import "../../deps/petal_components/assets/default.css";
@plugin "@tailwindcss/forms";
When you’re done, app.css has exactly one @import "tailwindcss" line. Line by line:
@source "../../deps/petal_components/**/*.*ex";
Tells Tailwind to scan the petal_components source for Tailwind utility usage. Required for the JIT compilation to pick up classes used inside components. The paths are relative to assets/css/, so they start with ../../deps.
@source not "../../deps/petal_components/lib/petal_components/showcase";
Skips the showcase/ example modules. They power the docs on this site, not your app, so scanning them only adds unused classes to your CSS.
@import "../../deps/petal_components/assets/default.css";
Brings in the default petal_components styles (the pc-* CSS class prefix used for component styling) and the default colour ramps.
@plugin "@tailwindcss/forms";
The form components are styled on top of the forms plugin. Without it, inputs have no border and no padding. The standalone Tailwind CLI that Phoenix uses already includes it, so there’s nothing to install. Skip the line if your app already loads it. If you build Tailwind through Node, run npm install -D @tailwindcss/forms in assets/.
Using <.prose>? It’s styled by the typography plugin, so also add @plugin "@tailwindcss/typography"; (the standalone CLI includes that one too).
Icons: Phoenix 1.8’s app.css already loads a heroicons plugin (@plugin "../vendor/heroicons";), and <.icon name="hero-..."> uses it. Keep it. If your app has no heroicons plugin, see Heroicons for older apps below.
Brand colours (optional)
Components work out of the box: default.css ships blue primary, pink secondary, the semantic hues and a zinc gray. They’re soft defaults, so a plain @theme block in your CSS wins. To change them, create assets/css/colors.css and import it in app.css after default.css with @import "./colors.css";. Map each role to any Tailwind hue, one line per stop:
@theme inline {
--color-primary-50: var(--color-blue-50);
--color-primary-100: var(--color-blue-100);
--color-primary-200: var(--color-blue-200);
--color-primary-300: var(--color-blue-300);
--color-primary-400: var(--color-blue-400);
--color-primary-500: var(--color-blue-500);
--color-primary-600: var(--color-blue-600);
--color-primary-700: var(--color-blue-700);
--color-primary-800: var(--color-blue-800);
--color-primary-900: var(--color-blue-900);
--color-primary-950: var(--color-blue-950);
--color-secondary-50: var(--color-pink-50);
--color-secondary-100: var(--color-pink-100);
--color-secondary-200: var(--color-pink-200);
--color-secondary-300: var(--color-pink-300);
--color-secondary-400: var(--color-pink-400);
--color-secondary-500: var(--color-pink-500);
--color-secondary-600: var(--color-pink-600);
--color-secondary-700: var(--color-pink-700);
--color-secondary-800: var(--color-pink-800);
--color-secondary-900: var(--color-pink-900);
--color-secondary-950: var(--color-pink-950);
--color-success-50: var(--color-green-50);
--color-success-100: var(--color-green-100);
--color-success-200: var(--color-green-200);
--color-success-300: var(--color-green-300);
--color-success-400: var(--color-green-400);
--color-success-500: var(--color-green-500);
--color-success-600: var(--color-green-600);
--color-success-700: var(--color-green-700);
--color-success-800: var(--color-green-800);
--color-success-900: var(--color-green-900);
--color-success-950: var(--color-green-950);
--color-danger-50: var(--color-red-50);
--color-danger-100: var(--color-red-100);
--color-danger-200: var(--color-red-200);
--color-danger-300: var(--color-red-300);
--color-danger-400: var(--color-red-400);
--color-danger-500: var(--color-red-500);
--color-danger-600: var(--color-red-600);
--color-danger-700: var(--color-red-700);
--color-danger-800: var(--color-red-800);
--color-danger-900: var(--color-red-900);
--color-danger-950: var(--color-red-950);
--color-warning-50: var(--color-yellow-50);
--color-warning-100: var(--color-yellow-100);
--color-warning-200: var(--color-yellow-200);
--color-warning-300: var(--color-yellow-300);
--color-warning-400: var(--color-yellow-400);
--color-warning-500: var(--color-yellow-500);
--color-warning-600: var(--color-yellow-600);
--color-warning-700: var(--color-yellow-700);
--color-warning-800: var(--color-yellow-800);
--color-warning-900: var(--color-yellow-900);
--color-warning-950: var(--color-yellow-950);
--color-info-50: var(--color-sky-50);
--color-info-100: var(--color-sky-100);
--color-info-200: var(--color-sky-200);
--color-info-300: var(--color-sky-300);
--color-info-400: var(--color-sky-400);
--color-info-500: var(--color-sky-500);
--color-info-600: var(--color-sky-600);
--color-info-700: var(--color-sky-700);
--color-info-800: var(--color-sky-800);
--color-info-900: var(--color-sky-900);
--color-info-950: var(--color-sky-950);
}
Only list the roles you want to change. Components read the semantic names, not the underlying Tailwind colors.
Heroicons for older apps
Skip this if your app.css already has a heroicons @plugin line (every Phoenix 1.8 app does). Otherwise it embeds Heroicons (https://heroicons.com) into your CSS bundle, reading the heroicons dependency Phoenix adds to mix.exs. Create assets/css/tailwind_heroicons.js, next to app.css:
const plugin = require("tailwindcss/plugin");
const fs = require("fs");
const path = require("path");
// Embeds Heroicons (https://heroicons.com) into your app.css bundle
// See your `CoreComponents.icon/1` for more information.
module.exports = plugin(function ({ matchComponents, theme }) {
let iconsDir = path.join(__dirname, "../../deps/heroicons/optimized");
let values = {};
let icons = [
["", "/24/outline"],
["-solid", "/24/solid"],
["-mini", "/20/solid"],
["-micro", "/16/solid"],
];
icons.forEach(([suffix, dir]) => {
fs.readdirSync(path.join(iconsDir, dir)).forEach((file) => {
let name = path.basename(file, ".svg") + suffix;
values[name] = { name, fullPath: path.join(iconsDir, dir, file) };
});
});
matchComponents(
{
hero: ({ name, fullPath }) => {
let content = fs
.readFileSync(fullPath)
.toString()
.replace(/\r?\n|\r/g, "");
let size = theme("spacing.6");
if (name.endsWith("-mini")) {
size = theme("spacing.5");
} else if (name.endsWith("-micro")) {
size = theme("spacing.4");
}
return {
[`--hero-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
"-webkit-mask": `var(--hero-${name})`,
mask: `var(--hero-${name})`,
"mask-repeat": "no-repeat",
"background-color": "currentColor",
"vertical-align": "middle",
display: "inline-block",
width: size,
height: "1lh",
};
},
},
{ values },
);
});
Then add @plugin "./tailwind_heroicons.js"; to app.css. The file sits in assets/css/, so both that path and the ../../deps path inside it resolve.
Import the components
Open lib/<your_app>_web.ex. def html, def live_view and def live_component all pull in html_helpers, but def live_view doesn’t go through def html, so an import in def html never reaches your LiveViews. Put it in html_helpers.
Phoenix 1.8’s generated core_components.ex also defines button/1, icon/1, input/1 and table/1. Import both and every call to those four is ambiguous, and the app stops compiling. So swap the generated import YourAppWeb.CoreComponents line for these two:
defmodule YourAppWeb
...
defp html_helpers do
quote do
...
use PetalComponents
import YourAppWeb.CoreComponents, except: [button: 1, icon: 1, input: 1, table: 1]
end
end
The rest of CoreComponents (flash/1, header/1, list/1 and friends) stays imported. If the compiler reports another call is ambiguous name (apps from older Phoenix versions also define modal/1), add it to the except: list.
use PetalComponents imports the core components, so you can call them as <.button>, <.modal>, etc. without explicit aliases. The Chat family isn’t part of that import: add alias PetalComponents.Chat and call them as <Chat.markdown>, <Chat.conversation>.
Pages from mix phx.gen.live and mix phx.gen.auth were written for the CoreComponents versions, so update their call sites:
-
<.input field={@form[:email]} label="Email" />becomes<.field field={@form[:email]} label="Email" />. petal_components’<.input>is the bare control, with no label and no errors. -
<.button variant="primary">becomes<.button>. A<.button>with no variant was the soft style, so make it<.button variant="soft">.<.button navigate={...}>becomes<.button link_type="live_redirect" to={...}>. -
Drop the daisyUI
btn,btn-primaryand otherbtn-*classes from a button’sclass. Keep layout classes likew-full. -
<.table>has no:actionslot. Move row actions into a last<:col :let={row} label="">. -
Tests that match exact input HTML (like
phx.gen.auth‘s login test) need rewriting withhas_element?/2.
mix compile --warnings-as-errors catches the variant, navigate and :action cases. It doesn’t catch a leftover <.input label=...> or btn-* classes, so run mix test too and search your templates for <.input and btn.
Next, route form errors through your app’s translator in config/config.exs:
config :petal_components, :error_translator_function, {YourAppWeb.CoreComponents, :translate_error}
Without it, petal_components falls back to plain substitution, and an error like phx.gen.auth‘s “has already been taken” renders as “invalid value”.
JS hooks
Toasts, the command palette, charts, the combobox, the data table, the chat family, the enhanced inputs and a few more use bundled JS hooks. Import them once in assets/js/app.js and merge them into your LiveSocket. Phoenix 1.8 already passes hooks: {...colocatedHooks}, so make it:
import PetalComponents from "../../deps/petal_components/assets/js/petal_components"
const liveSocket = new LiveSocket("/live", Socket, {
params: { _csrf_token: csrfToken },
hooks: { ...colocatedHooks, ...PetalComponents },
})
Using <.chart>? It drives Apache ECharts but doesn’t bundle it. Add <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script> to your root layout, or npm i echarts plus import * as echarts from "echarts"; window.echarts = echarts; in app.js. Skip it if you don’t render charts.
Verify
mix compile --warnings-as-errors
It should finish with no warnings. (Warnings about MDEx or EQRCode printed while compiling petal_components itself are optional dependencies and don’t fail the build.) Then check a LiveView renders the library’s markup: put <.button>Hello</.button> in one, and in its test assert has_element?(view, "button.pc-button"). Finally mix assets.build and confirm priv/static/assets/css/app.css contains .pc-button.
Using an agent? mix phx.new writes an AGENTS.md that tells it to use the CoreComponents <.icon> and <.input>. Update those lines to point at petal_components (<.field> for form fields). The rules file has the exact wording.
Additional setup
VSCode snippets
- VSCode extension — 65+ snippets covering every component
- Full snippet reference
Core Components conflicts (Phoenix 1.7+)
The Phoenix generator creates core_components.ex with some function components defined. In Phoenix 1.8 the ones that clash with petal_components are button, icon, input and table; apps from older Phoenix versions also have modal.
Fix: leave core_components.ex alone and keep those names out of its import with except:, as in Import the components above. Add any other name the compiler reports as ambiguous.
Pages from Phoenix generators like mix phx.gen.live need the call-site edits listed above. More on generators here. For generators that match petal_components out of the box, Petal Pro ships its own.
For a full upgrade commit of Phoenix 1.6 to 1.7, see how we did it in Petal Boilerplate.
If you want to pick and choose which components to use instead of use PetalComponents:
import PetalComponents.{
Alert,
Badge,
Button,
Container,
Dropdown,
Form,
Loading,
Typography,
Avatar,
Progress,
Breadcrumbs,
Pagination,
Link,
Modal,
SlideOver,
Tabs,
Card,
Table,
Accordion,
Icon
}
Namespacing
You can namespace all the components under any module you like. For example:
# in your_app_web.ex
defp html_helpers do
quote do
# HTML escaping functionality
import Phoenix.HTML
# Core UI components and translation
import YourAppWeb.CoreComponents
import YourAppWeb.Gettext
# Shortcut for generating JS commands
alias Phoenix.LiveView.JS
# Routes generation with the ~p sigil
unquote(verified_routes())
# Petal Components
defmodule PC do
defdelegate accordion(assigns), to: PetalComponents.Accordion
defdelegate alert(assigns), to: PetalComponents.Alert
defdelegate avatar(assigns), to: PetalComponents.Avatar
defdelegate badge(assigns), to: PetalComponents.Badge
defdelegate breadcrumbs(assigns), to: PetalComponents.Breadcrumbs
defdelegate button(assigns), to: PetalComponents.Button
defdelegate icon_button(assigns), to: PetalComponents.Button
defdelegate card(assigns), to: PetalComponents.Card
defdelegate container(assigns), to: PetalComponents.Container
defdelegate dropdown(assigns), to: PetalComponents.Dropdown
defdelegate form_label(assigns), to: PetalComponents.Form
defdelegate field(assigns), to: PetalComponents.Field
defdelegate icon(assigns), to: PetalComponents.Icon
defdelegate input(assigns), to: PetalComponents.Input
defdelegate a(assigns), to: PetalComponents.Link
defdelegate spinner(assigns), to: PetalComponents.Loading
defdelegate modal(assigns), to: PetalComponents.Modal
defdelegate pagination(assigns), to: PetalComponents.Pagination
defdelegate progress(assigns), to: PetalComponents.Progress
defdelegate rating(assigns), to: PetalComponents.Rating
defdelegate slide_over(assigns), to: PetalComponents.SlideOver
defdelegate table(assigns), to: PetalComponents.Table
defdelegate td(assigns), to: PetalComponents.Table
defdelegate tr(assigns), to: PetalComponents.Table
defdelegate th(assigns), to: PetalComponents.Table
defdelegate tabs(assigns), to: PetalComponents.Tabs
defdelegate h1(assigns), to: PetalComponents.Typography
defdelegate h2(assigns), to: PetalComponents.Typography
defdelegate h3(assigns), to: PetalComponents.Typography
defdelegate h4(assigns), to: PetalComponents.Typography
defdelegate h5(assigns), to: PetalComponents.Typography
defdelegate p(assigns), to: PetalComponents.Typography
defdelegate prose(assigns), to: PetalComponents.Typography
defdelegate ol(assigns), to: PetalComponents.Typography
defdelegate ul(assigns), to: PetalComponents.Typography
end
end
end
Then call components like so:
<.form for={@form} phx-submit="on_submit" phx-target={@myself}>
<PC.field field={@form[:title]} />
<PC.field field={@form[:description]} />
<PC.button label="Save" />
</.form>
Starting from a fresh project
If you’re starting a brand new Phoenix project, two options:
- The free Phoenix boilerplate ships with petal_components pre-installed.
- Petal Pro is the paid SaaS boilerplate built on petal_components — auth, multi-tenancy, Stripe billing, background jobs, the full set.
Or just install in your existing project with the two-step way above.