Product Detail Handler Extension

The Product Detail Handler Extension lets you customize behavior on the product detail page. Use this extension when you want to format PDP data or control product actions through callbacks. You can use it to:

Change product information before it is shown.
Add, remove, or replace product tags.
Change the displayed title, vendor, SKU, stamp image, or availability.
React when the selected product or variant changes.
React when the user adds a product to the cart.
React when the user clicks product, quick add, collection, vendor, or external navigation actions.
Cancel supported default actions by returning false.

Handler Shape

The extension is based on the ProductDetailHandler type from @napps/component-extension.

import type { ProductDetailHandler } from "@napps/component-extension";

export const handler: ProductDetailHandler = {
  onFormat(draft) {
    draft.setTitle("Custom title");
  },

  onAddedToCart(event) {
    if (event.data.quantity <= 0) {
      return false;
    }

    return true;
  }
};

Callbacks can be synchronous or asynchronous. If the callback is async, the app will only wait up to 3 seconds before assuming the callback failed.

type ProductDetailHandlerEventArgReturnType =
  | void
  | boolean
  | Promise<void>
  | Promise<boolean>;

When a callback receives an event, you can return false to cancel the default action when that action supports cancellation.

Formatting PDP Data

Use onFormat to change product information before it is displayed.

onFormat?: (draft: ProductDetailInfoState) => void | Promise<void>;

The draft object lets you edit the visible PDP data:

interface ProductDetailInfoState {
  setTitle: (title: string) => void;
  setVendor: (vendor: string | null | undefined) => void;
  setSku: (sku: string | null | undefined) => void;
  setStampImage: (imageURL: string | null | undefined) => void;
  setAvailability: (availability: boolean) => void;
  clearLowStockInfo: () => void;
  getTags: () => ProductTag[];
  addTag: (tag: ProductTag) => void;
  removeTag: (tag: ProductTag) => void;
  replaceTags: (tags: ProductTag[]) => void;
  clearTags: () => void;
  removeTagByType: (type: string) => void;
}

The same draft exposes read-only gallery media and lets you attach tags to individual images and videos.

interface ProductMediaItem {
  id: string;
  alt: string;
  contentType: string;
  previewImageUrl: string | null;
  type: "image" | "video" | "external_video" | "model3d";
}

interface MediaTag {
  id: string;
  text?: string | null;
  textColor?: string | null;
  backgroundColor?: string | null;
  iconUrl?: string | null;
  iconColor?: string | null;
}

interface ProductDetailInfoState {
  mediaItems: ProductMediaItem[];
  getMediaTags(mediaID: string): MediaTag[];
  addMediaTag(mediaID: string, tag: MediaTag): void;
  setMediaTags(mediaID: string, tags: MediaTag[]): void;
  removeMediaTag(mediaID: string, tagID: string): void;
  clearMediaTags(mediaID: string): void;
  clearAllMediaTags(): void;
}

Media cannot be reordered, hidden, or added. addMediaTag replaces an existing tag with the same ID on the same media item. A tag must contain text, an icon URL, or both. onFormat runs again when the selected variant or option changes, and the entire formatting hook shares the three-second timeout. Example:

import { ProductTag, type ProductDetailHandler } from "@napps/component-extension";

export const handler: ProductDetailHandler = {
  onFormat(draft) {
    draft.setVendor("Custom vendor");
    draft.setAvailability(true);
    draft.removeTagByType("old-label");

    draft.addTag(
      new ProductTag("promo", "Promo", "#ffffff", "#0f766e")
    );
  }
};

Action Callbacks

The handler can react to PDP actions through optional callbacks.

