Skip to main content
The product detail handler extension customizes the product detail page (PDP). It formats PDP data and controls product actions through callbacks. You can use it to:
  • 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 the ProductDetailHandler 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.
Callbacks can be synchronous or asynchronous. The app waits up to 3 seconds for an async callback, then treats it as failed. Callbacks that return 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

Use onFormat to change product information before it is displayed. Keep onFormat for display formatting and put behavior in the action callbacks.
The 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:
Media cannot be reordered, hidden, or added. 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. Return false 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 includes product, 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 a ProductEventArgs.

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:
Read the action data from event.data:

Product detail context

The factory receives this context when the handler is created:
  • product and selectedProductVariant are set only when available.
  • Use requestVariantSelection to ask the user to select a variant, or selectVariant and selectOption to select one yourself.
  • Use the variant availability methods to mark variants as available or unavailable, keyed by variant ID.
  • Use setAttributes and removeAttributes to 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.