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

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.

Add surface to the list of dependencies in mix.exs:

def deps do
  [
    {:surface, "~> 0.4.1"}
  ]
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],
  ...
]

To allow live reloading for .sface files, add the related patterns to the endpoint configuration in your config/dev.exs:

config : MyApp, MyAppWeb.Endpoint,
live_reload: [
  patterns: [
    ...,
    ~r"lib/my_app_web/live/.*(sface)$",
  ]
]

That's all!

Migrating from v0.4.x to v0.5.x

Surface v0.5.0 introduces a new syntax which requires migrating components written in previous versions. In order to make the migration process as smooth as possible, Surface v0.5.x ships with a converter that can automatically translate the old syntax into the new one.

Please see the Migration Guide for details.

Using Surface with Phoenix templates (optional)

Using Surface components in vanilla Phoenix templates is partially supported but usually not recommended. For more information, please visit Usage with Phoenix templates.

Running the examples (optional)

Most of the components used in the examples presented in this website are just thin wrappers around Bulma components. 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 root.html.leex:

<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