Pro Components

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

heex

<.color_scheme_switch />

The switch to switch between light and dark mode.

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

heex

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

Email helpers

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

Example usage:

elixir

<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:

elixir

/lib/petal_pro_web/components/email_components.ex

Then add your components:

heex

defmodule PetalPro.Components.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!

heex

<h1>Let's verify your account</h1>

<.my_new_component />

Landing page

A set of landing page related components. For example:

elixir

<LandingPage.features
  title={gettext("Features")}
  description={gettext("Here are some features you can use to get started with your web app.")}
  features={
    [
      %{
        title: "Authentication",
        description: Faker.Lorem.sentence(10..20),
        icon: :lightning_bolt
      },
      %{
        title: "HTML Emails",
        description: Faker.Lorem.sentence(10..20),
        icon: :puzzle
      },
      %{
        title: "Background Jobs",
        description: Faker.Lorem.sentence(10..20),
        icon: :at_symbol
      }
    ]
  }
/>

A dropdown for setting your language.

heex

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

This is a Petal Pro component. If you want to see how it’s coded or modify it to your own needs you can edit this file:

elixir

/lib/petal_pro_web/components/pro_components/language_select.ex

Language options are set in your config.exs:

css

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

See translations for more info.

Notification

A flash notification component defined in Petal Pro. See docs. The flash notification includes an animated progress bar at the top that advances to the right — once it completes, the notification automatically dismisses.

This comes from flash_group/1 set in your layout:

To see the implementation:

Page components

A set of generic page components to help with building pages. To see a list of them:

Box

Page header

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

Sidebar tabs container

A panel with a sidebar for a menu, and a slot for content on the right.

A Petal Pro 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).

heex

<.user_menu_dropdown
  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:

elixir

/lib/petal_pro_web/components/pro_components/user_dropdown_menu.ex

Markdown

Pretty markdown

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

heex

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

To see the implementation:

elixir

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

Markdown

Simple renders pure HTML from markdown.

heex

<.markdown content={some_markdown} />

heex

<.social_button
  link_type="a"
  to={Routes.user_ueberauth_path(@conn_or_socket, :request, "google")}
  variant="outline"
  logo="google"
  class="w-full"
/>

<.social_button
  link_type="a"
  to={Routes.user_ueberauth_path(@conn_or_socket, :request, "github")}
  variant="outline"
  logo="github"
  class="w-full"
/>

This is a Petal Pro component. To see its implementation:

elixir

/lib/petal_pro_web/components/pro_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:

elixir

/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:

elixir

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`	flash notifications
`ClipboardHook`	copy-to-clipboard buttons
`ColorSchemeHook`	the colour scheme switch
`ComboBoxHook`	the combo box
`EditorJsHook`	the content editor
`LocalTimeHook`	local time rendering
`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.

Two of those hooks may already be covered. From petal_components 4.8 the colour scheme lives in the PetalColorScheme hook behind <.color_scheme_switch>, and local time rendering lives behind <.local_time>, both in the bundled petal_components JS you are importing anyway. Pro’s own components are wired to Pro’s ColorSchemeHook and LocalTimeHook, so copy those if you copy the Pro components that use them. If you are reaching for the library versions instead, there is nothing to copy.

NPM packages

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

json

{
  "dependencies": {
    "tom-select": "^2.5.2",
    "tippy.js": "^6.3.7",
    "luxon": "^3.4.4"
  }
}

tom-select is for the combo box, tippy.js for tooltips, luxon for local time. The content editor adds the @editorjs/* packages on top; copy those from package.json if you took EditorJsHook.

Read the docs for each Pro component you copy. A few, the combo box especially, have setup steps of their own.

On this page

Stay up to date

Get notified about updates and when we release something.

Components

Layouts

Brand

Color scheme switch

Email helpers

Landing page

Language select

Notification

Page components

Box

Page header

Sidebar tabs container

User dropdown menu

Markdown

Pretty markdown

Markdown

Social Button

Using Pro components in another project

JavaScript hooks

NPM packages

Stay up to date