Surface

Surface is a server-side rendering component library for Phoenix that builds rich interactive user interfaces with minimal custom JavaScript.

What is Surface?

Surface is a server-side rendering component library built on top of Phoenix LiveView and its component API. It takes Elixir component modules that use the ~F sigil and compiles them into LiveView-compatible code, producing real-time, interactive UIs without client-side JavaScript. The library is authored by Marlus Saraiva and released under the MIT License.

Key Features

• HTML-centric templating — A templating language designed to read like HTML, improving the development experience for Elixir UI code.
• Components as modules — Components can be stateless, stateful, renderless, or compile-time, giving developers different patterns for structuring UI logic.
• Declarative properties — Components explicitly declare inputs (properties and events) with prop, enabling compile-time validation of how components are used.
• Slots — Components can declare placeholders that callers fill with custom content, allowing flexible composition.
• Contexts — Parent components share data with descendants without passing it as props at every level.
• Compile-time checking — The template structure, component properties, slots, and events are validated during compilation, catching many errors before runtime.
• Editor integration — Editors and tools get warnings/errors, syntax highlighting, jump-to-definition, and auto-completion (soon) through dedicated tooling.

Who is it for?

Elixir and Phoenix developers who want to build rich front-ends without writing JavaScript should use Surface. Teams already using Phoenix LiveView will find Surface's component model a natural fit. Developers who value compile-time safety in their templates benefit from Surface's validation of props, slots, and events.

What can you do with Surface?

• Build LiveView apps — Write UI components in an HTML-centric language and have them rendered server-side with real-time updates.
• Create reusable component libraries — Package stateless, stateful, or renderless components with declared properties and slots.
• Generate a starter setup — Run mix surface.init to configure a new project, with a --demo flag that creates a sample component at /demo.
• Set up a Surface Catalogue — Use the --catalogue flag to generate a living style guide at /catalogue for documenting components.

How does Surface work?

Install Phoenix with mix phx.new my_app, add {:surface, "~> 0.12.0"} to mix.exs, then run mix surface.init to update required files. The init task can generate a demo component and a Surface Catalogue with --demo --catalogue. Finally, start the server with mix phx.server and visit http://localhost:4000.

FAQ

Is Surface free?

Yes. Surface is open source under the MIT License, so it can be used freely in commercial and personal projects.

Does Surface require Phoenix LiveView?

Yes. Surface is built on top of Phoenix LiveView and its component API, so you need a Phoenix application with LiveView installed.

How do I install Surface?

Add {:surface, "~> 0.12.0"} to your mix.exs dependencies, run mix deps.get, and then run mix surface.init to configure the project.

What is the Surface Catalogue?

It is a generated, living style guide for your components. Running mix surface.init --catalogue sets it up at the /catalogue route.