In order to create a new component you need to define a module and
use one of
the available component types:
- Surface.Component - A stateless component.
- Surface.LiveComponent - A live stateful component.
Surface.LiveView - A wrapper component around
- Surface.MacroComponent - A low-level component which is responsible for translating its own content at compile time.
Note: For simpler, stateless components that don't require advanced features like contexts, you can also define them as function components as described in the phoenix docs. If you prefer, you can use
~Hfor a full Surface experience. Keep in mind that some static validations provided by Surface may not available when using function components.
When declaring a property and/or data, you can define the type of the assign using one of the following types:
Note: Currently, some of the types above work just as annotations and don't have any practical use aside from documentation. If the type you need is not in that list, you can safely use
:anyinstead. However, some other types like
:eventare handled differently, i.e. there are extra rules and behaviours applied to them.
In case you want to isolate all templating code into a separate file, you can create a
file using the same base name in the same directory of the related component or liveview.
components ├── example.ex ├── example.sface ├── hello.ex └── hello.sface ...
This way you can remove the implemented
render/1 altogether. Any defined assign or function
will be available in the new template.
Note: Unlike EEX templates, which can be used with any kind of text file, Surface's templates already extend HTML. Therefore, they are named simply as
Since a component is just a module, it can injected using either its full name
or a valid
Using full module name:
alias MyProject.Components.MyButton alias MyProject.Components.MyLink, as: Link def render(assigns) do ~F""" <MyButton>Ok</MyButton> ... <Link> ... </Link> """ end
The component API
Surface provides built-in functions that should be used to declare the essential building blocks of any component:
prop- Defines a property for the component.
data- Defines a data assign for a stateful
LiveView. The set of all
dataassigns represents the state of the component/view.
slot- Defines a placeholder (slot) that can be filled up with custom content.
All values declared using any of the above functions will be merged into the components
and will be available inside the template using the
Having everything explicitly declared brings a lot of benefits since all information provided can be used later for introspection allowing Surface to provide:
- Syntactic sugar on attributes definition - e.g. CSS style classes.
Improved API for events - automatically setting
- Compile-time checking - validations of required properties, incompatible slots, etc.
- Integration with editor/tools - for warnings/errors, syntax highlighting, jump-to-definition, auto-completion and more.
Docs generation - see the
Let's take a look at how a component can be defined using Surface's API.
defmodule Button do use Surface.Component @doc "The type (color) of the button" prop type, :string, values: ["primary", "success", "info"] @doc "The Button is expanded (full-width)" prop expanded, :boolean, default: false @doc "Triggers on click" prop click, :event @doc "Triggers on focus" prop focus, :event @doc "The content of the button" slot default, required: true ... end
The public API of the
Button above can be automatically generated, including all
information about properties, slots and events, divided by group in each
individual tab as follows:
Public vs private
slot defines the public API of the component as their values
are initialized outside the component. Assigns declared as
data are considered
private since they can only be accessed inside the component's scope.
It's important to keep that distinction in mind when designing a new component. Remember that users need to be able to easily identify the public interface so they can properly interact with the component. The recommendation is to have everything explicitly declared and well documented using Surface's component API.