Option Images & Swatches

Assign images to individual parameter options for visual selection in dropdowns, radio buttons, and color pickers.

What are option images?

Option images are thumbnails attached to individual parameter option values. They appear inline in the configurator controls — inside dropdowns, radio buttons, pill selectors, and color swatches. This lets customers see what each option looks like before selecting it.

Option images are different from product photos (assets). Product photos appear in the main image gallery and change based on the selected configuration. Option images appear on the form controls themselves.

Where option images appear

Dropdown (select)

A small thumbnail appears next to each option in the dropdown list, and next to the selected value in the trigger button.

Radio buttons (all styles)

Thumbnails appear inline within button-group, pill, and card radio styles. In the image-cards style, the image fills the card area.

Color swatches

When an option has an image, it replaces the solid color circle with the image. This is ideal for textures, patterns, and material finishes that can't be represented by a flat color.

Assigning images manually

In the visual parameter editor, each option chip has a small image icon on the left:

  • No image yet: Click the dashed image icon to open a file picker. Select a JPEG, PNG, or WebP image. It uploads immediately and appears as a thumbnail on the chip.
  • Image set: Hover over the thumbnail to reveal a remove button (X). Click it to clear the image.
  • Images are uploaded to your workspace storage and served via CDN.

Assigning images via AI chat

You can also assign option images by uploading images in the chat interface. Drop or select multiple images, then send them to the builder. The AI will:

  1. Ask how you want to use them (option swatches or product photos).
  2. If you confirm “option visuals”, the AI visually analyzes each image.
  3. It matches images to existing parameter options by identifying colors, materials, or variants.
  4. It calls the assign_option_images tool to set the image_url on each option in one batch.

If the AI cannot confidently identify which option an image belongs to, it will ask you before assigning.

Best practices

Consistent sizing

Use square images (1:1 aspect ratio) for the cleanest look across all control types. 200×200px is a good minimum resolution.

Neutral backgrounds

Use transparent PNG or a consistent neutral background so thumbnails look polished next to each other.

Texture swatches for colors

For materials like wood grain, marble, or fabric, use close-up texture photos as color swatches instead of flat hex values.

Match your product photos

Crop option images from your actual product photos when possible. This creates a visual connection between the swatch and the product preview.

Option images are stored on the ParameterOption object (the image_url field). They are independent of the product photo gallery (assets). Assigning an option image does not create a product photo entry.

← Back to documentationNeed help? Contact support