Product options
The ProductOptions object is the second argument to Selektable.open(). It provides product data and cart callbacks to the widget.
Reference
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;
}
Unique identifier for the product. Used to track generations and conversions.
Display name of the product. Shown in the widget UI.
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 for best practices on selecting this image. Array of all product images displayed in the widget.{
id: number; // Unique image ID
src: string; // Image URL
alt?: string; // Alt text
name?: string; // Image name
}
URL of the product page. Used for sharing and navigation.
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).
Product type. One of: simple, variable, grouped, external.
Available variations for variable products.{
id: number;
attributes: Array<{
name: string; // e.g., "Color"
value: string | null; // e.g., "Blue", or null for "any"
}>;
is_in_stock?: boolean;
}
Product attributes that have variations.{
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"
}>;
}
Whether the product can be purchased. If false, the add-to-cart button may be hidden.
Whether the product is in stock.
Product dimensions
Optional physical measurements that help the AI render the product at its real-world size relative to the room.
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.{
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)
}
width, height, or depth) should be provided alongside the unit. 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'
}
});
Providing dimensions is especially useful for furniture and home decor products where accurate sizing in the room visualization makes a big difference.
Cart callbacks
Called when the customer clicks “Add to Cart” in the widget. See Cart Integration for details.Signature:(product: CartProduct, quantity: number, variation?: CartVariation[]) =>
Promise<CartResult> | CartResult | void
{ id: number; title: string; price?: string; image?: string }
{ attribute: string; value: string }
{ success: boolean; error?: string; cartUrl?: string }
Called when the customer clicks “View Cart” after a successful add-to-cart.
Called when the customer clicks “Checkout” after a successful add-to-cart.
Product context resolution
The widget resolves product data in this priority order:
- Explicit options passed to
Selektable.open(widgetId, options) — highest priority
- Data attributes on the context element (
data-selektable-widget)
- 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.
For custom platforms, always pass product data explicitly via Selektable.open() options. Auto-detection is designed for WooCommerce pages.
