# Step-by-Step Product Configurator: complete guide > Overview The Step-by-Step Product Configurator adds a guided flow to the product page: the customer picks options (size, medium, color, frame…), types a text, uploads a file, and the price… - Page: - Language: en - Last updated: 2026-10-11 - Other languages: [fr](https://www.datafirefly.com/documentation/dfproductconfigurator/index.md), [es](https://www.datafirefly.com/es/documentation/dfproductconfigurator/index.md), [de](https://www.datafirefly.com/de/documentation/dfproductconfigurator/index.md), [it](https://www.datafirefly.com/it/documentation/dfproductconfigurator/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfproductconfigurator/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfproductconfigurator/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfproductconfigurator/index.md) - Index: ## Overview The Step-by-Step Product Configurator adds a guided flow to the product page: the customer picks options (size, medium, color, frame…), types a text, uploads a file, and the price updates with every choice. The surcharge is calculated server-side and carried by a native PrestaShop customization, so it follows the cart, the order and the invoice. The module is a strong alternative to combinations when a product mixes many options: no combination is created, each option carries its own price and weight, and one configurator can serve a whole catalog. - **Configurator**: a set of fields, linked to one or more products and, if needed, to categories. - **Field**: one step of the flow (dropdown, radio buttons, swatches, thumbnails, text, upload…). - **Option**: a choice offered in a field, with its price, weight, reference and visual. ## Installation and updates 1. In the back office, open **Modules → Module Manager → Upload a module** and upload the module ZIP. 2. Click **Configure** to reach the display settings and the demo data. 3. Configurators are managed in **Modules → Product configurators**. Compatibility: PrestaShop 1.7.7 to 9.x, PHP 7.1 and above (depending on the PrestaShop version). The module uses neither Composer nor jQuery and requires no theme change. To update, simply upload the new ZIP. The database schema, hooks and caches are updated automatically, even when the files were copied by hand without the module manager. Existing configurators are kept. ## Display settings The module's **Configure** page holds the settings shared by all configurators: - **Display mode**: block embedded in the product page (recommended with a page builder), a "Configure" button opening a full-screen popup, or full replacement of the product page. - **Placement**: automatic (the theme's `displayProductAdditionalInfo` hook) or manual (you place the configurator yourself, see the Creative Elements section). - **Hide the theme's native add-to-cart button**: prevents adding to cart without going through the configurator. - **Quantity selector in the configurator**: in embedded mode, shows the quantity next to the configurator's "Add to cart" button and hides the theme one. - **Show the configurator name and description**: turn off when the product title and text are already handled by the theme or the page builder. - **Show the steps bar** and **Number the steps**: the row of pills above the fields and the numbers before each title can be hidden separately. - **After adding to cart**: popup with the customization details, the theme's native popup (`ps_shoppingcart` cart module), or a simple message below the button. ## Creating a configurator In **Modules → Product configurators**, click **New configurator**. From a product page in the back office (legacy product page), the "Create a configurator for this product" button pre-fills the product. ### Linked products and categories - **Linked products**: type a name, reference or ID, then click the result. Add as many products as needed; the cross on a chip removes the product. - **Linked categories**: tick the categories whose products should all get the configurator. The filter above the list finds a category by name. The **Include subcategories** option extends the link to the whole tree. Each product keeps its own base price. If a product is linked to several active configurators, the direct product link wins over the category link, then the oldest configurator. A warning lists the products concerned. ### General settings - **Internal name (optional)**: helps you find the configurator in the list. Left empty, it takes the name of the first linked product. It is shown on the product page only if the matching setting is on. - **Active**: an inactive configurator appears on no product. - **Block add to cart if invalid**: the "Add to cart" button stays disabled while a required field is empty. - **Price mode**: product price + options (general case), or custom base price + options. ## Fields Click **Add a field**, choose its type, enter its label in each language (language selector at the top of the form) and tick **Required** if needed. A help text can be shown under the title. ### Field types - **Dropdown**, **Radio buttons**, **Color swatches**, **Image thumbnails**: one choice among options. - **Checkboxes**: several choices allowed (finishes, gift wrap…). - **Text field**, **Text area**, **Number**, **Date**, **File upload**: free input. A single "carrier" option then defines the price (for example €0.20 per character). ### Options Each option has a multilingual label, a price impact and its type (fixed amount, percentage of the base price, per character, per unit, formula), a color for swatches, a thumbnail for image thumbnails, a **weight** in kg, a **reference**, the "default" state and availability. An unavailable option stays visible but greyed out. ### Reordering fields and options Drag a field by its handle to change the step order; the **Collapse all** button makes this easier on a long configurator. Options are reordered the same way with their handle. The order is saved with the configurator. ### Show only if… A field can appear only when a specific option of another field is chosen. Example: the "Frame" field only shows when "Framed Print" is chosen in "Type". In the **Show only if…** block, select the trigger option or options (Ctrl or Cmd + click to pick several: the field shows if any of them is chosen). No selection: the field is always shown. Chained dependencies are handled: if a trigger field is hidden, the fields depending on it are hidden too. A hidden field is ignored in the price and the order, even if it is required. Only saved options appear in the list. After creating new options, save the configurator once, then set the conditions. ### Information link (window) Each field can show, to the right of its title, a link such as "Material Guide" or "Size Guide". Clicking it opens a window over the page. - **Link text**: the label shown, in each language. Empty: no link. - **Window content**: HTML (text, table, images) and the `{hook …}` and `{widget …}` tags, executed as in the Creative Elements Shortcode widget. For a rich layout, design the window as a saved template in Creative Elements and paste its shortcode. Scripts and iframes are rejected on save for security reasons: a warning says so and the previous content is kept. ## Price and weight Impacts are entered **tax excluded** in the default currency. The product page shows the base price, the options total and the tax-included total, updated with every choice. That total is only a display: the real price is recalculated server-side from the customer's choices, then carried by the native PrestaShop customization. Changing the page or requests in the browser does not change the invoiced price. The **weight** of the chosen options is added to the cart weight by PrestaShop. Your carriers' weight ranges therefore apply as usual, and option prices count in the total used for the free-shipping threshold. For shipping costs that depend on size, give each format a real or volumetric weight (for example 40 × 60 framed = 2.5 kg). Carrier dimension limits only read the product's own dimensions, not the chosen options. ## Visual preview (optional) In the configurator's **Visual preview** block, enable the preview and upload a background image (transparent PNG recommended). Each field can then place an image layer, tint the silhouette or show the customer's text inside a zone you draw with the mouse. The customer can choose the font, size and color of their text, and colors can be linked to another field. On add to cart, the final visual is composed and saved with the order. Preview off: no preview is shown, the theme or page builder images are never modified, and the fields' preview settings are hidden in the editor (they stay saved if you turn the preview back on). ## Creative Elements and page builders 1. In the module settings, choose the **Embedded** mode and the **Manual** placement. 2. Turn off the preview in the configurator: the product page images stay those of the page builder. 3. In the Creative Elements product page template, add a **Modules** widget, choose the DataFirefly Configurator module and enter the hook `displayDfProductConfigurator`. You can also use a **Shortcode** widget with `{hook h='displayDfProductConfigurator'}`. 4. Place this widget where you want it, for example under the title and price. On products without a configurator, the widget shows nothing. 5. If needed, turn off step numbering, the steps bar and the configurator name, then enable the built-in quantity selector if the Creative Elements "Add to cart" widget is not on the page. In a theme, the same hook is called with `{hook h='displayDfProductConfigurator' product=$product}`. The configurator is rendered only once per page. ## After adding to cart With the default setting, a popup opens: product image, unit price, details of each choice (for example Type: Framed Print, Size: 40 × 60 cm, Frame: Walnut), quantity, then the number of items, subtotal, shipping and cart total, with the **Continue shopping** and **Proceed to checkout** buttons. The `views/templates/front/cart_modal.tpl` template can be overridden in the theme. The "Theme native popup" setting uses the cart module's popup; it does not show the customization details. The "Message" setting shows a link to the cart below the button. ## Cart, order and production Each validated configuration creates a native PrestaShop customization: two different configurations give two separate cart lines. The readable summary (Size: 40 × 60 cm · Type: Framed Print · Frame: Walnut) appears in the cart, the order, the invoice and the back office. The back-office order detail shows a **Customizations** panel with the field-by-field summary, the files sent by the customer and, if the preview is on, the final visual. On the Classic theme, a quantity change reloads part of the product page via AJAX: the configurator stays in place and keeps the customer's choices. ## Duplicating a configurator In the list, open the row menu and click **Duplicate** (the button also exists at the bottom of the editor). The copy takes the settings, fields, options, translations and images. "Show only if…" conditions and linked colors are rewired to the copied fields. The copy is created **inactive and with no linked product or category**, so it does not take over from the original: link your products, then activate it. ## Demo data The **Configure** page offers three imports, which can be run again without duplicates: - **Mug, vase, t-shirt**: composed preview, engraved text, colors depending on the shape, price formula, upload. - **Embroidery (patch and beanie)**: colors linked across several elements. - **Photo art (wall art)**: preview off, "Material Guide" link, sizes with weights, medium as thumbnails, customer photo, background color, frame shown only for a framed print. ## Troubleshooting ### The configurator does not show - Check that the configurator is **active** and linked to the product, directly or through a category. - With manual placement, check that the `displayDfProductConfigurator` hook is placed in the product page template. - With automatic placement, check that the theme calls `displayProductAdditionalInfo` (the Classic theme does). - Clear the cache (**Advanced Parameters → Performance**). ### An option is missing from "Show only if…" It is not saved yet. Save the configurator, then come back to the field. ### The information link does not show Both the link text and the window content must be filled in for the displayed language. ### The "Add to cart" button stays greyed out A visible required field is empty: the message under the total says which one. Turn off "Block add to cart if invalid" to keep the button active and show the errors on click. ### Shipping costs do not change with the options Check that the options carry a weight and that the carrier bills by weight (not by price). ## Version history - **1.3.0**: PrestaShop 1.7.7 and 1.7.8, several products and categories per configurator, duplication, conditions picked from a list of options, information links in a window, dedicated hook for page builders, cart popup, display settings, drag-and-drop, photo art demo. - **1.2.1**: preview identical to the final visual, translated front-end messages, zone editor with the right proportions. - **1.2.0**: linked colors, visual recoloring, one-click demos, always-visible preview. - **1.1.0**: font, size and color chosen by the customer, mouse-driven placement zones, final visual and order panel, three display modes. - **1.0.0**: initial release.