Presets
Presets are reusable component templates that you define once and reference across multiple views. They work like a view in structure - built from the same components and configuration - but instead of being tied to a specific URL path, they are standalone building blocks you can embed wherever you need them.
The main benefit is avoiding duplication. If the same component structure appears in several views - a teaser card, a menu entry, a content list - you can extract it into a preset and reference it from each view instead of maintaining identical configurations in multiple places.
Presets support props: named placeholders that the referencing view fills with concrete values. Inside the preset, you reference a prop value with `$props.{key}`. This makes presets flexible - one template can serve many contexts by receiving different values each time it is used.
Presets replace the older EmbeddedViews feature and are available from PXP 4.0 / Purple Builder 0.18 as part of the split `views.json` system
Create presets
To use presets, you'll need to migrate to the split views.json (see View configuration ).
Preset files live in `default/storefront/assets/presets/`. This folder is created automatically during migration.
Inside the `presets` folder, create JSON files with descriptive names - for example `teaser-card.json` or `menu-entry.json`. There are no naming restrictions beyond using valid file names.
A preset file uses the same component and configuration structure as a view. The key difference is the **props definition**: you declare the keys that the referencing view is expected to provide.
To define a prop, add it to the props configuration of the preset root. Inside the preset, reference the value anywhere using `$props.{key}`.
Add a preset to a view
Once a preset file exists in the `presets` folder, the node type Preset Reference becomes available in the view editor.
To add a preset to a view:
- Open the view you want to edit.
- Add a Preset Reference node at the desired position in the component tree.
- Select the preset to use from the dropdown.
- Fill in the preset props attribute with the values the preset expects.
Changes to a preset's structure can affect the schema of any view that references it. Review referencing views after editing a preset. Also note that excluding any of the files of the view structure through master/brand deployment can cause invalid configurations.
The preset is rendered inline at the position of the Preset Reference node. No wrapper element is added, which keeps the DOM lean. You may review the final structure of the view in views.json.
Passing data with props
Props are the mechanism for making a preset context-aware. Each prop is a key that the referencing view fills with a value - either a static string or a dynamic data binding.
Where | Syntax |
|---|---|
Define a prop key in the preset | Add key to props object |
Reference a prop value inside the preset | $props.{key} |
Pass a value from the view | Set value in the preset props attribute of the Preset Reference node |
Props currently support flat key-value pairs. Passing complex nested objects as a single prop is not supported. If you need to access deeply nested data, extract the required values individually using separate props or a helper function in custom.server.js.
Conditional use
Presets do not support a condition setting at the reference level. If you need to show or hide a preset based on a condition, either:
- Place the condition inside the preset on the top-level component, or
- Wrap the Preset Reference node in a conditional section in the view.
The second approach adds an extra wrapper element to the DOM. Where possible, prefer moving the condition into the preset itself.
Limitations
Limitation | Detail |
|---|---|
No recursion | A preset cannot reference itself or another preset that references it. Multi-level structures (e.g. nested menus) must be handled by creating separate presets for each level. |
No conditionals at reference level | Conditions must be placed inside the preset or the Preset Reference node must be wrapped in a conditional section in the view. |
Flat props only | $props.object.key does not resolve. Pass individual scalar values as separate props, or use a custom.server.js helper to extract deeply nested values before passing them. |
FAQ
Can I use a preset inside another preset? No. Preset references inside presets are not supported. If you need to compose reusable structures, build them as self-contained presets and reference each one independently from the view.
What happens if a preset is excluded from a master or brand deployment? Excluding preset files from a deployment can result in invalid configurations in the views that reference them. Make sure preset files are included in any deployment that also includes views that reference them.
Do presets work on the web experience? Yes, presets are part of the view configuration system and apply to both app and web experiences.
Are presets the same as EmbeddedViews? Presets are the replacement for EmbeddedViews, which are deprecated. If your experience still uses EmbeddedViews, migrate to the split views.json system and recreate those components as presets.
What is the future of presets? Presets are an intermediate solution. The upcoming Component Library feature will provide a more capable, composable alternative. No new capabilities (recursion, reference-level conditionals) are planned for presets before that transition.