Viewing latest docs.
Switch version: v3

Components

The majority of components come from our open-source package “Petal Components“. However, there are some only in Petal Pro. Ultimately, petal.build will house all docs related to components, and these guides will more tailored to Petal Pro core functionality.

Layouts

Docs are on petal.build.

Brand

See the Branding section.

Color scheme switch

<.color_scheme_switch id="theme-switch" />

The switch to flip between light and dark mode. It comes from Petal Components now (Pro’s own copy was retired in 4.5), and it needs a unique id. Pass variant="dropdown" or variant="segmented" if you want a System option too.

Note that for this to work you also need to add this to your <head> . This is installed by default in Petal Pro.

# in your <head>:
<.color_scheme_script />

Email helpers

A set of components for email templates. Kind of like Petal Components, but for emails.

Example usage:

<h1>Let's verify your account</h1>
<p>Touch the button below to verify your account</p>
<EmailComponents.button_centered to={@url}>
Verify account
</EmailComponents.button_centered>
<EmailComponents.small_text>
If you didn't create an account with us, please ignore this.
</EmailComponents.small_text>

If you want to add your own components, you can edit the following file:

/lib/petal_pro_web/components/email_components.ex

Then add your components:

defmodule PetalProWeb.EmailComponents do
use Phoenix.Component
def my_new_component(assigns) do
~H"""
Your component HTML goes here
"""
end
end

Now it’ll be available in your email templates!

<h1>Let's verify your account</h1>
<EmailComponents.my_new_component />

Landing page

A set of landing page related components. For example:

<LandingPageComponents.feature_grid
title={gettext("Features")}
description={gettext("Here are some features you can use to get started with your web app.")}
features={[
%{title: "Authentication", description: "Sign in with a password, a PIN or OAuth.", icon: "hero-bolt"},
%{title: "HTML Emails", description: "Transactional emails with a preview page.", icon: "hero-puzzle-piece"},
%{title: "Background Jobs", description: "Oban, ready to go.", icon: "hero-at-symbol"}
]}
/>

The components live in lib/petal_pro_web/components/landing_page_components.ex (hero, logo cloud, feature grid, testimonials, pricing, FAQ and more).

Language select

A dropdown for setting your language.

<.language_select
current_locale={Gettext.get_locale(PetalProWeb.Gettext)}
language_options={PetalPro.config(:language_options)}
/>

This comes from Petal Components (PetalComponents.LanguageSelect), which use PetalProComponents imports for you. Pro had its own copy until 4.5. To see how it’s coded, read deps/petal_components/lib/petal_components/language_select.ex. If you need to change the markup, fork it (see Forking a Petal Component).

Language options are set in your config.exs:

config :petal_pro, :language_options, [
%{locale: "en", flag: "🇬🇧", label: "English"},
%{locale: "fr", flag: "🇫🇷", label: "French"}
]

See translations for more info.

Notification

Flash messages show as toasts. PetalProWeb.Flash.flash_group/1 renders Petal Components’ <.toast_group> and bridges put_flash into it, so every put_flash(:info | :success | :warning | :error, ...) turns up as a stacked, swipe-to-dismiss toast with a progress bar. It disappears after 10 seconds (timer_length). Pass position="bottom-left" (or any corner) to move the stack. In a LiveView you can call PetalComponents.Toast.send_toast/3 for richer toasts, and they land in the same group.

This comes from flash_group/1 set in your layout:

<PetalProWeb.Flash.flash_group flash={@flash} />

To see the implementation:

/lib/petal_pro_web/components/pro_components/flash.ex

Page components

A set of generic page components to help with building pages. To see a list of them, open lib/petal_pro_web/components/pro_components/page_components.ex.

Box

<.box padded>
Your content here
</.box>

Page header

Shows a heading and optional slot for buttons on the right hand side.

<.page_header title={gettext("Organizations")}>
<.button size="sm" link_type="live_patch" to={~p"/admin/orgs/new"} label="New Org" />
</.page_header>

Sidebar tabs container

A two-pane container for settings screens: a nav on the left and your content in a card on the right. Below lg the nav turns into a horizontal scroll strip, and the ScrollStripHook keeps the active item in view.

Settings header

The header at the top of every settings screen: a title, an optional one-line description, and an optional :actions slot for buttons on the right.

<.settings_header
title={gettext("Profile")}
subtitle={gettext("Your name and avatar, shown across the app.")}
/>

Status and role badges

One place for every status pill and role chip in the app. <.status_badge> is a <.badge> with a dot, and its colour comes from the status. <.role_badge> is the same chip without the dot.

<.status_badge status={subscription.status} />
<.status_badge status={:trialing} label={gettext("Trial")} />
<.role_badge role={membership.role} />

To change a colour, edit status_color/1 or role_color/1 in:

/lib/petal_pro_web/components/pro_components/status_badge.ex

User dropdown menu

A Petal Components component. Displays the user’s avatar and will show a dropdown menu upon being clicked. Used in the navbar. Displays a list of menu items (see the Menus section).

<.user_dropdown_menu
user_menu_items={@user_menu_items}
avatar_src={@avatar_src}
current_user_name={if @current_user, do: user_name(@current_user), else: nil}
/>

To see the implementation:

/deps/petal_components/lib/petal_components/user_dropdown_menu.ex

Markdown

Pretty markdown

Renders the markdown as HTML and uses the Tailwind Typography classes to prettify it.

<.pretty_markdown content={some_markdown} class="mx-auto" />

To see the implementation:

/lib/petal_pro_web/components/pro_components/markdown.ex

Markdown

Simple renders pure HTML from markdown.

<.markdown content={some_markdown} />

Social Button

<.social_button provider="google" href={~p"/auth/google"} class="w-full" />
<.social_button provider="github" href={~p"/auth/github"} class="w-full" />

This comes from Petal Components now (Pro’s copy retired in 4.5). variant defaults to "outline", and variant="solid" paints the brand colour. Use navigate= or patch= in place of href= for live links. To see its implementation:

/deps/petal_components/lib/petal_components/social_button.ex

Using Pro components in another project

The Pro components are plain Phoenix.Component modules, so they travel. Copy three things out of Petal Pro:

/lib/petal_pro_web/components/pro_components/ # the components themselves
/lib/petal_pro_web/components/pro_components.ex # the `use PetalProComponents` macro
/lib/petal_pro_web/components/route_tree.ex # imported by the macro, but lives outside the folder

route_tree.ex is easy to miss. pro_components.ex imports PetalProWeb.RouteTree, so without it use PetalProComponents will not compile.

Then add use PetalProComponents to html_helpers in your web module. In Petal Pro that file is lib/petal_pro_web/petal_pro_web.ex; in an app called Fred it is lib/fred_web/fred_web.ex:

defmodule PetalProWeb do
defp html_helpers do
quote do
use Gettext, backend: PetalProWeb.Gettext
use PetalComponents
use PetalProComponents
import PetalProWeb.CoreComponents
import PetalProWeb.Helpers
import Phoenix.HTML
alias Phoenix.LiveView.JS
unquote(verified_routes())
end
end
end

The Pro components are built on top of Petal Components, so the target app needs that dependency too. Petal Pro pins it in mix.exs; copy whatever requirement is there rather than picking a version, because the components assume the CSS that ships with the pinned release.

JavaScript hooks

Some components need a hook. Copy these from assets/js/hooks/ and register them in app.js:

Hook Used by
ClearFlashHook the “Internet lost” banner and any <.flash> you render by hand
ClipboardHook copy-to-clipboard buttons
EditorJsHook the content editor
ScrollStripHook the settings nav strip in sidebar_tabs_container
TippyHook tooltips in the sidebar menu

Take only the hooks for the components you copied. If you skip the content editor, you skip EditorJsHook and the whole @editorjs/* block below with it.

The colour scheme switch, language select, local time, social button and combo box all come from Petal Components now, and their hooks (PetalColorScheme, PetalLocalTime, PetalComboBox) ship in the bundled petal_components JS you’re already spreading into your LiveSocket hooks. There’s nothing to copy for those.

NPM packages

Those hooks pull in npm packages. The current set, from Petal Pro’s assets/package.json:

{
"dependencies": {
"tippy.js": "^6.3.7"
}
}

tippy.js is for the sidebar tooltips. The content editor adds the @editorjs/* packages on top; copy those from package.json if you took EditorJsHook. (Pro’s package.json still lists luxon, but nothing uses it since local time moved to Petal Components, so you can leave it out.)

Read the docs for each Pro component you copy. A few, like the content editor, have setup steps of their own.