Skip to content
Back to search

petal_components

Phoenix + Live View HEEX Components

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/petalframework/petal_components with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/petalframework/petal_components'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/petalframework--petal-components/badge.svg)](/listings/petalframework--petal-components)

HTML

<a href="/listings/petalframework--petal-components"><img src="/api/listings/petalframework--petal-components/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The two-step way (recommended)

# 1. Install the MCP server once
claude mcp add petal --transport http https://mcp.petal.build/mcp

Then in any Phoenix project:

2. Tell your AI: "install petal_components"

The agent calls `get_install_instructions` on the MCP, applies the changes to your `mix.exs`, runs `mix deps.get`, patches `assets/css/app.css`, and adds `use PetalComponents` to your web module. Works in umbrella apps and standard Phoenix projects. The AI handles project shape variance the install would otherwise have to special-case.

Cursor, Windsurf, Continue, Codex, and Cline have their own MCP install commands - see https://petal.build/petal-components for snippets per tool.

The manual way

If you'd rather install yourself, in `mix.exs`:

def deps do
  [
    {:petal_components, "~> 4.0"},
    # optional — only needed for the chat markdown components (<Chat.markdown>, <Chat.rich_text>)
    {:mdex, "~> 0.12"}
  ]
end

In `assets/css/app.css`:

@import "tailwindcss";
@source "../deps/petal_components/**/*.*ex";
@import "../deps/petal_components/assets/default.css";

In your `MyAppWeb` module:

def html do
  quote do
    use PetalComponents
    # ... your other imports
  end
end

Register the bundled JS hooks in `assets/js/app.js` (needed for the password/copyable/clearable inputs and the chat components — the rest of the library is CSS + LiveView.JS only):

import PetalComponents from "../../deps/petal_components/assets/js/petal_components"

const liveSocket = new LiveSocket("/live", Socket, {
  params: { _csrf_token: csrfToken },
  hooks: { ...PetalComponents }, // merge with your own hooks if you have any
})

Run `mix deps.get`, then `mix compile` to verify.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://code.claude.com/schemas/marketplace-v1.json",
  3. "name": "petal",
  4. "version": "0.1.0",
  5. "owner": {
  6. "name": "Petal Framework",
  7. "url": "https://petal.build"
  8. },
  9. "description": "Petal Components skills for AI coding agents",
  10. "plugins": [
  11. {
  12. "name": "petal-design",
  13. "displayName": "Petal Design",
  14. "description": "Design doctrine for Phoenix apps using petal_components - build, review, and theme UI that stays on the design system. Pairs with the Petal MCP (mcp.petal.build).",
  15. "source": "./",
  16. "author": { "name": "Petal Framework" },
  17. "keywords": ["phoenix", "liveview", "design-system", "petal", "tailwind", "heex"]
  18. }
  19. ]
  20. }
