Creating re-usable Components with Eleventy using Shortcodes (Advanced)

If you are creating websites with Eleventy, sometimes, you will need to create a reusable component where you can re-use it on many places. Eleventy provides us a neat way to handle this using shortcodes. However, this requires registering the shortcode inside .eleventy.js. However when you have a lot of components, it would be better if we could organize it better.

In this article, I'll be showing how you can create as many components without polluting .eleventy.js. If you only need simple integration, Please refer the Official Docs.

I have created an Eleventy Starter Template called "NEAT Starter"
View on Github

The Plan

When we have many components, its better to organize in files & folder. So first we will create a components folder inside _includes/ and then inside components, we create another folder called shortcodes. This is where we put all re-usable components. We will also create a file inside the components folder called shortcode.js where we import all component shortcodes and register in Eleventy.

Writing Shortcode

First, let us write our first shortcode to return full name & username of a user. Create a user.js file inside components/shortcodes folder and write some code like this:

// components/shortcodes/user.js

module.exports = (data) => {
  return `<div class="user">
<div class="user">${}</div>
<div class="usernmae">@${data.username}</div>

Registering Shortcode

Now Register this shortcode inside components/shortcode.js file by importing the above shortcode and pass it as an argument.

const user= require("./shortcodes/user.js");

module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("user", user);

Adding to .eleventy.js

Now we need to integrate it to .eleventy.js to make it working.

const addShortcodes = require("./_includes/components/shortcode.js");

module.exports = function (eleventyConfig) {

Calling the Component

Now call the component anywhere you like (eg: any html or njk files) like the following.

{% user name="Surjith", username="surjithctly" %}

That's it. Now just refresh the server using npm run start to see the changes.

Note: If you make some changes later to the js files, you might need to restart the server each time to see the new changes.

Adding More Components

Our main objective is to create many components. So let's create another one and see how we can do that. This time, we will create a Paired Shortcode, so that you can put content inside the shortcode (like a wrapper). Learn more . Create a card.js file inside components/shortcodes folder and write some code like this:

// components/shortcodes/card.js

module.exports = (content, options) => {
  return `<div class="card">
<div class="title">${options.title}</div>
<div class="content">${content}</div>

Registering Paired Shortcode

Now Register this as paired shortcode inside components/shortcode.js. We will add this along with our previous shortcode.

const user= require("./shortcodes/user.js");
const card= require("./shortcodes/card.js");

module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("user", user);
  eleventyConfig.addPairedShortcode("card", card);

This time, we don't need to add config to .eleventy.js because its already handled by our previous import. That's the benefit of using this method instead of adding every config inside the .eleventy.js.

Calling the Component

Now we call the component anywhere same as the other one. However note the endcard since we are using paired shortcode.

{% card title="Awesome Title"  %}
  Hey, This should render as card content.
{% endcard %}

However, you will need to restart the server to view the changes. Run npm run start to view the changes.

Wrapping up

Same way, you could create as many re-usable components you want. You may also create subfolders to arrange it even better.

Let me know your thoughts.

Follow me on Twitter

Did you find this article valuable?

Support Surjith S M by becoming a sponsor. Any amount is appreciated!