Getting Started

Start building rich interactive user-interfaces , writing minimal custom Javascript now. For a quick start, choose one of the boilerplates projects or install Surface from scratch.


A minimal bare bones Surface boilerplate is available in case you want to take it for a spin without even bothering to install node/npm, i.e., no webpack, no babel , etc.

Steps required:

  1. Clone the project with git clone
  2. Install dependencies with mix deps.get
  3. Start Phoenix endpoint with mix phx.server

That’s all! You can then visit localhost:4000 from your browser.

Further information and source code be found at .

Installing from scratch


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

def deps do
    {:surface, "~> 0.1.0-alpha.1"}

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

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],

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="" />

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

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


  • A VS Code extension that adds support for syntax highlighting is available at .

  • Improved integration with ElixirSense to provide auto-completion , go-to-definition and more is comming soon!