Soy Components

For a full tutorial on how to build components using soy templates, make sure to follow the Modal tutorial section.

This guide will explain some details about the integration between Metal.js components and soy templates.

Note that Metal.js is template agnostic, so it's not necessary to use soy at all. That said, we already provide a very good integration between metal components and soy, so if you like this template language you should give it a try.


The only thing you need to do to use soy templates in your Metal.js component is to call Soy.register, passing it your component class and the soy templates you're going to use, like this:

By default, Metal.js will use the soy template called render as the entry point for rendering. But you can tell us to use a different one if you prefer by passing the name as the last param to the Soy.register call, like this:

Template file

Make sure that your soy file has the entry point template (render by default), otherwise nothing will be rendered.

This main template will receive as data a combination of:

Note that by default all params declared on the component's main soy template are automatically configured as state properties as well, but without any special configurations (like initial value or validators). If they're manually defined through the STATE property they will retain the setup specified there though.

Any params passed to the component but not directly declared on its main soy template will be treated as basic configuration data, meaning that changes to them will not automatically rerender the component. They can still be passed down to other templates using data="all", as well be accessed via the config property on the js file.

Soy compilation

For the integration between Metal.js and soy to work, the soy files need to be compiled via one of our available build tools. That's because they don't just compile the code, but also add some information that help with the integration (like export declarations).

The available build tools that correctly compile soy for Metal.js are: