Introducing placeholders in JSS apps
Describes placeholders in JSS apps and naming best practices
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
<div> <placeholder name="jss-content" /> </div>
In a component definition file, such as
In a layout definition specified in a route data file,
placeholders: jss-content: - componentName: HelloWorld - componentName: HelloWorld
Such code results in the following output:
<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
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
Working with placeholders in JSS apps
Depending on which framework you work with, refer to one of the following topics: