{"id":13497498,"url":"https://github.com/petalframework/petal_components","last_synced_at":"2026-05-16T01:02:45.220Z","repository":{"id":37587426,"uuid":"416902200","full_name":"petalframework/petal_components","owner":"petalframework","description":"Phoenix + Live View HEEX Components ","archived":false,"fork":false,"pushed_at":"2025-04-22T04:44:18.000Z","size":1760,"stargazers_count":974,"open_issues_count":26,"forks_count":103,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-22T06:33:04.174Z","etag":null,"topics":["components","phoenix","tailwindcss"],"latest_commit_sha":null,"homepage":"https://petal.build/components","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petalframework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-13T21:24:58.000Z","updated_at":"2025-04-22T04:44:22.000Z","dependencies_parsed_at":"2023-10-20T22:18:57.322Z","dependency_job_id":"c1450a0d-1e94-47e3-b930-9b692919d2e6","html_url":"https://github.com/petalframework/petal_components","commit_stats":{"total_commits":641,"total_committers":46,"mean_commits":"13.934782608695652","dds":0.5132605304212168,"last_synced_commit":"4a6ad7f206fac047743ab26c0d210fc199436c5c"},"previous_names":[],"tags_count":139,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalframework%2Fpetal_components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalframework%2Fpetal_components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalframework%2Fpetal_components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalframework%2Fpetal_components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petalframework","download_url":"https://codeload.github.com/petalframework/petal_components/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251297558,"owners_count":21566841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["components","phoenix","tailwindcss"],"created_at":"2024-07-31T20:00:32.061Z","updated_at":"2026-05-16T01:02:45.208Z","avatar_url":"https://github.com/petalframework.png","language":"Elixir","funding_links":[],"categories":["Usage","Elixir","Frameworks"],"sub_categories":["Credits"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/wickedsites/image/upload/v1635752721/petal/logo_rh2ras.png\" height=\"96\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePetal Components\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eShadcn-style Phoenix components that AI assistants can actually use.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hex.pm/packages/petal_components\"\u003e\u003cimg alt=\"Hex Version\" src=\"https://img.shields.io/hexpm/v/petal_components.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hexdocs.pm/petal_components\"\u003e\u003cimg alt=\"Hex Docs\" src=\"https://img.shields.io/hexpm/dt/petal_components.svg?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg alt=\"MIT\" src=\"https://img.shields.io/badge/license-MIT-green\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://petal.build/components\"\u003eLive docs\u003c/a\u003e ·\n  \u003ca href=\"https://mcp.petal.build\"\u003eMCP server\u003c/a\u003e ·\n  \u003ca href=\"./rules.md\"\u003eRules for AI tools\u003c/a\u003e ·\n  \u003ca href=\"https://petal.build/petal-components/vs-shadcn\"\u003evs shadcn\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The 30-second pitch\n\nPetal 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.\n\nThe 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.\n\nIf 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.\n\n## Install\n\n### Phoenix app\n\nAdd to your `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:petal_components, \"~\u003e 3.2\"}\n  ]\nend\n```\n\nThen in `assets/css/app.css`:\n\n```css\n@import \"tailwindcss\";\n@source \"../deps/petal_components/**/*.*ex\";\n@import \"../deps/petal_components/assets/default.css\";\n```\n\nIn your `MyAppWeb` module:\n\n```elixir\ndef html do\n  quote do\n    use PetalComponents\n    # ... your other imports\n  end\nend\n```\n\n### AI coding tools (MCP server)\n\n```sh\n# Claude Code\nclaude mcp add petal --transport http https://mcp.petal.build/mcp\n```\n\nCursor, Windsurf, Continue, Codex, and Cline have their own MCP install steps - see https://petal.build/petal-components for setup snippets per tool.\n\nOnce installed, the agent can call `list_components` and `get_component` to ground its output in the real petal_components schema. No more `\u003cdiv class=\"rounded-lg shadow ...\"\u003e` fallbacks for things we already ship.\n\n## For AI coding tools\n\nIf 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:\n\n- Always reach for an existing petal_components tag before hand-rolling HEEx\n- The component naming map (HEEx tag form, module path, CSS class prefix)\n- How to discover components via the MCP\n- Common patterns (form-in-card, modal-with-form, table-with-actions)\n- When in doubt: call `list_components`, then `get_component`\n\nYou can also fetch it at https://petal.build/petal-components/rules.md.\n\n## Component catalogue\n\n30+ 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:\n\n**Layout \u0026 content**: `\u003c.container\u003e`, `\u003c.card\u003e`, `\u003c.h1\u003e`, `\u003c.p\u003e`, `\u003c.accordion\u003e`, `\u003c.tabs\u003e`, `\u003c.stepper\u003e`, `\u003c.skeleton\u003e`\n\n**Forms**: `\u003c.field\u003e`, `\u003c.text_input\u003e`, `\u003c.select\u003e`, `\u003c.checkbox\u003e`, `\u003c.radio_group\u003e`, `\u003c.switch\u003e`, `\u003c.textarea\u003e`, `\u003c.date_input\u003e`, `\u003c.file_input\u003e` (full list in `lib/petal_components/form.ex`)\n\n**Actions**: `\u003c.button\u003e`, `\u003c.button_group\u003e`, `\u003c.dropdown\u003e`, `\u003c.menu\u003e`, `\u003c.user_dropdown_menu\u003e`\n\n**Feedback**: `\u003c.alert\u003e`, `\u003c.modal\u003e`, `\u003c.slide_over\u003e`, `\u003c.progress\u003e`, `\u003c.spinner\u003e`, `\u003c.rating\u003e`\n\n**Data display**: `\u003c.table\u003e`, `\u003c.pagination\u003e`, `\u003c.breadcrumbs\u003e`, `\u003c.badge\u003e`, `\u003c.avatar\u003e`, `\u003c.marquee\u003e`, `\u003c.icon\u003e`, `\u003c.link\u003e`\n\nA visual grid is at https://petal.build/components. A live playground is at https://petal-components-demo.fly.dev.\n\n## Examples\n\n### Form in a card\n\n```heex\n\u003c.card\u003e\n  \u003c.card_content\u003e\n    \u003c.form for={@form} phx-submit=\"save\"\u003e\n      \u003c.field field={@form[:name]} label=\"Name\" /\u003e\n      \u003c.field field={@form[:email]} type=\"email\" label=\"Email\" /\u003e\n      \u003c.button type=\"submit\"\u003eSave\u003c/.button\u003e\n    \u003c/.form\u003e\n  \u003c/.card_content\u003e\n\u003c/.card\u003e\n```\n\n### Modal with a form\n\n```heex\n\u003c.modal title=\"Edit user\" max_width=\"md\"\u003e\n  \u003c.form for={@form} phx-submit=\"save\"\u003e\n    \u003c.field field={@form[:name]} label=\"Name\" /\u003e\n    \u003c.button type=\"submit\"\u003eSave\u003c/.button\u003e\n  \u003c/.form\u003e\n\u003c/.modal\u003e\n```\n\n### Table with row actions\n\n```heex\n\u003c.table rows={@users}\u003e\n  \u003c:col :let={user} label=\"Name\"\u003e{user.name}\u003c/:col\u003e\n  \u003c:col :let={user} label=\"Email\"\u003e{user.email}\u003c/:col\u003e\n  \u003c:col :let={user} label=\"\"\u003e\n    \u003c.button size=\"xs\" variant=\"outline\" phx-click=\"edit\" phx-value-id={user.id}\u003e\n      Edit\n    \u003c/.button\u003e\n  \u003c/:col\u003e\n\u003c/.table\u003e\n```\n\n### Loading button\n\n```heex\n\u003c.button loading={@saving} phx-click=\"save\"\u003eSave\u003c/.button\u003e\n```\n\n## Compared to shadcn\n\nIf you like the shadcn workflow in React, this is the Phoenix version of that idea:\n\n- **Same philosophy**: composable primitives, you own the patterns, no monolithic theme system to fight.\n- **Same AI-tool integration**: an MCP server so the agent reads the real schema instead of hallucinating attrs.\n- **Different runtime**: HEEx, not JSX. Tailwind v4, not Tailwind 3 + CSS variables. Works in LiveView and dead views.\n- **Different distribution**: a Hex package, not a CLI that copies files into your repo. Update with `mix deps.update`.\n\nFull comparison with code samples side by side: https://petal.build/petal-components/vs-shadcn.\n\n## petal_pro\n\n[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.\n\n## Local development\n\nStandalone dev server, no umbrella needed:\n\n```sh\ngit clone https://github.com/petalframework/petal_components.git\ncd petal_components\nmix deps.get\nmix tailwind.install\niex -S mix run dev.exs\n```\n\nPlayground at http://localhost:4000 with every component rendered. Live reload on edits to `lib/`.\n\nTests:\n\n```sh\nmix test\n```\n\n## Contributing\n\nSuggest a component on the [public roadmap](https://petal.build/components/roadmap). PRs welcome - clone the repo, run the dev server above, and submit.\n\nThere 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.\n\n## Companion projects\n\n- [petal-components-mcp](https://github.com/petalframework/petal-components-mcp) - the MCP server. Source for the schema introspector and the TypeScript MCP service.\n- [petal_boilerplate](https://github.com/petalframework/petal_boilerplate) - a fresh Phoenix install with petal_components wired up.\n- [Figma UI kit](https://www.figma.com/community/file/1374192831096114078/official-petal-ui-kit) - official Figma kit for designing against petal_components.\n- [VSCode snippets](https://marketplace.visualstudio.com/items?itemName=petalframework.vscode-petal-components-snippets) - 65+ snippets for the components.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetalframework%2Fpetal_components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetalframework%2Fpetal_components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetalframework%2Fpetal_components/lists"}