This library helps you write encapsulated bits of HTML into a single unit called component in your server rendered Phoenix web site. Similar to how react/ember/web components do.

• Synopsis
• Installation
• Quick start
• Configuration
• License

You can generate a new component with the built-in generator

$ mix phoenix.gen.component button
* creating web/components/button/view.ex
* creating web/components/button/template.html.eex
* creating test/components/button_test.exs

Then you can use the new component in a template

# /web/views/page_view.ex
defmodule MyApp.PageView do
  use MyApp.Web, :view
  use PhoenixComponents.View

  import_components [:button]
end

# /web/templates/page/show.html.eex

<%= button type: :primary do %>
  My cool button!
<% end %>

With the corresponding component definition

# /web/components/button/view.ex
defmodule MyApp.Components.ButtonView do
  use PhoenixComponents.Component

  def class_for_type(type) do
    "btn btn--" <> to_string(type)
  end
end

# /web/components/button/template.html.eex
<button class="<%= class_for_type @attrs.type %>">
  <%= @content %>
</button>

Add phoenix_components to your mix.exs deps:

def deps do
  [{:phoenix_components, "~> 1.0.0"}]
end

and then you have to add one config to your config file

config :phoenix_components, app_name: MyApp

where MyApp is the module that represents your phoenix app.

If you're running Elixir 1.3 or lower, don't forget to add it under you applications list in mix.exs

def application do
  [applications: [:phoenix_components]]
end

This is a quick overview of how to create and use a component in your application.

After installing the dependency you need to configure your application.

You can do this by adding this line to your web/web.ex file

Look for the line def view do and update it to include this line

def view do
  quote do
    use Phoenix.View, root: "web/templates"
    use PhoenixComponents.View # Add this line
    ...

Phoenix components are defined by two different parts, a view and a template. The view contains helper functions and the template contains the HTML.

To create a button component you need to create the view file web/components/button/view.ex with the following content

defmodule MyApp.Components.Button do
  use PhoenixComponents.Component

  def classes do
    "btn btn-default"
  end
end

Then create the template file web/components/button/template.html.eex with the following content

<button class="<%= classes %>">
  <%= @content %>
</button>

Note that @content variable will contain the content defined inside the button block. Next section shows this in more detail.

You can use the component from any template by using the helper function component.

In any template, e.g. web/templates/pages/show.html.eex add the button component.

<%= component :button do %>
  My cool button!
<% end %>

The content inside the component block is passed to the component as the @content variable.

You can import the components in any view by using the import_components function. This allows you to avoid having to call component helper and instead just use the name of the component.

defmodule MyApp.PageView do
  use Phoenix.Web, :view
  import_components [:button, :jumbotron]
end

Then you can use these helpers from your templates

<%= button type: :submit do %>
  Submit form!
<% end %>

When calling a component you can pass any attribute you like.

<%= button type: :submit do %>
  Submit form!
<% end %>

Inside the component's template these attributes are going to be available in the @attrs map.

<button type="<%= @attrs.type %>">
  <%= @content %>
</button>

You can configure where to put the components by editing your application configuration file config/config.exs.

config :phoenix_components, path: "lib/foo/bar"

Components are obtained from web by default.

phoenix_components is licensed under the MIT license.

See LICENSE for the full license text.