Welcome to Petal 👋
A versatile set of beautifully styled components for you to use in your next Phoenix project.
Installation
- New projects
- How to install Tailwind
- How to install Petal Components
- How to install Alpine JS
- How to install VSCode snippets
New projects
You can use our free Phoenix basic boilerplate that has the components pre-installed.
Or you can use our paid boilerplate (Petal Pro), which provides additional functionality like authentication, email components, layouts and more.
How to install Tailwind
Firstly, follow this guide to install Tailwind: Tailwind installation guide for Phoenix.
How to install Petal Components
Add dependency
defp deps do
[
{:petal_components, "~> 1.0.0"},
]
end
Modify the tailwind.config.js
You will need to open your tailwind.config.js
and make two changes:
-
include the Petal Components folder in the
content
array -
extend the color palette in the
theme.extend.colors
object
const colors = require("tailwindcss/colors");
const plugin = require("tailwindcss/plugin");
module.exports = {
content: [
"../lib/*_web.ex",
"../lib/*_web/**/*.*ex",
"./js/**/*.js",
"../deps/petal_components/**/*.*ex", // <-- ADD THIS LINE
],
darkMode: "class",
theme: {
extend: {
// ADD THESE COLORS (can pick different ones from here: https://tailwindcss.com/docs/customizing-colors)
colors: {
primary: colors.blue,
secondary: colors.pink,
success: colors.green,
danger: colors.red,
warning: colors.yellow,
info: colors.sky,
// Options: slate, gray, zinc, neutral, stone
gray: colors.gray,
},
},
},
plugins: [
require("@tailwindcss/forms"),
plugin(({ addVariant }) =>
addVariant("phx-no-feedback", [".phx-no-feedback&", ".phx-no-feedback &"])
),
plugin(({ addVariant }) =>
addVariant("phx-click-loading", [
".phx-click-loading&",
".phx-click-loading &",
])
),
plugin(({ addVariant }) =>
addVariant("phx-submit-loading", [
".phx-submit-loading&",
".phx-submit-loading &",
])
),
plugin(({ addVariant }) =>
addVariant("phx-change-loading", [
".phx-change-loading&",
".phx-change-loading &",
])
),
],
};
Include the CSS
@import "tailwindcss/base";
@import "../../deps/petal_components/assets/default.css";
@import "tailwindcss/components";
@import "tailwindcss/utilities";
Import the components
This allows them to be called anywhere in your views.
defmodule YourAppWeb
...
defp view_helpers do
quote do
...
use PetalComponents
end
end
Phoenix 1.6 and below
You may have a modal/1
function defined already, which will cause a clash with PetalComponents.Modal.modal/1
. Check in live_helpers.ex
and remove it.
Phoenix 1.7 and above
Petal Components work fine with Phoenix 1.7 - there just will be some naming conflicts as the Phoenix generator now creates a file called core_components.ex
, which has some function components defined in there.
To fix, go to the generated core_components.ex
file and rename or remove the following functions: modal
, button
and table
.
Unfortunately, this means the generators like mix phx.gen.live
won’t work properly. If you want generators for Petal Components, look into buying Petal Pro.
For a full upgrade commit of Phoenix 1.6 to 1.7 you can see here how we did it with Petal Boilerplate.
If you want to pick and choose which components to use, you could import only the ones you want:
# Instead of `use PetalComponents`, you could do this and delete any you don't want:
import PetalComponents.{
Alert,
Badge,
Button,
Container,
Dropdown,
Form,
Loading,
Typography,
Avatar,
Progress,
Breadcrumbs,
Pagination,
Link,
Modal,
SlideOver,
Tabs,
Card,
Table,
Accordion,
Icon
}
Optionally set a translator for form errors
If you want to translate your form errors to anything other than English you will need to provide Petal Components with your translater function.
config :petal_components, :error_translator_function, {<YourApp>Web.ErrorHelpers, :translate_error}
How to install Alpine JS
Alpine JS is the default JS library for a couple of components like Dropdown and Accordion. Though you can opt out and us Liveview.JS (only works in live views) - see the js_lib
attribute on the components.
Add to your root.html.heex file:
<head>
<!-- For accordion -->
<script defer src="https://unpkg.com/@alpinejs/collapse@3.x.x/dist/cdn.min.js">
</script>
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js">
</script>
</head>