https://github.com/petalframework/petal_components
Phoenix + Live View HEEX Components
https://github.com/petalframework/petal_components
components phoenix tailwindcss
Last synced: 27 days ago
JSON representation
Phoenix + Live View HEEX Components
- Host: GitHub
- URL: https://github.com/petalframework/petal_components
- Owner: petalframework
- License: mit
- Created: 2021-10-13T21:24:58.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-22T04:44:18.000Z (about 1 year ago)
- Last Synced: 2025-04-22T06:33:04.174Z (about 1 year ago)
- Topics: components, phoenix, tailwindcss
- Language: Elixir
- Homepage: https://petal.build/components
- Size: 1.68 MB
- Stars: 974
- Watchers: 18
- Forks: 103
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-elixir - Petal Components - A set of HEEX components that makes it easy for Phoenix developers to build beautiful web apps. (Frameworks)
- fucking-awesome-elixir - Petal Components - A set of HEEX components that makes it easy for Phoenix developers to build beautiful web apps. (Frameworks)
README
Petal Components
Shadcn-style Phoenix components that AI assistants can actually use.
Live docs ·
MCP server ·
Rules for AI tools ·
vs shadcn
---
## The 30-second pitch
Petal Components gives Phoenix LiveView apps a shadcn-style set of HEEx components: buttons, forms, modals, tables, cards, and more. They are built with Tailwind v4 and work in live or dead views.
The companion piece is a hosted MCP server at `mcp.petal.build` that exposes every component's real schema to AI coding tools. Install it once and Claude Code, Cursor, Codex, and Windsurf reach for the existing components instead of inventing raw Tailwind markup from training data.
If you have used shadcn in React, you already know the shape. Same idea, composable primitives, you own the patterns, AI tools read the schema and call it correctly. We just write HEEx, not JSX.
## Install
### Phoenix app
Add to your `mix.exs`:
```elixir
def deps do
[
{:petal_components, "~> 3.2"}
]
end
```
Then in `assets/css/app.css`:
```css
@import "tailwindcss";
@source "../deps/petal_components/**/*.*ex";
@import "../deps/petal_components/assets/default.css";
```
In your `MyAppWeb` module:
```elixir
def html do
quote do
use PetalComponents
# ... your other imports
end
end
```
### AI coding tools (MCP server)
```sh
# Claude Code
claude mcp add petal --transport http https://mcp.petal.build/mcp
```
Cursor, Windsurf, Continue, Codex, and Cline have their own MCP install steps - see https://petal.build/petal-components for setup snippets per tool.
Once installed, the agent can call `list_components` and `get_component` to ground its output in the real petal_components schema. No more `
` fallbacks for things we already ship.
## For AI coding tools
If you are a Cursor, Claude Code, Codex, Continue, Windsurf, or Cline user (or you maintain one of those tools), drop [`rules.md`](./rules.md) into your rules system. It is the canonical instruction set:
- Always reach for an existing petal_components tag before hand-rolling HEEx
- The component naming map (HEEx tag form, module path, CSS class prefix)
- How to discover components via the MCP
- Common patterns (form-in-card, modal-with-form, table-with-actions)
- When in doubt: call `list_components`, then `get_component`
You can also fetch it at https://petal.build/petal-components/rules.md.
## Component catalogue
30+ components covering the patterns a real Phoenix app needs. The MCP server is always the canonical list - call `list_components` for the live inventory. Highlights:
**Layout & content**: `<.container>`, `<.card>`, `<.h1>`, `<.p>`, `<.accordion>`, `<.tabs>`, `<.stepper>`, `<.skeleton>`
**Forms**: `<.field>`, `<.text_input>`, `<.select>`, `<.checkbox>`, `<.radio_group>`, `<.switch>`, `<.textarea>`, `<.date_input>`, `<.file_input>` (full list in `lib/petal_components/form.ex`)
**Actions**: `<.button>`, `<.button_group>`, `<.dropdown>`, `<.menu>`, `<.user_dropdown_menu>`
**Feedback**: `<.alert>`, `<.modal>`, `<.slide_over>`, `<.progress>`, `<.spinner>`, `<.rating>`
**Data display**: `<.table>`, `<.pagination>`, `<.breadcrumbs>`, `<.badge>`, `<.avatar>`, `<.marquee>`, `<.icon>`, `<.link>`
A visual grid is at https://petal.build/components. A live playground is at https://petal-components-demo.fly.dev.
## Examples
### Form in a card
```heex
<.card>
<.card_content>
<.form for={@form} phx-submit="save">
<.field field={@form[:name]} label="Name" />
<.field field={@form[:email]} type="email" label="Email" />
<.button type="submit">Save
```
### Modal with a form
```heex
<.modal title="Edit user" max_width="md">
<.form for={@form} phx-submit="save">
<.field field={@form[:name]} label="Name" />
<.button type="submit">Save
```
### Table with row actions
```heex
<.table rows={@users}>
<:col :let={user} label="Name">{user.name}
<:col :let={user} label="Email">{user.email}
<:col :let={user} label="">
<.button size="xs" variant="outline" phx-click="edit" phx-value-id={user.id}>
Edit
```
### Loading button
```heex
<.button loading={@saving} phx-click="save">Save
```
## Compared to shadcn
If you like the shadcn workflow in React, this is the Phoenix version of that idea:
- **Same philosophy**: composable primitives, you own the patterns, no monolithic theme system to fight.
- **Same AI-tool integration**: an MCP server so the agent reads the real schema instead of hallucinating attrs.
- **Different runtime**: HEEx, not JSX. Tailwind v4, not Tailwind 3 + CSS variables. Works in LiveView and dead views.
- **Different distribution**: a Hex package, not a CLI that copies files into your repo. Update with `mix deps.update`.
Full comparison with code samples side by side: https://petal.build/petal-components/vs-shadcn.
## petal_pro
[petal_pro](https://petal.build/petal-pro) is the production SaaS boilerplate built on petal_components - auth, multi-tenancy, Stripe billing, background jobs, the full set. It is the best reference for real-world composition of these components.
## Local development
Standalone dev server, no umbrella needed:
```sh
git clone https://github.com/petalframework/petal_components.git
cd petal_components
mix deps.get
mix tailwind.install
iex -S mix run dev.exs
```
Playground at http://localhost:4000 with every component rendered. Live reload on edits to `lib/`.
Tests:
```sh
mix test
```
## Contributing
Suggest a component on the [public roadmap](https://petal.build/components/roadmap). PRs welcome - clone the repo, run the dev server above, and submit.
There is also a [Phoenix umbrella app](https://github.com/petalframework/petal_development) with `petal_components` as a submodule alongside a boilerplate Phoenix app for integrated testing.
## Companion projects
- [petal-components-mcp](https://github.com/petalframework/petal-components-mcp) - the MCP server. Source for the schema introspector and the TypeScript MCP service.
- [petal_boilerplate](https://github.com/petalframework/petal_boilerplate) - a fresh Phoenix install with petal_components wired up.
- [Figma UI kit](https://www.figma.com/community/file/1374192831096114078/official-petal-ui-kit) - official Figma kit for designing against petal_components.
- [VSCode snippets](https://marketplace.visualstudio.com/items?itemName=petalframework.vscode-petal-components-snippets) - 65+ snippets for the components.
## License
MIT.