ProductCustomizableOptions container

The ProductCustomizableOptions container renders selectable choices and shopper-input fields for the current product’s customizable options. Supported controls include dropdown menus, radio buttons, checkboxes, text fields, multiline text fields, dates, local date-times, and times.

The container receives initial product data during initialization to preload the component. It then listens for pdp/data events in its scope to update product data and for pdp/values events to keep displayed selections in sync with the current configuration.

Note

• Rendering is conditional. The container renders when the product’s ac_customizable_options attribute has entries in selectable or shopperInput. Otherwise, it renders nothing. See ac_customizable_options for the attribute shape.
• Selecting a value adds its custom-option/<optionId>/<valueId> UID to the PDP configuration’s optionsUIDs. Deselecting the value removes it. The checkbox and multiple options support more than one selected value per option.
• Entering a value updates enteredOptions with the encoded option UID and its string value. Clearing a field removes only that option’s entry. Other entered values and selected options are preserved.
• Required options display a Required label. This container does not currently enforce required-option selection or block Add to Cart when required options are empty. It does not display a live price-delta preview. See Supported Commerce features for roadmap status.

Selectable controls

Render type	Control	Selection
drop_down	Dropdown menu	One value per option.
radio	Radio button group	One value per option.
checkbox	Checkbox group	Multiple values per option.
multiple	Checkbox group	Multiple values per option. Not a native multi-select list.

Each selected value adds its encoded selectable[].values[].id to optionsUIDs. Fixed surcharges are formatted in the product’s currency. Percentage surcharges are shown as percentages. These labels do not update the displayed product total.

Shopper-input controls

Render type	Control	Metadata
field	Text input	Positive integer range.from and range.to values specify minimum and maximum lengths.
area	Multiline text input	Same length constraints. Line breaks are preserved.
date	Date input	Local calendar date.
date_time	Local date-time input	No timezone conversion.
time	Time input	Local time.
file	Disabled file input	Displays a localized unsupported message. Upload is not implemented.

Labels indicate required options and show nonzero option prices in the product’s currency.

Invalid length limits are ignored, and a maximum of 0 means unlimited. Maximum length is enforced when shoppers enter or paste text. Minimum length is set on the input control but does not block Add to Cart. If the minimum exceeds the maximum, the minimum is ignored.

Keep the encoded shopperInput[].id unchanged when passing { uid, value } entries to the cart. Do not decode or encode it again. The container preserves whitespace and multiline text.

Date and time controls store cart-compatible strings in enteredOptions without timezone conversion:

Render type	Shopper input	Stored value
date	2026-10-02	2026-10-02 00:00:00
date_time	2026-10-02T14:30	2026-10-02 14:30:00
time	14:30	1970-01-01 14:30:00

The embedded ProductDetails container renders these controls too. Use either the standalone container or the embedded rendering path, not both on the same PDP.

ProductCustomizableOptions configurations

The ProductCustomizableOptions container provides the following configuration options:

Parameter	Type	Req?	Description
scope	string	No	Unique identifier for the PDP context. Only containers rendered with this scope will respond to product events.
initialData	ProductModel	No	Initial product data used before scoped pdp/data events arrive.
className	string	No	Additional CSS class applied to the container wrapper.

Slots

This container does not expose any customizable slots.

Usage

The following example demonstrates how to render the ProductCustomizableOptions container:

import { render as provider } from '@dropins/storefront-pdp/render.js';
import ProductCustomizableOptions from '@dropins/storefront-pdp/containers/ProductCustomizableOptions.js';

await provider.render(ProductCustomizableOptions, {
  scope: 'example', // optional
})(block);