Tuesday, April 25, 2017

How to add a custom rendering in all your future Sitecore SXA sites

Sitecore SXA and custom renderings

There are already blogs about how to create custom renderings in Sitecore SXA. The official Sitecore documentation site has an article on how to create your rendering and add it to the toolbox. You can read on my own blog how to do this with variants.

In short, the steps are:
  • Create a rendering (controller, action method, repository ...)
  • Create a controller rendering in Sitecore
  • Add a new rendering to the toolbox

Once you completed these steps you will have a new component in the toollbox for your site. But a Sitecore instance with SXA will probably host multiple sites, so what if you created a rendering that you want to use on all your future SXA sites? I found some information on that and would like to share it, using an existing component as example to show you how to create your own. This will also show that it is possible to add your rendering to the existing component groups in SXA, but that might be not such a good idea considering that upgrades of SXA might remove your additions. And of course, you don't want to mix features.

Adding your rendering to the available components of new SXA sites

First step is to open the Sitecore content editor. I will use the "Page Content" renderings group to show what you can do as this is one with some nice examples.

Branch Template

First thing to do is to create a branch template that will create the item(s) needed to make our component(s) available when a new site is generated. Go to /sitecore/templates/Branches/Feature/Experience Accelerator and you will find already quite some folders with branch templates for the existing components. As we are using Page Content as example, lets check that folder:

The folder contains a few branches, but we'll focus on the Available Page Content Renderings now. This is the branch template that will be used to create the item with the renderings that are included in the "Page Content" rendering group - you'll find all of them in the $name item in the branch. 

To create your own you need to define a new branch template just like it with a proper name. If you just want to add your rendering to an existing group, you can simply add it to the proper branch template and your done - you don't need any further steps in that case but be aware that updates might delete your addition (of course, this is easily checked and re-added if needed).

Site Setup

If you created your own branch to have your own rendering group, go to /sitecore/system/Settings/Feature/Experience Accelerator. You will recognize the folders there for all the default rendering groups and you should create your own here.

First item in the folder is a "Site Setup" item, where we can define the name of the group and whether it is checked by default (or installed by default).

The Site Setup has several children - steps that will be taken during setup. The first ones you can see in the Page Content example are all of type "AddItem" (/sitecore/templates/Foundation/Experience Accelerator/Scaffolding/Actions/Site/AddItem)


Let's take the first one as example as this is the most interesting one:

Add Available Renderings

In the AddItem item, you choose a location and a template (and a name). To add the available renderings -what is our main purpose here-, we take the Available Renderings parent as location and use our branch template as Template - the one you created in the first step.

This will tell the SXA site creation script to create a new item based on the branch template at the set location. 

Data items

You can use the same AddItem to create other items as well, like a data folder (including data items if you want). The Page Content has examples on that using other branch templates. 

Rendering variants

If your rendering can make use of variants, you should also create the items for that. The Page Content has examples on empty variant folders (like Field Editor) or variant folders with a default variant (like Page List) where again a branch template is used to create all the necessary items.

Other instances

But what about other instances? Yes, indeed - we have been talking about SXA sites within the same instance here. That covers quite some scenarios, but if you want to have this in other instances with SXA as well you can easily package your stuff and tranfer it - after all, we did nothing more than manipulating items in Sitecore...


Adding your own components is quite powerful but still fairly easy if you know which steps to take. Just adding the renderings can be done with the steps provided here, but I'm sure they are more possibilities to discover by looking at the existing features (e.g. adding to the theme, which you can check in the search feature). And that is the best advice I can give you: take a look at the existing features and you'll discover the fancy world of SXA ;)


  1. Hey ! Thank you very much for this useful article, you must have spent quite some time getting this!
    Still, it does not work for me. I followed the steps to add a folder, in addition to your tutorial, I filled the Originator field in the available rendering created to link all this stuff together. Still success is partial, only two out of the four renderings are available in experience editor. Even more surprising, those items were one available when I had added them one by one in available renderings but then two of them disappeared and this is why I followed your tutorial.
    Maybe is it because I just copied the available renderings from an other folder ? (but I can't see any filled field in those items!).
    I then tried a more simple case, adding the renderings to an existing folder adding them in the available rendering and in the $name... this time none of them was added !

    1. I would suggest you to post your issue on https://sitecore.stackexchange.com/ or join Sitecore Slack chat. Those channels are much more suited to get help (you'll find me there but also lots of other great Sitecoreians).