Surface is a server-side rendering component library that allows developers to build rich interactive user-interfaces , writing minimal custom Javascript.

Built on top of Phoenix LiveView and its new LiveComponent , Surface leverages the amazing Phoenix Framework to provide a fast and productive solution to build modern web applications.

For installation instructions, please visit the Getting Started guide.

How does it work?

At compile time, Surface translates components defined in an extended HTML-like syntax into regular Phoenix templates. It also translates standard HTML nodes allowing us to extend their behaviour adding new features like syntactic sugar on attributes definition, directives, static validation and more.

In order to have your code translated, you need to use the ~H sigil when defining your templates.


  • An HTML-centric templating language with built-in directives ( :for , :if , …) and syntactic sugar for attributes (inspired by Vue.js).

  • Components as modules - they can be stateless, stateful, renderless or compile-time.

  • Declarative properties - explicitly declare the inputs (properties and events) of each component.

  • Slots - placeholders declared by a component that you can fill up with custom content .

  • Contexts - allows a parent component to share data with its children without passing them as properties.

  • Compile-time checking of components and their properties.

  • Integration with editor/tools for warnings/errors, syntax highlighting, jump-to-definition, auto-completion (soon!) and more.

Note: Some of the features are still experimental and subject to change.