Surface is component based library for Phoenix LiveView.

Built on top of the new Phoenix.LiveComponent API, Surface provides a more declarative way to express and use components in Phoenix.

A work-in-progress live demo with more details can be found at surface-demo.msaraiva.io

This module defines the ~H sigil that should be used to translate Surface code into Phoenix templates.

In order to have ~H available for any Phoenix view, add the following import to your web file in lib/my_app_web.ex:

# lib/my_app_web.ex

...

def view do
  quote do
    ...
    import Surface
  end
end

Defining components

To create a component you need to define a module and use one of the available component types:

• Surface.Component - A stateless component.
• Surface.LiveComponent - A live stateful component.
• Surface.LiveView - A wrapper component around Phoenix.LiveView.
• Surface.DataComponent - A component that serves as a customizable data holder for the parent component.
• Surface.MacroComponent - A low-level component which is responsible for translating its own content at compile time.

Example

# A functional stateless component

defmodule Button do
  use Surface.Component

  property click, :event
  property kind, :string, default: "is-info"

  def render(assigns) do
    ~H"""
    <button class="button {{ @kind }}" phx-click={{ @click }}>
      {{ @inner_content.() }}
    </button>
    """
  end
end

You can visit the documentation of each type of component for further explanation and examples.

Directives

Directives are built-in attributes that can modify the translated code of a component at compile time. Currently, the following directives are supported:

• :for - Iterates over a list (generator) and renders the content of the tag (or component) for each item in the list.

• :if - Conditionally render a tag (or component). The code will be rendered if the expression is evaluated to a truthy value.

• :show - Conditionally shows/hides an HTML tag, keeping the rendered alement in the DOM even when the value is false.

• :bindings - Defines the name of the variables (bindings) in the current scope that represent the values passed internally by the component when calling the @content function.

• :on-[event] - Sets a phx event binding defining the component itself as the default handler (target). This is the prefered way to use phx events in Surface as it can properly handle properties of type :event. Available directives are: :on-phx-click, :on-phx-blur, :on-phx-focus, :on-phx-change, :on-phx-submit, :on-phx-keydown and :on-phx-keyup.

Example

<div>
  <div class="header" :if={{ @showHeader }}>
    The Header
  </div>
  <ul>
    <li :for={{ item <- @items }}>
      {{ item }}
    </li>
  </ul>
</div>