Petal Components: Shadcn-style HEEx components with an MCP server for AI coding tools

What Petal Components solves

Phoenix LiveView developers often end up writing the same Tailwind markup for buttons, modals, and tables in every project. Petal Components aims to remove that repetition with a set of HEEx components that follow the shadcn philosophy: composable primitives, you own the patterns, and no monolithic theme system. The project's pitch is that AI assistants can actually use these components, because a companion MCP server exposes the real schema. Instead of an AI generating raw Tailwind from training data, it reads the component definitions and calls them correctly. This targets teams that use Claude Code, Cursor, Codex, Windsurf, or similar tools in their Phoenix workflow.

The MCP server is the differentiator

The hosted MCP server at mcp.petal.build is what separates this library from a plain component collection. The README instructs you to add it once with `claude mcp add petal --transport http https://mcp.petal.build/mcp`. After that, you tell your AI to 'install petal_components', and the agent calls `get_install_instructions` on the MCP to apply the changes. The server also provides `list_components` and `get_component` as discovery methods. This is a real architectural choice: the component schema lives outside the codebase, so AI tools query the canonical inventory rather than relying on stale training data. It also means the library can add components without requiring users to update their local rules, as long as the MCP server is current.

Installation and setup

The recommended path is the MCP-driven install, but the manual route is straightforward. In `mix.exs`, add `{:petal_components, "~> 4.0"}` and optionally `{:mdex, "~> 0.12"}` for the chat markdown components. In `assets/css/app.css`, you need three lines: `@import "tailwindcss";`, `@source "../deps/petal_components/**/*.*ex";`, and `@import "../deps/petal_components/assets/default.css";`. This tells Tailwind v4 to scan the component source and pulls in the default styles. In your `MyAppWeb` module, add `use PetalComponents` inside the `html` quote block. Finally, register the bundled JS hooks in `assets/js/app.js` by importing `PetalComponents` from the deps path and merging it into the LiveSocket hooks. The README notes that only the password, copyable, clearable inputs, and chat components need these hooks; the rest is CSS and LiveView.JS only.

Component catalogue and usage patterns

The library ships 30+ components across layout, forms, actions, feedback, and data display. Examples in the README show a form inside a card, a modal with a form, a table with row actions, and a loading button. The table pattern uses `:col` slots with `:let` bindings, which is idiomatic HEEx. The form-in-card example composes `<.card>`, `<.card_content>`, `<.form>`, and `<.field>` in a way that mirrors common Phoenix patterns. The loading button is a single attribute: `<.button loading={@saving} phx-click="save">Save</.button>`. The component naming map is documented in `rules.md`, which also defines the HEEx tag form, module path, and CSS class prefix for each component. The MCP server remains the canonical list, so the README encourages calling `list_components` for a live inventory rather than trusting the static catalogue.

Where it fits and where it doesn't

This library is a good fit if you already use Tailwind v4 and want a component set that follows Phoenix conventions. It works in both live and dead views, which is a plus for pages that don't need LiveView. However, it is not a copy-paste-into-your-repo system like shadcn. You depend on a Hex package, so you get updates via `mix deps.update`, but you don't own the source in your repository. If you need to heavily customize a component's internals, you may find the package boundary limiting. The MCP server is hosted, which introduces a network dependency for AI tooling. If you work offline or have strict data policies, you might need to run your own server, but the README doesn't document a self-hosted option.

Comparison with shadcn and alternatives

The project explicitly compares itself to shadcn. Both share the philosophy of composable primitives and AI-tool integration, but the runtime differs: HEEx instead of JSX, Tailwind v4 instead of Tailwind 3 with CSS variables. Distribution also differs: a Hex package versus a CLI that copies files into your repo. That means with shadcn you can edit the copied source directly, while with Petal Components you edit through the package's API or by overriding styles. A real alternative is to use Phoenix's built-in form helpers and write your own Tailwind classes, which gives you full control but sacrifices consistency and AI assistance. Another alternative is to use a different Phoenix component library like Surface or Flutter-like libraries, but the README doesn't mention them, so a direct comparison is not possible from this material.

Maintenance and licensing

The project is MIT-licensed, which means you can use it in commercial projects without paying for a license. The repository is active, with the latest release v3.2.2 pushed on 2026-05-15, and the default branch is main. The README mentions a roadmap for contributions, but the truncated section doesn't detail it. The package is on Hex, so updates are straightforward with `mix deps.update petal_components`. The main maintenance cost is keeping your Tailwind v4 setup aligned with the library's CSS imports, especially if you have custom theme changes. The MCP server is hosted by the project, so you rely on their uptime for AI tooling, but the components themselves work without it once installed.

Editorial conclusion

Adopt Petal Components if you build Phoenix LiveView apps and want a consistent, accessible component set that AI assistants can call correctly via the MCP server. Skip it if you need a CLI that copies source into your repo (like shadcn) or if you prefer hand-rolling Tailwind. Before adopting, verify the MCP server's latency and privacy, confirm the component coverage matches your needs, and check the Tailwind v4 setup in your existing CSS pipeline.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes