# salla-product-options (https://docs.salla.dev/twilight/react/web-components/salla-product-options)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

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 [#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).

```tsx
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 [#example]

```tsx
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>
  );
}
```

```html
<form class="product-form">
  <salla-product-options product-id="123456" options='[{"id":1,"name":"Size","type":"single-option","required":true,"details":[{"id":11,"name":"M"},{"id":12,"name":"L"}]}]' product-available></salla-product-options>
  <salla-add-product-button product-id="123456"></salla-add-product-button>
</form>
```

## Properties [#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 [#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 [#methods]

Call these on the element or a React ref.

### `enableUserInitiatedValidation() => Promise<void>` [#enableuserinitiatedvalidation--promisevoid]

Turns on user-initiated validation, so invalid options scroll into view when validation fails. Resolves with no value.

### `enterCartMode() => Promise<void>` [#entercartmode--promisevoid]

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>` [#getoptionoption_id-any--promiseoption]

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[]>` [#getoptionsdata--promiseoption]

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[]>` [#getselectedoptions--promiseany]

Returns the currently selected options.

Returns `Promise<any[]>`: A Promise that resolves to an array of the selected option objects.

### `getSelectedOptionsData() => Promise<{}>` [#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>` [#hasoutofstockoption--promiseboolean]

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>` [#reportvalidity--promiseboolean]

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>` [#seedselectedoptions--promisevoid]

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>` [#setoptionsdataoptionsdata-option--promisevoid]

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>` [#validateandscroll--promiseboolean]

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 [#related]

Renders: [`<salla-booking-field>`](https://docs.salla.dev/twilight/react/web-components/salla-booking-field), [`<salla-conditional-fields>`](https://docs.salla.dev/twilight/react/web-components/salla-conditional-fields), [`<salla-progress-bar>`](https://docs.salla.dev/twilight/react/web-components/salla-progress-bar), [`<salla-file-upload>`](https://docs.salla.dev/twilight/react/web-components/salla-file-upload), [`<salla-map>`](https://docs.salla.dev/twilight/react/web-components/salla-map), [`<salla-color-picker>`](https://docs.salla.dev/twilight/react/web-components/salla-color-picker), [`<salla-datetime-picker>`](https://docs.salla.dev/twilight/react/web-components/salla-datetime-picker).

Used inside: [`<salla-multiple-bundle-product-cart>`](https://docs.salla.dev/twilight/react/web-components/salla-multiple-bundle-product-cart), [`<salla-multiple-bundle-product-options-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-multiple-bundle-product-options-modal), [`<salla-order-edit>`](https://docs.salla.dev/twilight/react/web-components/salla-order-edit), [`<salla-order-edit-item>`](https://docs.salla.dev/twilight/react/web-components/salla-order-edit-item), [`<salla-order-options-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-order-options-modal).