Introducing placeholders in JSS apps

Current version: 21.x

A placeholder is a special component included with JSS. When added to the app's root component, or another component, this component creates a named placeholder key. You can use the named placeholder key for dynamically placing other components registered with JSS in the corresponding placeholder.

When connected to Sitecore, placeholders enable the functionality of Sitecore features, such as personalization, testing, and editors' ability to alter the page layout. The contents of placeholders are determined by how content authors and editors have structured the page layout.

When working disconnected from Sitecore, you determine the binding of components to specific placeholders through route data files.

Conceptually, a placeholder is similar to a <div/> tag with child elements, where each child is a component or a static component tree.

Placeholders can be nested: components can have placeholders on them, not just at the root. A common example of this might be a hierarchy like main (placeholder) > Tabs (component) > tabs (placeholder) > Tab (component).

JSS app development generally consists of designing a placeholder/component hierarchy and then implementing each component. Each framework-specific JSS implements this architecture in a slightly different idiomatic way.

Consider the following example:

  • In a file app.js:

    RequestResponse
    <div>
      <placeholder name="jss-content" />
    </div>
  • In a component definition file, such as HelloWorld.js

    RequestResponse
    <div>hello world!</div>
  • In a layout definition specified in a route data file, data/routes/en.yml:

    RequestResponse
    placeholders:
        jss-content:
        - componentName: HelloWorld
        - componentName: HelloWorld

Such code results in the following output:

RequestResponse
<div>
    <div>hello world!</div>
    <div>hello world!</div>
</div>

Placeholder naming considerations

Choosing meaningful placeholder names can enhance the maintainability of any JSS app.

Consider the names of placeholders carefully when assigning them, and follow these best practices:

  • Prefix placeholder names with an app-specific prefix. For example, instead of content, use myapp-content. This is important because a Sitecore instance can host multiple JSS apps and websites, and it is best to avoid conflicting placeholder names.

  • Choose a name that describes the general purpose of the placeholder and avoid jargon.

  • Assign a user-friendly display name for each placeholder in /sitecore/definitions/placeholders.sitecore.js. Only using a placeholder on a route is enough to register it. However, adding a display name gives your app a nice feel for authors. Display names do not need to be unique.

Varying root placeholders by page template

Sometimes, it might be necessary to render different root placeholders depending on the page type.

Because components can return different elements conditionally, this can be achieved easily by returning different components based on the value of props.layoutData.sitecore.route.templateName or props.layoutData.sitecore.route.templateId.

Working with placeholders in JSS apps

Every sample application for JavaScript frameworks supported by JSS has the necessary infrastructure for working with placeholders.

Depending on which framework you work with, refer to one of the following topics:

Do you have some feedback for us?

If you have suggestions for improving this article,