Product Custom Inputs: Storefront

Product Custom Inputs in the Sylius storefront: add-to-cart form, behavior for required fields and repeated adds, display hooks with priorities and template override.

Deutsche Version

Back to overview

Product Custom Inputs: Storefront

This documentation always describes the latest published version.

Add-to-cart form

The plugin extends the Sylius add-to-cart form (CartItemType) with one field per attached custom input field, sorted by position. Each field type renders the matching form element, and the limits from the field definition act as validation. The placeholder only appears for text, multi-line text and number.

Saving: Inputs are collected on submit and only saved after Sylius has decided whether a new cart line is created or the quantity of an existing line is increased.
Adding again: If a customer adds the same variant again, it lands on the same line. The new inputs then overwrite the existing values of that line.
Required fields: A required field is only enforced on the actual add-to-cart, not on every re-render of the page (variant switch, change of another field). Otherwise an error on a field the customer has not reached yet would disable the Sylius button.

Display

A single Twig function provides the values for every place, so formatting lives in one spot:

{% for input in mmd_order_item_custom_input_values(item) %}
    {{ input.label }}: {{ input.value }}
{% endfor %}

It returns a list of label and value. A checkbox appears as a translated "Yes" or "No", a select value as its configured label (the raw stored value if the option has since been removed). Dates and times appear as stored, without adapting to the locale.

Place	Hook	Priority
Product page (input fields)	`sylius_shop.product.show.content.info.summary.add_to_cart`	50
Cart page (head, rows)	`sylius_shop.cart.index.content.form.sections.general.items.head` and `.body`	250
Checkout sidebar	`sylius_shop.checkout.common.sidebar.summary.items.item`	150
Order summary (checkout completion and customer account)	`sylius_shop.shared.order.show.summary.table.header` and `.body`	250
Admin order view	`sylius_admin.order.show.content.sections.items.head` and `.body`	-50

The order summary hook is used by both the checkout completion step and the order history in the customer account.

Overriding templates

You can override every template of the plugin in your application or theme. The most important one is the input template of the product page:

templates/shop/product/show/content/info/summary/add_to_cart/custom_inputs.html.twig

When overriding, keep the error-aware data-model handling. It makes a field with an error re-render on every change, so the button unlocks once the input is correct. Without it, the button stays locked after a validation error.

If a theme replaces a template that one of the hooks hangs on, the display only appears there if the theme template calls the hook itself.