interface ProductDetailHandler {
  onDestroyed?: () => void | Promise<void>;
  onFormat?: (draft: ProductDetailInfoState) => void | Promise<void>;
  onVariantSelected?: () => void;
  onProductSelected?: (
    event: ProductDetailEventArgs<ProductSelectedEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onAddedToCart?: (
    event: ProductDetailEventArgs<AddedToCartEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onProductClicked?: (
    event: ProductDetailEventArgs<ProductClickedEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onProductQuickAddClicked?: (
    event: ProductDetailEventArgs<ProductClickedEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onExternalNavigationRequestClicked?: (
    event: ProductDetailEventArgs<ExternalNavigationRequestEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onCollectionClicked?: (
    event: ProductDetailEventArgs<CollectionClickedEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
  onVendorClicked?: (
    event: ProductDetailEventArgs<VendorClickedEventArgs>
  ) => ProductDetailHandlerEventArgReturnType;
}

onDestroyed

Runs when the handler is destroyed. Use it to clean up work you started inside the handler.

onFormat

Runs when PDP display data can be formatted. Use it to change title, vendor, SKU, availability, stamp image, low stock information, or tags.

onVariantSelected

Runs when a variant is selected.

onProductSelected

Runs when a product is selected. The event data contains:

interface ProductSelectedEventArgs {
  product: Product;
  variant: ProductVariant | undefined;
}

onAddedToCart

Runs when a product is added to the cart. The event data contains:

interface AddedToCartEventArgs {
  product: Product;
  variant: ProductVariant;
  quantity: number;
}

onProductClicked

Runs when a product is clicked. The event data contains:

interface ProductClickedEventArgs {
  product: Product;
}

onProductQuickAddClicked

Runs when the quick add action is clicked for a product. The event data contains the clicked product.

onExternalNavigationRequestClicked

Runs when an external navigation action is clicked. The event data contains:

interface ExternalNavigationRequestEventArgs {
  title: string;
  target: string;
}

onCollectionClicked

Runs when a collection action is clicked. The event data contains:

interface CollectionClickedEventArgs {
  collection: Collection;
  title: string;
}

onVendorClicked

Runs when a vendor action is clicked. The event data contains:

interface VendorClickedEventArgs {
  vendor: string;
  title: string;
}

Event Object

Callbacks that receive an event use this shape:

interface ProductDetailEventArgs<T> {
  data: T;
}

Use event.data to read the action data. Example:

import type { ProductDetailHandler } from "@napps/component-extension";

export const handler: ProductDetailHandler = {
  onExternalNavigationRequestClicked(event) {
    if (!event.data.target.startsWith("https://")) {
      return false;
    }

    return true;
  }
};

Product Detail Context

Product detail handlers receive a context while they are created.

interface ProductDetailHandlerContext {
  productID: string;
  product?: Product;
  selectedProductVariant?: ProductVariant;
  handlingType: ProductDetailHandlingType;
  requestVariantSelection: () => Promise<ProductVariant | null>;
  selectVariant: (variantID: string) => boolean;
  selectOption: (type: string, value: string) => void;
}

The context lets you:

Read the current product ID.
Read the current product, when available.
Read the selected variant, when available.
Check how the product detail flow is being used.
Ask the user to select a variant.
Select a variant by ID.
Select an option by type and value.

The handling type can be:

enum ProductDetailHandlingType {
  PDP = "PDP",
  QuickAdd = "QuickAdd",
  Select = "Select"
}

PDP - Normal Product Detail Page
QuickAdd - Quick Add Sheet/Dialog
Select - Similar to Quick Add but with the purpose to select a variant

Creation Arguments

When a handler is created, these arguments can be provided:

interface CreateProductDetailHandlerArgs {
  identifier: string;
  packageName: string;
  productID: string;
  settings: {
    [key: string]: any;
  };
}

Use settings for configuration passed to the handler.

Best Practices

Keep callbacks fast.
Use onFormat only for display formatting.
Use action callbacks for behavior.
Return false only when you want to stop the default action.
Check optional values before using them.

​Handler Shape

​Formatting PDP Data

​Action Callbacks

​onDestroyed

​onFormat

​onVariantSelected

​onProductSelected

​onAddedToCart

​onProductClicked

​onProductQuickAddClicked

​onExternalNavigationRequestClicked

​onCollectionClicked

​onVendorClicked

​Event Object

​Product Detail Context

​Creation Arguments

​Best Practices