Subtemplates

Sub templates let you render components from inside another component. This lets you scale your architecture for complex apps.

Syntax Types

Shorthand Syntax

The simplest way to specify a subtemplate is to include the template name and its values inlined into the expression.

{> userProfile name=(getFullname user.id) age=user.age}

Shorthand with Data Object

If you would like to return the data context as an object from an expression you can use the data property. The returned object becomes the subtemplate’s data context, and the expression is re-evaluated reactively when dependencies change.

const createInstance = ({ self }) => ({
  getData(user) {
    return {
      name: self.getFullname(user.id),
      age: user.age
    }
  };
});

{> userProfile data=(getData user)

Verbose Syntax

Verbose syntax uses the syntax {> template name=templateName data=someData} and allows you to more explicitly define the name and data for a subtemplate. When using verbose expressions you can use an inline object for data or an expression.

{> template
  name='userProfile'
  data={
    name: getFullname(user.id),
    age: user.age
  }
}

Advanced Uses

Dynamic Templates

Verbose syntax supports using an expression to return a template name. This means you can dynamically swap templates based on the returned value of a function. This can be incredibly useful in many advanced use cases.

const createInstance = ({ self }) => ({
  getProfileTemplate(user) {
    return user.isEmployee
      ? 'employeeProfile'
      : 'userProfile'
    ;
  };
});

{> template
  name=(getProfileTemplate user)
  data={
    name: (getFullname user.id),
    age: user.age
  }
}

Specifying Templates in Settings

You can use dynamic template names to even let users specify templates directly from settings objects. This can let users author their own templates that are then consumed by your component.

You can see an example of this in action below.

Data Reactivity

Default Behavior

Data passed into subtemplates is reactive by default. When the underlying data changes, the subtemplate updates automatically.

{> userProfile name=user.name age=user.age}

If user.name changes, the subtemplate re-renders with the new value. This is true for both shorthand props and shorthand data= expressions.

Surgical vs Coarse Updates

How you pass data determines how granularly the subtemplate responds to changes.

Individual props give you surgical updates — each value is tracked independently. Changing name won’t cause age to re-evaluate.

{> todoItem title=todo.title completed=todo.completed}

A data expression treats the returned object as a single unit. If any part of the object changes, all expressions in the subtemplate re-evaluate.

{> todoItem data=(getTodo id)}

Use individual props when the subtemplate is rendered many times (like items in a list) and performance matters. Use a data expression when convenience matters more than granularity.

Static Data in Verbose Syntax

In verbose syntax, inline data objects using data={...} are static — they are evaluated once and do not update reactively.

{> template
  name='userProfile'
  data={
    name: getFullname(user.id),
    age: user.age
  }
}

To make individual values in a verbose object reactive, use reactiveData:

{> template
  name='userProfile'
  reactiveData={
    isLoggedIn: getLoginStatus
  }
  data={
    name: getFullname(user.id),
    age: user.age
  }
}

Here isLoggedIn will update when the signal changes, while name and age remain fixed at their initial values.

Verbose syntax also supports reactive data expressions, which behave the same as the shorthand data= form — the entire object re-evaluates as a unit:

{> template
  name='userProfile'
  data=getUserData
}

Examples

Basic Example

A template includes two values, the name or template name to render and data the data to pass into the subtemplate. Templates must be passed to the defineComponent call of a component that references a subtemplate.

This example uses the shorthand syntax for a subtemplate

{>row row=row company=company}

This will render a template named row with the data context set to

data = {
  row: row, // row in table is passed into row
  company: company // company in table is pass into row
};

This could also have been written with a helper that returns the data context. This form is reactive — when the data changes, the subtemplate updates.

{>row data=getRowData}

Or using verbose syntax that specifies the template name explicitly. Note that verbose data={...} with an inline object is static — see Data Reactivity for details.

{> template
  name='row'
  data={
    row: row,
    company: company
  }
}

Advanced Example

Exposing templates as a setting allows for complex use cases where a portion of the rendered template can be dynamic and specified by the user at run time.

This allows for more complex components that let users control how a portion of the component renders.

The following example shows exposing a setting which lets a user specify a template to render a row.

In index.js you can see where the template is imported and specified by the user who is consuming the component.