Getting Started

Start building rich interactive user-interfaces, writing minimal custom Javascript now. For a quick start, you can either add Surface to an existing Phoenix LiveView project or install it from scratch.

Installing from scratch

Phoenix v1.5 comes with built-in support for LiveView apps. You can create a new application with

mix phx.new my_app --live

Then add surface to the list of dependencies in mix.exs:

def deps do
  [
    {:surface, "~> 0.1.0"}
  ]
end

If you're using mix format, make sure you add surface to the import_deps configuration in your .formatter.exs file:

[
  import_deps: [:ecto, :phoenix, :surface],
  ...
]

That's all!

Note: In case you want to add Surface to an existing Phoenix application that doesn't have LiveView properly installed, please see Phoenix Liveview's installation instructions at hexdocs.pm/phoenix_live_view/installation.html.

Using Surface on plain Phoenix views (optional)

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

You will also need to call Surface.init/1 in the mount function:

defmodule PageLive do
  use Phoenix.LiveView

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

  ...
end
defmodule NavComponent do
  use Phoenix.LiveComponent

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

  ...
end

Running the examples

Most of the components used in this website as well the examples in the documentation are just thin wrappers around Bulma components. Why Bulma? Because it's a free, open source, responsive CSS framework with no JS dependencies, which makes it a perfect fit to use with Phoenix LiveView. However, you can easily adapt any of the examples to any library of your preference or try them out with your own CSS styles.

For a quick start with bulma, you can add the following line to your layout_view.ex:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.8.0/css/bulma.min.css" />

or add it to the list of dependencies in assets/package.json:

"dependencies": {
  "bulma": "0.8.0"
}

Tooling