Recommendations: Extending SXA

You might want to extend SXA, for example, to add your own custom rendering to the SXA toolbox or a template. This topic describes some requirements and recommendations for extending SXA.

Never put custom items in SXA-controlled branches of the tree

When extending SXA, think about where to store your custom items. SXA overwrites the standard SXA sections during SXA updates. Therefore, placing custom items in tree branches controlled by SXA can result in your instance being broken after an upgrade. We recommend that you:

  • Place custom modules in a branch that is a sibling to the Headless Experience Accelerator module root.

  • Place templates in folders that are siblings to the Experience Accelerator folder – never inside.

  • Similarly, you must create a module-specific root item for all other areas, such as Renderings, Branches, Media.

Related topics:

Do not modify OOTB SXA items

When extending SXA, always use the SXA extension points for custom functionality. For example, create a custom data template. If this is not possible and you have a good reason for the extension, contact the SXA team to create the extension point for you.

Related topics:

Create an SXA module for your custom renderings

Place custom renderings in an SXA module that can be added to an existing site or used immediately in newly created sites. 

You must:

Related topics:

Base your custom templates for pages on the Page template

When you create a custom template that represents a page, you must select the Page template as your base template. Otherwise, certain functionality might not work.

Item ID: Page: {3F8A6A5D-7B1A-4566-8CD4-0A50F3030BD8}.

Item path: sitecore/Templates/Foundation/Experience Accelerator/Multisite/Content/Page.

Consider using existing renderings before building a new one

Check out the flowchart to help decide whether you need to create a custom component.

You can customize existing SXA renderings by using rendering variants. If possible, always consider using variants before building a custom rendering.

Related topics:

Limit scope of fields linking to items

For fields that support queries, you must limit the scope of items that editors can choose from. 

For example, use:

  • query:$siteMedia – for file or image fields.

  • query:$home – for fields that link to pages.

  • query:$site – for fields that can link to any item within your site.

The description of the SXA pipelines includes a complete list of tokens and how to extend them.

Do you have some feedback for us?

If you have suggestions for improving this article,