Product Details initialization

The Product Details initializer configures how product information is displayed and managed, including images, descriptions, pricing, and options. Use initialization to customize product data models and enhance product presentation.

Version: 1.3.5

Configuration options

The following table describes the configuration options available for the Product Details initializer:

Parameter	Type	Req?	Description
langDefinitions	LangDefinitions	No	Language definitions for internationalization (i18n). Override dictionary keys for localization or branding.
models	Record<string, any>	No	Custom data models for type transformations. Extend or modify default models with custom fields and transformers.
scope	string	No	Defines the store view scope for product data retrieval. Used in multi-store setups to fetch store-specific product information.
defaultLocale	string	No	Sets the default locale for product content when no specific locale is detected.
globalLocale	string	No	Overrides locale detection and forces all product content to use this specific locale regardless of user settings.
sku	string	No	Pre-loads a specific product SKU on initialization. Useful for server-side rendering or direct product page access.
acdl	boolean	No	Configuration for Adobe Client Data Layer (ACDL) integration to track product view events and user interactions for analytics.
anchors	string[]	No	Controls hash navigation behavior for product page sections (e.g., #reviews, #specifications). Enables deep linking to specific content areas.
persistURLParams	boolean	No	Determines which URL query parameters should persist when navigating between product variants. Useful for tracking campaigns or referral sources.
preselectFirstOption	boolean	No	When `true`, automatically selects the first available option for each configurable attribute. Streamlines selection for products with default variants.
optionsUIDs	string[]	No	Pre-selects specific product options by their unique identifiers. Useful for direct links to configured product variants (e.g., specific `size/color` combinations).

Default configuration

The initializer runs with these defaults when no configuration is provided:

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-pdp';

// All configuration options are optional
await initializers.mountImmediately(initialize, {
  langDefinitions: {}, // Uses built-in English strings
  models: {}, // Uses default data models
  // Drop-in-specific defaults:
  // scope: undefined // See configuration options below
  // defaultLocale: undefined // See configuration options below
  // globalLocale: undefined // See configuration options below
  // sku: undefined // See configuration options below
  // acdl: undefined // See configuration options below
  // anchors: undefined // See configuration options below
  // persistURLParams: undefined // See configuration options below
  // preselectFirstOption: undefined // See configuration options below
  // optionsUIDs: undefined // See configuration options below
});

Language definitions

Override dictionary keys for localization or branding. The langDefinitions object maps locale keys to custom strings that override default text for the drop-in.

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-pdp';

const customStrings = {
  'AddToCart': 'Add to Bag',
  'Checkout': 'Complete Purchase',
  'Price': 'Cost',
};

const langDefinitions = {
  default: customStrings,
};

await initializers.mountImmediately(initialize, { langDefinitions });

Tip

For complete dictionary customization including all available keys and multi-language support, see the Product Details Dictionary page.

Customizing data models

Extend or transform data models by providing custom transformer functions. Use the models option to add custom fields or modify existing data structures returned from the backend.

Model properties

Each model in the models configuration object supports the following properties:

Property	Type	Description
initialData	any	Provides initial data for the model before backend data is fetched.
transformer	(data?: ProductModel) => ProductModel	Transforms product data returned from GraphQL. Use this to add custom fields or modify existing data structures.
transform	(data?: ProductModel) => ProductModel	Deprecated. Use transformer instead.
fallbackData	(parentProduct: any, simpleProduct: ProductModel) => ProductModel	Provides fallback data when a simple product variant is selected from a configurable parent product.

The following example shows how to customize a model for the Product Details drop-in:

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-pdp';

const models = {
  ProductModel: {
    transformer: (data) => ({
      ...data,
      customField: data?.custom_field,
      promotionBadge: data?.promotion?.label,
      displayPrice: data?.price?.value ? `${data.price.value}` : 'N/A',
    }),
  },
};

await initializers.mountImmediately(initialize, { models });

Drop-in configuration

The Product Details initializer configures how product information is displayed and managed, including images, descriptions, pricing, and options. Use initialization to customize product data models and enhance product presentation.

import { initializers } from '@dropins/tools/initializer.js';
import { initialize } from '@dropins/storefront-pdp';

await initializers.mountImmediately(initialize, {
  scope: 'value',
  langDefinitions: {},
  defaultLocale: 'value',
  globalLocale: 'value',
  sku: 'value',
  acdl: true,
  anchors: 'value',
  persistURLParams: true,
  preselectFirstOption: true,
  optionsUIDs: 'abc123',
  models: {},
});

Note

Refer to the Configuration options table for detailed descriptions of each option.

Configuration types

The following TypeScript definitions show the structure of each configuration object:

langDefinitions

Maps locale identifiers to dictionaries of key-value pairs. The default locale is used as the fallback when no specific locale matches. Each dictionary key corresponds to a text string used in the drop-in UI.

langDefinitions?: {
  [locale: string]: {
    [key: string]: string;
  };
};

models

Maps model names to objects that configure how product data is transformed. Each model can provide an initial data state, a transformer function to modify GraphQL responses, and a fallback for configurable product variants.

models?: {
  [name: string]: {
    initialData: any;
    /** @deprecated Use "transformer" instead */
    transform?: (data?: ProductModel) => ProductModel;
    transformer?: (data?: ProductModel) => ProductModel;
    fallbackData?: (parentProduct: any, simpleProduct: ProductModel) => ProductModel;
  };
};