salla-product-options
Renders the selectable options of a product (single and multiple choice, color, thumbnail, text, number, date and time, image and file upload, map, donation amount, digital card values and more) as fo
Renders the selectable options of a product (single and multiple choice, color, thumbnail, text, number, date and time, image and file upload, map, donation amount, digital card values and more) as form inputs, for product pages, the cart and bundles.
A theme places it inside the product form, usually next to salla-add-product-button, with the same product-id. Pass the options as JSON in options; if none are given the component loads them for product-id from the API (except on the cart page).
The inputs are named options[<optionId>], so they are submitted with the surrounding form. Options shown conditionally (visibility conditions) are hidden until their condition is met.
Required inputs use native required validation. validateAndScroll() validates and scrolls to the first invalid option, and salla-add-product-button calls it before adding to the cart.
Emits the changed DOM event and the product-options::change event on salla.event whenever a selection changes.
Use it
In HTML or JSX, use the tag <salla-product-options> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).
import { SallaProductOptions } from '@salla.sa/twilight-components-react/product-options';Client-only. On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.
Example
import { SallaProductOptions } from '@salla.sa/twilight-components-react/product-options';
import { SallaAddProductButton } from '@salla.sa/twilight-components-react/add-product-button';
export function Example() {
return (
<form className="product-form">
<SallaProductOptions productId="123456" options='[{"id":1,"name":"Size","type":"single-option","required":true,"details":[{"id":11,"name":"M"},{"id":12,"name":"L"}]}]' productAvailable />
<SallaAddProductButton productId="123456" />
</form>
);
}Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
bundleContext | bundle-context | Bundle context for options of a product inside a bundle. When provided, form inputs use the bundle naming convention (bundle[sectionId][index][options][optionId]) instead of options[optionId]. Expected shape: { sectionId: string | number, sectionIndex: number, productId: string | number }, as a JSON string or an object. | object | string | |
config | config | Configuration for customizing the display layout of product options. The config prop accepts a JSON string that specifies the layout type for rendering options. It allows customization of how single-option and multiple-option selections are displayed. Example Usage: html <salla-product-options options="{{ product.options }}" product-id="{{ product.id }}" unique-key="abc123" config='{ "single-option": { "type": "button" }, "multiple-option": { "type": "button" } }'> </salla-product-options> Example Config JSON: json { "single-option": { "type": "button" }, "multiple-option": { "type": "default" } } - single-option: - Defines the display style for single-option selections. - type: Supported values: - "button": Displays options in a button-style grid layout. - "default": Displays options as a dropdown (default). - multiple-option: - Defines the display style for multiple-option selections. - type: Supported values: - "button": Displays options in a button-style grid layout. - "default": Displays options as a list of checkboxes (default). | string | |
hideOutLabel | hide-out-label | When set (any non-empty value), the "out of stock" text is not appended to out-of-stock choices. Used for live validation such as the cart page and inline checkout. | string | |
noPadding | no-padding | When true, removes the wrapper's padding (keeps the background, rounded corners and margin). Used by callers that need the options to sit flush inside their own surface. | boolean | false |
options | options | The product's options as a JSON string (or an array when set from JavaScript). Each option is { id, name, type, required, placeholder, details?: [{ id, name, additional_price, is_selected, is_out, ... }], visibility_condition?, ... }. type is one of single-option, multiple-options, color, thumbnail, text, textarea, number, date, datetime, time, image, file, map, donation, digital-code-value, country, radio, checkbox, color_picker, booking or splitter. | string | |
productAvailable | product-available | Whether the product is available at the parent level (quantity > 0, or unlimited). Controls the unlimited-product fallback in computeAvailabilityMap: only when true is a detail with all-false SKUs treated as available (placeholder/incomplete data). The API path derives this automatically from is_out_of_stock. When options are supplied via the options prop, callers must set product-available explicitly. It defaults to false so genuinely out-of-stock products are never silently promoted to available. (Truly unlimited products with no SKU data are handled separately and don't need this.) | boolean | false |
productId | product-id | The id of the product the options belong to. Defaults to the current page id (page.id). It is used to load the options from the API when options is not given, and is included in the changed event data. | number | string | salla.config.get('page.id') |
uniqueKey | unique-key | A unique key used to generate distinct identifiers. This key is appended to a default value to ensure uniqueness across instances or components where differentiation is required. | string |
Events
Listen with addEventListener, or the on prop of the React wrapper (for example onModalBack).
| Event | Description | Detail |
|---|---|---|
changed | Fires when an option value changes. event.detail is { event, option, detail, productId }: the original input event, the changed option object, the chosen detail object (for options with choices, otherwise null) and the product id. The same data is also emitted as product-options::change on salla.event. | any |
Methods
Call these on the element or a React ref.
enableUserInitiatedValidation() => Promise<void>
Turns on user-initiated validation, so invalid options scroll into view when validation fails. Resolves with no value.
enterCartMode() => Promise<void>
Switches the component to cart-item mode: fills the selected options, enables disabling of out-of-stock choices, and skips the product price update for pre-selected options. Used by themes when treating a product page as a cart item editor. Resolves with no value.
getOption(option_id: any) => Promise<Option>
Finds one option by its id.
| Parameter | Type | Description |
|---|---|---|
option_id | any | The option id, compared with strict equality, so pass a number if the option ids are numbers. |
Returns Promise<Option>: A Promise that resolves to the option object, or undefined if there is none with that id.
getOptionsData() => Promise<Option[]>
Returns the current options data, including the selected values and details.
Returns Promise<Option[]>: A Promise that resolves to the array of option objects.
getSelectedOptions() => Promise<any[]>
Returns the currently selected options.
Returns Promise<any[]>: A Promise that resolves to an array of the selected option objects.
getSelectedOptionsData() => Promise<{}>
Reads the current form values of the options.
Returns Promise<{}>: A Promise that resolves to an object that maps each option id to its selected value, for example { "1": "11" }.
hasOutOfStockOption() => Promise<boolean>
Checks whether any selected option choice is out of stock.
Returns Promise<boolean>: A Promise that resolves to a truthy value when an out-of-stock choice is selected (or every selected variant is out of stock), and a falsy value otherwise.
reportValidity() => Promise<boolean>
Runs native validation on every required, visible, enabled input and shows the browser's validation messages.
Returns Promise<boolean>: A Promise that resolves to true if all of them are valid and false otherwise.
seedSelectedOptions() => Promise<void>
Seed selectedOptions from API defaults (is_selected: true).
componentWillLoad does this only on the cart page; non-cart callers
(e.g. order-options modal) call this after mount to avoid the first
multi-select toggle wiping the pre-selected defaults. Resolves with no value.
setOptionsData(optionsData: Option[]) => Promise<void>
Replaces the options data with the given list, resets the out-of-stock tracking and re-renders. Resolves with no value.
| Parameter | Type | Description |
|---|---|---|
optionsData | Option[] | Array of product option objects, in the same shape as the options prop. |
validateAndScroll() => Promise<boolean>
Turns on user-initiated validation and validates the options, scrolling to the first invalid one.
Returns Promise<boolean>: A Promise that resolves to true if all required options are valid and false otherwise.
Related
Renders: <salla-booking-field>, <salla-conditional-fields>, <salla-progress-bar>, <salla-file-upload>, <salla-map>, <salla-color-picker>, <salla-datetime-picker>.
Used inside: <salla-multiple-bundle-product-cart>, <salla-multiple-bundle-product-options-modal>, <salla-order-edit>, <salla-order-edit-item>, <salla-order-options-modal>.