README.md · README · 256 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://res.cloudinary.com/wickedsites/image/upload/v1635752721/petal/logo_rh2ras.png" height="96">
  3. </p>
  4. <h1 align="center">Petal Components</h1>
  5. <p align="center">
  6. <strong>Shadcn-style Phoenix components that AI assistants can actually use.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://hex.pm/packages/petal_components"><img alt="Hex Version" src="https://img.shields.io/hexpm/v/petal_components.svg"></a>
  10. <a href="https://hexdocs.pm/petal_components"><img alt="Hex Docs" src="https://img.shields.io/hexpm/dt/petal_components.svg?style=flat"></a>
  11. <a href="https://opensource.org/licenses/MIT"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
  12. </p>
  13. <p align="center">
  14. <a href="https://petal.build/components">Live docs</a> ·
  15. <a href="https://mcp.petal.build">MCP server</a> ·
  16. <a href="./usage-rules.md">Rules for AI tools</a> ·
  17. <a href="https://petal.build/petal-components/vs-shadcn">vs shadcn</a>
  18. </p>
  19. ---
  20. ## The 30-second pitch
  21. 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.
  22. 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.
  23. 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.
  24. ## Install
  25. ### The two-step way (recommended)
  26. ```sh
  27. # 1. Install the MCP server once
  28. claude mcp add petal --transport http https://mcp.petal.build/mcp
  29. ```
  30. Then in any Phoenix project:
  31. ```
  32. 2. Tell your AI: "install petal_components"
  33. ```
  34. The agent calls `get_install_instructions` on the MCP, applies the changes to your `mix.exs`, runs `mix deps.get`, patches `assets/css/app.css`, and adds `use PetalComponents` to your web module. Works in umbrella apps and standard Phoenix projects. The AI handles project shape variance the install would otherwise have to special-case.
  35. Cursor, Windsurf, Continue, Codex, and Cline have their own MCP install commands - see https://petal.build/petal-components for snippets per tool.
  36. ### The manual way
  37. If you'd rather install yourself, in `mix.exs`:
  38. ```elixir
  39. def deps do
  40. [
  41. {:petal_components, "~> 4.0"},
  42. # optional — only needed for the chat markdown components (<Chat.markdown>, <Chat.rich_text>)
  43. {:mdex, "~> 0.12"}
  44. ]
  45. end
  46. ```
  47. In `assets/css/app.css`:
  48. ```css
  49. @import "tailwindcss";
  50. @source "../../deps/petal_components/**/*.*ex";
  51. @source not "../../deps/petal_components/lib/petal_components/showcase";
  52. @import "../../deps/petal_components/assets/default.css";
  53. @plugin "@tailwindcss/forms";
  54. ```
  55. In your `MyAppWeb` module:
  56. ```elixir
  57. def html do
  58. quote do
  59. use PetalComponents
  60. # ... your other imports
  61. end
  62. end
  63. ```
  64. Register the bundled JS hooks in `assets/js/app.js` (needed for the password/copyable/clearable inputs and the chat components — the rest of the library is CSS + LiveView.JS only):
  65. ```js
  66. import PetalComponents from "../../deps/petal_components/assets/js/petal_components"
  67. const liveSocket = new LiveSocket("/live", Socket, {
  68. params: { _csrf_token: csrfToken },
  69. hooks: { ...PetalComponents }, // merge with your own hooks if you have any
  70. })
  71. ```
  72. Run `mix deps.get`, then `mix compile` to verify.
  73. ## For AI coding tools
  74. If you are a Cursor, Claude Code, Codex, Continue, Windsurf, or Cline user (or you maintain one of those tools), drop [`usage-rules.md`](./usage-rules.md) into your rules system. It is the canonical instruction set:
  75. - Always reach for an existing petal_components tag before hand-rolling HEEx
  76. - The component naming map (HEEx tag form, module path, CSS class prefix)
  77. - How to discover components via the MCP
  78. - Common patterns (form-in-card, modal-with-form, table-with-actions)
  79. - When in doubt: call `list_components`, then `get_component`
  80. You can also fetch it at https://petal.build/petal-components/rules.md.
  81. The file ships in the Hex package under the name the [usage_rules](https://hexdocs.pm/usage_rules) package looks for, so you can have it synced into your `CLAUDE.md` (or `AGENTS.md`) instead of copying it by hand. Add `{:usage_rules, "~> 1.1", only: [:dev]}` to your deps, then in `mix.exs`:
  82. ```elixir
  83. def project do
  84. [
  85. # ...
  86. usage_rules: [file: "CLAUDE.md", usage_rules: [:petal_components]]
  87. ]
  88. end
  89. ```
  90. and run:
  91. ```sh
  92. mix usage_rules.sync
  93. ```
  94. Re-run it after upgrading petal_components and the block in your file updates in place.
  95. The design rules those tools follow (the `petal-design` skill in `skills/petal-design/`) are also written up for people: the [design system guide](guides/design.md) covers the token layer, the gray dial, dark mode, radius and type, the composition patterns, and a review checklist you can apply by hand.
  96. ## Component catalogue
  97. 200+ 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:
  98. **Layout & content**: `<.container>`, `<.card>`, `<.h1>`, `<.p>`, `<.accordion>`, `<.tabs>`, `<.stepper>`, `<.skeleton>`
  99. **Forms**: `<.field>`, `<.text_input>`, `<.select>`, `<.checkbox>`, `<.radio_group>`, `<.switch>`, `<.textarea>`, `<.date_input>`, `<.file_input>` (full list in `lib/petal_components/form.ex`)
  100. **Actions**: `<.button>`, `<.button_group>`, `<.dropdown>`, `<.menu>`, `<.user_dropdown_menu>`
  101. **Feedback**: `<.alert>`, `<.modal>`, `<.slide_over>`, `<.popover>`, `<.tooltip>`, `<.progress>`, `<.spinner>`, `<.rating>`
  102. **Data display**: `<.table>`, `<.pagination>`, `<.breadcrumbs>`, `<.badge>`, `<.avatar>`, `<.marquee>`, `<.icon>`, `<.link>`
  103. A visual grid is at https://petal.build/components. The live playground is at https://playground.petal.build.
  104. ## Examples
  105. ### Form in a card
  106. ```heex
  107. <.card>
  108. <.card_content>
  109. <.form for={@form} phx-submit="save">
  110. <.field field={@form[:name]} label="Name" />
  111. <.field field={@form[:email]} type="email" label="Email" />
  112. <.button type="submit">Save</.button>
  113. </.form>
  114. </.card_content>
  115. </.card>
  116. ```
  117. ### Modal with a form
  118. ```heex
  119. <.modal title="Edit user" max_width="md">
  120. <.form for={@form} phx-submit="save">
  121. <.field field={@form[:name]} label="Name" />
  122. <.button type="submit">Save</.button>
  123. </.form>
  124. </.modal>
  125. ```
  126. ### Table with row actions
  127. ```heex
  128. <.table rows={@users}>
  129. <:col :let={user} label="Name">{user.name}</:col>
  130. <:col :let={user} label="Email">{user.email}</:col>
  131. <:col :let={user} label="">
  132. <.button size="xs" variant="outline" phx-click="edit" phx-value-id={user.id}>
  133. Edit
  134. </.button>
  135. </:col>
  136. </.table>
  137. ```
  138. ### Loading button
  139. ```heex
  140. <.button loading={@saving} phx-click="save">Save</.button>
  141. ```
  142. ## Compared to shadcn
  143. If you like the shadcn workflow in React, this is the Phoenix version of that idea:
  144. - **Same philosophy**: composable primitives, you own the patterns, no monolithic theme system to fight.
  145. - **Same AI-tool integration**: an MCP server so the agent reads the real schema instead of hallucinating attrs.
  146. - **Different runtime**: HEEx, not JSX. Tailwind v4, not Tailwind 3 + CSS variables. Works in LiveView and dead views.
  147. - **Different distribution**: a Hex package, not a CLI that copies files into your repo. Update with `mix deps.update`.
  148. Full comparison with code samples side by side: https://petal.build/petal-components/vs-shadcn.
  149. ## petal_pro
  150. [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.
  151. ## Local development
  152. Standalone dev server, no umbrella needed:
  153. ```sh
  154. git clone https://github.com/petalframework/petal_components.git
  155. cd petal_components
  156. mix deps.get
  157. mix tailwind.install
  158. iex -S mix run dev.exs
  159. ```
  160. Playground at http://localhost:4000 with every component rendered. Live reload on edits to `lib/`.
  161. Tests:
  162. ```sh
  163. mix test
  164. ```
  165. ## Contributing
  166. The component roadmap lives in the [milestones](https://github.com/petalframework/petal_components/milestones): each issue is a complete build brief (API sketch, variants, playground page spec, accessibility requirements, test checklist). See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the playground workflow, and the review process. Suggestions also welcome on the [public roadmap](https://petal.build/components/roadmap).
  167. ## Companion projects
  168. - [petal-components-mcp](https://github.com/petalframework/petal-components-mcp) - the MCP server. Source for the schema introspector and the TypeScript MCP service.
  169. - [petal_boilerplate](https://github.com/petalframework/petal_boilerplate) - a fresh Phoenix install with petal_components wired up.
  170. - [Figma UI kit](https://www.figma.com/community/file/1374192831096114078/official-petal-ui-kit) - official Figma kit for designing against petal_components.
  171. - [VSCode snippets](https://marketplace.visualstudio.com/items?itemName=petalframework.vscode-petal-components-snippets) - 65+ snippets for the components.
  172. ## Acknowledgements
  173. Petal Components stands on other people's work:
  174. - [phoenix_playground](https://github.com/phoenix-playground/phoenix_playground) by [Wojtek Mach](https://github.com/wojtekmach) - boots the dev server and [playground.petal.build](https://playground.petal.build) from a single script.
  175. - [Phoenix](https://www.phoenixframework.org/) and [LiveView](https://github.com/phoenixframework/phoenix_live_view) - the platform everything here renders on.
  176. - [Tailwind CSS](https://tailwindcss.com/) - every component is styled with Tailwind v4.
  177. - [Apache ECharts](https://echarts.apache.org/) - the engine under `<.chart>`.
  178. - [Heroicons](https://heroicons.com/) - the icon set under `<.icon>`.
  179. - [border-beam](https://github.com/Jakubantalik/border-beam) by [Jakub Antalik](https://github.com/Jakubantalik) (MIT) - `<.border_plasma>`'s pulse effect ports its gradient geometry, oscillator tuning and layer treatment.
  180. ## License
  181. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.