- Change the displayed title, vendor, SKU, stamp image, low stock information, tags, or media tags.
- React when the selected product or variant changes.
- Validate or cancel an add to cart before it happens.
- React when the user clicks product, quick add, collection, vendor, or external navigation actions.
- Cancel supported default actions by returning
false.
Exported function
A product detail handler is a factory function. Expresso calls it to create a handler for each product detail flow, passing a context and the creation arguments, and uses theProductDetailHandler object it returns.
Export the factory from your entry file under the extension’s functionName in napps.config.json. See How App Extensions work. The examples on this page name it createProductDetailHandler, like the template generated by napps create-extension.
boolean | Promise<boolean> can return false to cancel the default action, if that action supports cancellation. There is no preventDefault() method on the event object.
Formatting PDP data
UseonFormat to change product information before it is displayed. Keep onFormat for display formatting and put behavior in the action callbacks.
draft object lets you edit the visible PDP data:
mediaItems is the PDP gallery in display order. You can inspect it and attach tags to individual images and videos:
addMediaTag replaces an existing tag with the same ID on the same media item, so repeated calls are safe. A tag must contain text, an icon URL, or both; a tag with neither is dropped. onFormat runs again when the selected variant or option changes, and the entire formatting hook shares the three-second timeout.
ProductTag is a runtime global. The package exports its type only, so construct it with new ProductTag(...) without importing it as a value:
Action callbacks
The handler reacts to PDP actions through optional callbacks.onFormat
Runs when PDP display data can be formatted. See Formatting PDP data.onDestroyed
Runs when the handler is destroyed. Use it to clean up work you started inside the handler.onVariantSelected
Runs when a variant is selected.onVariantsAvailability
Runs with the store availability of the product’s variants. The event data contains:onBeforeProductAddToCart
Runs before a product is added to the cart. Returnfalse to stop the add to cart. This is the only callback whose payload uses variant and carries quantity:
onProductSelected
Runs when a product is selected. The event data contains:onAddedToCart
Runs after a product is added to the cart. The event data includesproduct, productVariant, and
quantity, the increase observed after the native add operation. Returning false suppresses the
delegated native callback; it does not undo the cart addition.
onProductClicked
Runs when a product is clicked. The event data contains:onProductQuickAddClicked
Runs when the quick add action is clicked for a product. The event data is aProductEventArgs.
onExternalNavigationRequestClicked
Runs when an external navigation action is clicked. The event data contains:onCollectionClicked
Runs when a collection action is clicked. The event data contains:onVendorClicked
Runs when a vendor action is clicked. The event data contains:onPreferredStoresChanged
Runs when the user’s preferred stores change. The event data contains:Event object
Callbacks that receive an event use this shape:event.data:
Product detail context
The factory receives this context when the handler is created:productandselectedProductVariantare set only when available.- Use
requestVariantSelectionto ask the user to select a variant, orselectVariantandselectOptionto select one yourself. - Use the variant availability methods to mark variants as available or unavailable, keyed by variant ID.
- Use
setAttributesandremoveAttributesto manage key-value attributes.
handlingType tells you how the product detail flow is being used:
ProductPage: the regular product detail page.ProductQuickAdd: the quick add sheet or dialog.ProductSelection: like quick add, but used to select a variant.
Creation arguments
The factory’s second argument contains:settings holds the configuration passed to the handler.