JSX Components

For a practical tutorial on how to build components using JSX 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 JSX at all. That said, we already provide a very good integration between metal components and JSX, so if you like using it you should give it a try.


The only thing you need to do to use JSX in your Metal.js component is to extend from JSXComponent, like this:

render function

Now that we've extended from JSXComponent we can use jsx in the render method to specify what our component should render.

Note that your component can have two different types of data: state and props. The main difference is that props is accessed via this.props and will be the original data received from parent components or the constructor. State is accessed from this.state though, like this.state.name in the previous example, and can be configured to use validators, setters, initial values and other features. Check out the guide about state to learn more about this.

Children props

Whenever content is passed inside a component's jsx tag, it will be received through the children props property. That way the component can decide if this content will be rendered at all, and where exactly it should go.

For example, imagine a simple list component that receives its items as its content, like this:

This could be implemented by using the children props:

If you inspect this.props.children you'll notice that it's an array of objects. That gives you a lot of power when handling your component's contents. For example, you can choose to render only part of your children, like this:

Or even change the data that they should receive before being rendered:

Functional components

Sometimes you'll create very simple components, that have no other behavior besides rendering their own contents. In this case you can drop using classes, and instead create simple functions that just render the contents instead.

For example, let's create a simple Button component as a function:

You can then use it from parent components in the same way that you'd use a component class, for example:

Rendering JSX Components

JSX components can either be rendered in the usual way, or via the JSXComponent.render function, like this:

You can also pass a functional component to it:

Or even render directly via JSX:

JSX compilation

For the integration between Metal.js and JSX to work, the JSX code needs to be compiled via a babel plugin called babel-plugin-incremental-dom. Using it directly means you'd need to configure it manually though, so we also provide a babel preset that you can use instead.