> ## Documentation Index
> Fetch the complete documentation index at: https://docs.selektable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Product options

> Full reference for the ProductOptions object passed to Selektable.open()

# Product options

The `ProductOptions` object is the second argument to `Selektable.open()`. It provides product data and cart callbacks to the widget.

## Reference

```typescript theme={null}
interface ProductOptions {
  // Product information
  productId?: string | number;
  productTitle?: string;
  productImage?: string;
  productImages?: ProductImage[];
  productUrl?: string;

  // Product type (for cart integration)
  type?: 'simple' | 'variable' | 'grouped' | 'external';

  // Variable product data
  variations?: ProductVariation[];
  attributes?: ProductAttribute[];
  is_purchasable?: boolean;
  is_in_stock?: boolean;

  // Physical product dimensions (for AI-accurate sizing)
  dimensions?: ProductDimensions;

  // Cart callbacks
  onAddToCart?: (product, quantity, variation?) => Promise<CartResult> | CartResult | void;
  onViewCart?: () => void;
  onCheckout?: () => void;
}
```

## Product information

<ParamField path="productId" type="string | number">
  Unique identifier for the product. Used to track generations and conversions.
</ParamField>

<ParamField path="productTitle" type="string">
  Display name of the product. Shown in the widget UI.
</ParamField>

<ParamField path="productImage" type="string">
  Primary image URL used for AI generation. This is the image the AI model uses to render the product in the customer's photo.

  If not provided, the first image in `productImages` is used.

  See [Choosing the right product image](/guides/product-image) for best practices on selecting this image.
</ParamField>

<ParamField path="productImages" type="ProductImage[]">
  Array of all product images displayed in the widget.

  ```typescript theme={null}
  {
    id: number;       // Unique image ID
    src: string;      // Image URL
    alt?: string;     // Alt text
    name?: string;    // Image name
  }
  ```
</ParamField>

<ParamField path="productUrl" type="string">
  URL of the product page. Used for sharing and navigation.
</ParamField>

## Variable product data

These fields are primarily used for WooCommerce-style variable products where a single product has multiple variations (e.g., different colors/sizes).

<ParamField path="type" type="string">
  Product type. One of: `simple`, `variable`, `grouped`, `external`.
</ParamField>

<ParamField path="variations" type="array">
  Available variations for variable products.

  ```typescript theme={null}
  {
    id: number;
    attributes: Array<{
      name: string;        // e.g., "Color"
      value: string | null; // e.g., "Blue", or null for "any"
    }>;
    is_in_stock?: boolean;
  }
  ```
</ParamField>

<ParamField path="attributes" type="array">
  Product attributes that have variations.

  ```typescript theme={null}
  {
    id: number;
    name: string;          // e.g., "Color"
    taxonomy: string;      // e.g., "pa_color"
    has_variations: boolean;
    terms: Array<{
      id: number;
      name: string;        // e.g., "Blue"
      slug: string;        // e.g., "blue"
    }>;
  }
  ```
</ParamField>

<ParamField path="is_purchasable" type="boolean">
  Whether the product can be purchased. If `false`, the add-to-cart button may be hidden.
</ParamField>

<ParamField path="is_in_stock" type="boolean">
  Whether the product is in stock.
</ParamField>

## Product dimensions

Optional physical measurements that help the AI render the product at its real-world size relative to the room.

<ParamField path="dimensions" type="ProductDimensions">
  Physical dimensions of the product. When provided, the AI uses these measurements to calculate correct proportions relative to the room and other objects in the scene.

  ```typescript theme={null}
  {
    width?: number;    // Width of the product
    height?: number;   // Height of the product
    depth?: number;    // Depth of the product
    unit: 'cm' | 'in' | 'mm';  // Unit of measurement (required)
  }
  ```

  At least one dimension value (`width`, `height`, or `depth`) should be provided alongside the `unit`.
</ParamField>

```javascript theme={null}
Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg',
  dimensions: {
    width: 220,
    height: 85,
    depth: 95,
    unit: 'cm'
  }
});
```

<Tip>
  Providing dimensions is especially useful for furniture and home decor products where accurate sizing in the room visualization makes a big difference.
</Tip>

## Cart callbacks

<ParamField path="onAddToCart" type="function">
  Called when the customer clicks "Add to Cart" in the widget. See [Cart Integration](/guides/cart-integration) for details.

  **Signature:**

  ```typescript theme={null}
  (product: CartProduct, quantity: number, variation?: CartVariation[]) =>
    Promise<CartResult> | CartResult | void
  ```

  **CartProduct:**

  ```typescript theme={null}
  { id: number; title: string; price?: string; image?: string }
  ```

  **CartVariation:**

  ```typescript theme={null}
  { attribute: string; value: string }
  ```

  **CartResult:**

  ```typescript theme={null}
  { success: boolean; error?: string; cartUrl?: string }
  ```
</ParamField>

<ParamField path="onViewCart" type="function">
  Called when the customer clicks "View Cart" after a successful add-to-cart.
</ParamField>

<ParamField path="onCheckout" type="function">
  Called when the customer clicks "Checkout" after a successful add-to-cart.
</ParamField>

## Product context resolution

The widget resolves product data in this priority order:

1. **Explicit options** passed to `Selektable.open(widgetId, options)` — highest priority
2. **Data attributes** on the context element (`data-selektable-widget`)
3. **Auto-detection** from the page DOM (WooCommerce body classes, JSON-LD, variation forms, etc.)

Auto-detection works with common ecommerce page structures, including WooCommerce product pages, JSON-LD structured data, and standard product data attributes.

<Tip>
  For custom platforms, always pass product data explicitly via `Selektable.open()` options. Auto-detection is designed for WooCommerce pages.
</Tip>