Using Sub-templates with Polymer Templates

Use Lit templates instead
Lit templates are recommended. Polymer templates are available in the next long term supported Vaadin version (LTS), but they are deprecated.

A Polymer template can include child Polymer templates that are defined in other files.

You can use the tag name and import function to reference the child template. It is also necessary to let the server know how to load the child file. This happens automatically if you bind the child template in the mapped Java template file, using the @Id annotation, in the same way as any other Polymer component.

In this section, we demonstrate how to create a parent Polymer template that includes a child Polymer template.

Example: JavaScript Polymer parent template.

import {PolymerElement,html} from '@polymer/polymer/polymer-element.js';
import 'child-template.js';

class ParentTemplate extends PolymerElement {
    static get template() {
        return html`
            <div>Parent Template</div>
            <child-template id="childTemplate"></child-template>`;

    static get is() { return 'parent-template' }

customElements.define(, ParentTemplate);
  • The JavaScript template uses a child-template element. This is a custom element defined in child-template.js (see below).

Example: Mapped parent template Java class.

public class ParentTemplate extends PolymerTemplate<Model> {

    private ChildTemplate child;

public interface Model extends TemplateModel {
    void setName(String name);
  • The associated Java template file defines that ChildTemplate should be instantiated for any template element with a matching tag name, that is child-template.

  • Since the client-side implementation of child-template depends on a click handler defined from server-side Java (see below), an instance of ChildTemplate must be created on the server to receive the event. The @Id annotation mapping ensures that this instance is automatically created and wired to the <child-template> element in the parent template.

Example: JavaScript Polymer child template.

import {PolymerElement,html} from '@polymer/polymer/polymer-element.js';

class ChildTemplate extends PolymerElement {
    static get template() {
        return html`<button on-click="handleClick">Child Template</button>`;

    static get is() { return 'child-template' }

customElements.define(, ChildTemplate);
  • This template delegates a click handler to the server side.

  • The handleClick method is called on the ChildTemplate instance (not the ParentTemplate instance).

Example: Mapped child template Java class.

public  class ChildTemplate extends PolymerTemplate<TemplateModel> {

    private void handleClick() {
        System.out.println("Click on Button in the child template");
You can detect whether a component is part of a PolymerTemplate using the isTemplateMapped method. See the Detecting PolymerTemplate Mapping in Components for more.