JavaScript

Community Resources:

Conditionally Rendering JavaScript Templates

+ Add yours!

Eleventy supports many different types of JavaScript content that will be parsed as Eleventy templates:

Raw Values Jump to heading #

Raw values will not have access to Data or JavaScript Template Functions. Use a function that returns a value instead.

String Jump to heading #

module.exports = "<p>Zach</p>";

Or template literals:

module.exports = `<p>These can
span
multiple
lines!</p>`;

Buffer Jump to heading #

Some templating libraries return Buffers (e.g. viperHTML).

module.exports = Buffer.from("<p>Zách</p>");

Promise Jump to heading #

module.exports = new Promise((resolve, reject) => {
  setTimeout(function() {
    resolve("<p>Zach</p>");
  }, 1000);
});

Function Jump to heading #

Can return any raw value (e.g. String, Buffer, Promise). Use template literals to embed data values without having to concatenate strings!

module.exports = function(data) {
  return `<p>${data.name}</p>`;
};

De-structuring syntax is a little bit easier to read:

module.exports = function({name}) {
  return `<p>${name}</p>`;
};

Maybe you like arrow functions:

module.exports = ({name}) => `<p>${name}</p>`;

async functions work too:

const getAnAsyncThing = require("./lib/asyncThing");

module.exports = async function(data) {
  return `<p>${await getAnAsyncThing()}</p>`;
};

Classes Jump to heading #

Eleventy looks for classes that have a render method and uses render to return the content of the template. render methods can be async.

render can return any raw value (e.g. String, Buffer, Promise).

class Test {
  // or `async render({name}) {`
  render({name}) {
    return `<p>${name}</p>`;
  }
}

module.exports = Test;

Optional data Method Jump to heading #

This data acts as Front Matter for the template and similarly to Front Matter will take precedence over all other data in the data cascade. The data method can be asynchronous async data() or it can be a getter get data().

class Test {
  // or `async data() {`
  // or `get data() {`
  data() {
    return {
      name: "Ted",
      layout: "teds-rad-layout",
      // … other front matter keys
    };
  }

  render({name}) {
    // will always be "Ted"
    return `<p>${name}</p>`;
  }
}

module.exports = Test;

Permalinks Jump to heading #

The permalink data key will work here. Permalinks can be a raw value (e.g. String, Buffer, Promise) or a Function that returns any raw value.

Permalink String Jump to heading #

class Test {
  data() {
    return {
      // Writes to "/my-permalink/index.html"
      permalink: "/my-permalink/"
    };
  }

  render(data) { /* … */ }
}

module.exports = Test;

Permalink Function Jump to heading #

Permalink Functions can return any raw value (e.g. String, Buffer, Promise).

class Test {
  data() {
    return {
      key: "hello",
      // Writes to "/my-permalink/hello/index.html"
      permalink: data => `/my-permalink/${data.key}/`
    };
  }

  render(data) { /* … */ }
}

module.exports = Test;

Permalink Function using a Filter Jump to heading #

Universal filters, shortcodes, and other JavaScript Template Functions work here and are exposed on this. Read more about Eleventy provided Universal Filters.

class Test {
  data() {
    return {
      title: "This is my blog post title",
      // Writes to "/this-is-my-blog-post-title/index.html"
      permalink: function(data) {
        return `/${this.slug(data.title)}/`;
      }
    };
  }

  render(data) { /* … */ }
}

module.exports = Test;

Markdown and JavaScript Jump to heading #

Yes, you can use JavaScript as your preprocessor language for Markdown. Read more about templateEngineOverride.

class Test {
  data() {
    return {
      myName: "Zach",
      templateEngineOverride: "11ty.js,md"
    };
  }

  render(data) {
    return `# This is ${data.myName}`;
  }
}

module.exports = Test;

JavaScript Template Functions Jump to heading #

A JavaScript Template Function allows you to extend your JavaScript templates with extra functionality. If you add any Universal Filters or Shortcodes, they will be exposed as JavaScript Template Functions.

module.exports = function(eleventyConfig) {
  eleventyConfig.addJavaScriptFunction("myFunction", function(a, b) { … });
};

module.exports = function(data) {
  return `<h1>${this.myFunction(data.a, data.b)}</h1>`;
};

Asynchronous JavaScript Template Functions Jump to heading #

This works the same as any async JavaScript function or function that returns a Promise.

This is the same as the example above but adds async before the function.

module.exports = function(eleventyConfig) {
  eleventyConfig.addJavaScriptFunction("myAsyncFunction", async function(a, b) { … });
};

This is the same as the example above but adds await before the function is called.

module.exports = async function(data) {
  return `<h1>${await this.myAsyncFunction(data.a, data.b)}</h1>`;
};

Warning about Arrow Functions Jump to heading #

module.exports = (data) => {
  // Using `this` in an arrow function will throw an error!
  return `<h1>${this.myFunction(data.a, data.b)}</h1>`;
};

Relationship to Filters and Shortcodes Jump to heading #

Any universal filters or shortcodes will also be available as JavaScript Template Functions.

module.exports = function(eleventyConfig) {
  // Universal filters (Adds to Liquid, Nunjucks, 11ty.js, and Handlebars)
  eleventyConfig.addFilter("myFilter", function(myVariable) { … });

  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
  eleventyConfig.addShortcode("user", function(firstName, lastName) { … });

  // Universal Paired Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
  eleventyConfig.addPairedShortcode("pairedUser", function(content, firstName, lastName) { … });
};

module.exports = function(data) {
  return `
<h1>${this.myFilter(data.myVar)}</h1>
<p>${this.user(data.firstName, data.lastName)}</p>
<p>${this.pairedUser(`Here is some more content`, data.firstName, data.lastName)}</p>
`;
};

Access to page data values New in v0.11.0 Jump to heading #

If you aren’t using an arrow function, JavaScript Functions (and Nunjucks, Liquid, and Handlebars Shortcodes) will have access to Eleventy page data values without needing to pass them in as arguments.

module.exports = function(eleventyConfig) {
  eleventyConfig.addJavaScriptFunction("myFunction", function() {
    // Available in 0.11.0 and above
    console.log( this.page );

    // For example:
    console.log( this.page.url );
    console.log( this.page.inputPath );
    console.log( this.page.fileSlug );
  });
};

Other pages in Template Languages:

• HTML
• Markdown
• JavaScript
• Nunjucks
• Liquid
• Handlebars
• Mustache
• EJS
• HAML
• Pug
• Custom

Related Docs

• Template Filters
• Template Shortcodes
• Watch JavaScript Dependencies