Surface is a 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.

Full documentation and live examples can be found at surface-ui.org

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

In order to have ~F 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

Additionally, use Surface.init/1 in your mount function to initialize assigns used internally by surface:

# A LiveView using surface templates

defmodule PageLive do
  use Phoenix.LiveView
  import Surface

  def mount(_params, _session, socket) do
    socket = Surface.init(socket)
    ...
    {:ok, socket}
  end

  def render(assigns) do
    ~F"""
    ...
    """
  end
end

# A LiveComponent using surface templates

defmodule NavComponent do
  use Phoenix.LiveComponent
  import Surface

  def mount(socket) do
    socket = Surface.init(socket)
    ...
    {:ok, socket}
  end

  def render(assigns) do
    ~F"""
    ...
    """
  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.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

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

  def render(assigns) do
    ~F"""
    <button class={"button", @kind} :on-click={@click}>
      <#slot/>
    </button>
    """
  end
end

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