Tutorial: Image Choice (PRO)
Form Preview

What You'll Build

Beautiful, visual selection fields using images. Perfect for product pickers, style selectors, travel options, and any scenario where pictures speak louder than words.

What You'll Learn

  • Creating single and multiple selection image pickers
  • Using different layouts: columns and carousel
  • Applying visual variants: card, thumbnail, and overlay
  • Adding labels and descriptions to options
  • Controlling image sizes: global optionSize and per-option size
  • Disabling options with isDisabled
  • Per-option custom styling for featured/special items
  • Controlling deselection behavior with allowDeselect
  • Custom styling for container, options, and selected states
  • Dynamic options that change based on form state
🖼️

PRO Feature

Image Choice uses Image Assets, a PRO feature. Upload your images in account settings.

This tutorial uses sample travel images available for everyone to try!

⚡

Interactive Learning

Every code snippet is fully editable! Modify the code, experiment with options, and see changes instantly in the live preview.

Tutorial Steps

Step 1: Basic Single Selection

Start with addImageChoice() and selectionMode: 'single' for radio button-like behavior with images. Users can select exactly one option.

💡 Tip:
Each option needs an id (the value stored), an assetId (the uploaded image), and optionally a label.

Step 2: Multiple Selection

Set selectionMode: 'multiple' to allow users to select multiple images. Use min and max to constrain how many can be selected.

💡 Tip:
When multiple selection is enabled, the field value becomes an array of selected option IDs (e.g., ['budget', 'luxury']).

Step 3: Columns Layout

The columns layout arranges options in a grid. Use columnsCount to specify 2, 3, 4, or 'auto' columns.

💡 Tip:
Use columnsCount: 'auto' for responsive layouts that adapt to the container width. Options will wrap to new rows as needed.

Step 4: Carousel Layout

The carousel layout shows a fixed number of options with navigation arrows. Configure visibleItems, showArrows, showDots, and loop.

💡 Tip:
Enable loop: true for infinite scrolling. Use showDots: true for pagination indicators at the bottom.

Step 5: Card Variant

The card variant (default) shows the image with label and description below. Great for detailed product selections.

💡 Tip:
Add description to options for additional context. Descriptions appear below the label in card variant.

Step 6: Thumbnail Variant

The thumbnail variant is minimal and image-focused. The border appears directly on the image, perfect for compact selections.

💡 Tip:
Thumbnails work great with smaller optionSize values. Labels appear below the image without the card border.

Step 7: Overlay Variant

The overlay variant places the label on top of the image with a gradient background. Creates a dramatic, immersive look.

💡 Tip:
Overlay works best with larger images. The gradient ensures text remains readable over any image.

Step 8: Custom Styling

Fine-tune appearance with three styling options: customStyles (container), optionStyles (each option), and selectedOptionStyles (selected state).

💡 Tip:
Use selectedOptionStyles for subtle animations like transform: scale(1.02) to make selections feel responsive.

Step 9: Option Size (Global & Per-Option)

Control image dimensions with optionSize for all options, or override per-option using size in individual options.

💡 Tip:
Set only width OR height to preserve aspect ratio. Setting both forces exact dimensions.

Step 10: Option-Level Features

Each option can have its own isDisabled, customStyles, and size. Great for sold-out items or featured products.

💡 Tip:
Use isDisabled: true to gray out unavailable options. Use per-option customStyles to highlight special items.

Step 11: Allow Deselect

Control whether users can click a selected option to deselect it. Default is true. Set allowDeselect: false to force a selection once made.

💡 Tip:
Use allowDeselect: false when you require a choice and don't want users to accidentally clear their selection.

Step 12: Dynamic Options

Make options dynamic using form.state() and form.computedValue(). Options can filter or change based on other field values.

💡 Tip:
Combine ImageChoice with radio buttons or dropdowns to create powerful filtering interfaces where users narrow down visual choices.

Step 13: Complete Travel Planner

Let's put it all together! A complete travel planning form using multiple ImageChoice fields with different configurations.

💡 Tip:
Access ImageChoice values with form.imageChoice('id')?.value(). For multiple selection, the value is an array.

ImageChoice Configuration Reference

ImageChoiceConfig (field-level)

  • options: Array of ImageChoiceOption objects
  • selectionMode: 'single' (default) or 'multiple'
  • min / max: Constraints for multiple selection mode
  • allowDeselect: Click selected option to deselect (default: true)
  • defaultValue: Initial selection (string for single, string[] for multiple)
  • layout:{ type: 'columns', columnsCount } or { type: 'carousel', visibleItems, showArrows, showDots, loop }
  • variant: 'card' (default), 'thumbnail', or 'overlay'
  • optionSize:{ width?, height? } - base size for all options
  • customStyles: CSS styles for the container
  • optionStyles: CSS styles applied to each option
  • selectedOptionStyles: Additional styles when option is selected

ImageChoiceOption (per-option)

  • id: Unique identifier (required) - the value stored when selected
  • assetId: ID of uploaded image asset (required)
  • label: Text label displayed below/on the image
  • description: Additional description text (card variant only)
  • isDisabled: Gray out and prevent selection of this option
  • size:{ width?, height? } - override global optionSize for this option
  • customStyles: CSS styles for this specific option (e.g., highlight featured items)

Layout: Columns

  • type: 'columns'
  • columnsCount: number (e.g., 2, 3, 4) or 'auto' for responsive

Layout: Carousel

  • type: 'carousel'
  • visibleItems: Number of options visible at once (default: 3)
  • showArrows: Show navigation arrows (default: true)
  • showDots: Show dot indicators (default: false)
  • loop: Enable infinite loop (default: false)

Variants

  • 'card': Image with label/description below in bordered card (default)
  • 'thumbnail': Minimal, image-focused with border on hover/select
  • 'overlay': Label overlaid on image with gradient background

Try It Yourself

  • Challenge 1: Create a product picker with 4-column grid and overlay variant
  • Challenge 2: Build a carousel that shows 2 items at a time with loop enabled
  • Challenge 3: Add custom styling with hover effects and shadows
  • Challenge 4: Create a multi-step wizard where the second step's options depend on the first step's selection

Next Steps

Great job! You've mastered image-based selection fields. Ready to explore more?

Continue to Conditional Visibility

Related tutorials: