Picture choice

Create picture choice inputs in your forms.

Picture choice

Use the pictureChoice() function to create picture choice inputs in your forms. It allows users to select one or more options from a list of choices with associated images.

---

Basic usage

import { Composer } from "formsmd";

const composer = new Composer({
  id: "my-form"
});

composer.pictureChoice("style", {
  question: "Choose your preferred style",
  choices: [
    { label: "Modern", value: "modern", image: "/styles/modern.jpg" },
    { label: "Classical", value: "classical", image: "/styles/classical.jpg" },
    { label: "Minimalist", value: "minimalist", image: "/styles/minimalist.jpg" }
  ]
});

Generates the following Markdown-like syntax:

#! id = my-form

style = PictureChoice(
  | question = Choose your preferred style
  | choices = "modern" Modern && /styles/modern.jpg, "classical" Classical && /styles/classical.jpg, "minimalist" Minimalist && /styles/minimalist.jpg
)

Required

Add the required parameter to make the field mandatory:

composer.pictureChoice("style", {
  question: "Choose your preferred style",
  choices: [
    { label: "Modern", value: "modern", image: "/styles/modern.jpg" },
    { label: "Classical", value: "classical", image: "/styles/classical.jpg" },
    { label: "Minimalist", value: "minimalist", image: "/styles/minimalist.jpg" }
  ],
  required: true
});

Generates the following Markdown-like syntax:

style* = PictureChoice(
  | question = Choose your preferred style
  | choices = "modern" Modern && /styles/modern.jpg, "classical" Classical && /styles/classical.jpg, "minimalist" Minimalist && /styles/minimalist.jpg
  | required
)

---

Function overview

The following is the overview of the function:

pictureChoice(name: string, params: object)

Arguments

Name	Type	Description
name	string	A unique name for your form field that you'll use to identify the user's response.*
params	object	An object containing all the configuration parameters for your picture choice field (see the parameters section below for the full list of options).

*Avoid values for the name argument which may be the names of HTML attributes, such as "name", "role", "id", etc. This is because by default, the form's template string is first sanitized using DOMPurify, and these values may be removed to prevent DOM clobbering.

---

Parameters

Shared parameters

These parameters are common to all form fields:

Name	Type	Description
question (required)	string	The main question or label of the form field.
required	true (boolean)	When set, the field becomes required.
description	string	Any extra information that the user may need to fill out the form. Appears right below the question.
fieldSize	"sm"	When set to "sm", the font sizes of the question, description, and answer are made smaller.
labelStyle	"classic"	When set to "classic", the question and description of the form field are made smaller.
subfield	true (boolean)	When set, the question and description of the form field are made smaller. Functionally the same as setting labelStyle to "classic".
disabled	true (boolean)	When set, the input is disabled.
autofocus	true (boolean)	When set, the input will be automatically focused when the parent slide becomes active, or immediately after page load.
id	string	The id attribute of the form field container.
classNames	string[]	The CSS class names of the form field. See the available CSS utility classes.
attrs	Array<{ name: string, value: string }>	Other HTML attributes of the form field. Each attribute has a name and value property.
displayCondition	{ dependencies: string[], condition: string }	Controls when the field is shown. The dependencies lists the fields to watch, and condition is the expression that must be true to show the field. The condition must be a valid Nunjucks expression. See example.

Picture choice specific parameters

Name	Type	Description
choices (required)	Array<{ label: string, value?: string, image: string }>	Array of choices that must include a label for display text, an optional value that's stored in the form data (if not provided, label is used as the value), and an image URL for display.
multiple	true (boolean)	Allow multiple selections.
supersize	true (boolean)	Make the pictures larger.
hideLabels	true (boolean)	Hide the text labels.
hideFormText	true (boolean)	For multiple selections, when set, the form text "Choose as many as you like" is hidden.
checked	string[]	Array of pre-checked choice values.

---

Examples

Picture choice with value-label pairs and image URLs

Value-label pairs allow different values to be stored than what's shown to users. The label appears for users to select, while the value is stored in the form data. Each choice must also include an image URL. Please note, for checked to work with value-label pairs, it must contain the value, not the label.

composer.pictureChoice("theme", {
  question: "Select your preferred theme",
  choices: [
    { 
      label: "Light and Airy",
      value: "light",
      image: "https://example.com/themes/light.jpg"
    },
    { 
      label: "Dark and Moody",
      value: "dark",
      image: "https://example.com/themes/dark.jpg"
    },
    { 
      label: "Bold and Colorful",
      value: "colorful",
      image: "https://example.com/themes/colorful.jpg"
    }
  ],
  checked: ["light"],
  multiple: true,
  required: true
});

Generates the following Markdown-like syntax:

theme* = PictureChoice(
  | question = Select your preferred theme
  | choices = "light" Light and Airy && https://example.com/themes/light.jpg, "dark" Dark and Moody && https://example.com/themes/dark.jpg, "colorful" Bold and Colorful && https://example.com/themes/colorful.jpg
  | checked = light
  | multiple
  | required
)

Supersized picture choice with hidden labels

Create a picture choice with larger images and hidden text labels:

composer.pictureChoice("avatar", {
  question: "Choose your avatar",
  choices: [
    { label: "Warrior", image: "/avatars/warrior.jpg" },
    { label: "Mage", image: "/avatars/mage.jpg" },
    { label: "Archer", image: "/avatars/archer.jpg" }
  ],
  supersize: true,
  hideLabels: true
});

Generates the following Markdown-like syntax:

avatar = PictureChoice(
  | question = Choose your avatar
  | choices = Warrior && /avatars/warrior.jpg, Mage && /avatars/mage.jpg, Archer && /avatars/archer.jpg
  | supersize
  | hidelabels
)

Styled picture choice with custom attributes

Add CSS classes and other HTML attributes using the classNames and attrs parameters:

composer.pictureChoice("layout", {
  question: "Pick your preferred layout",
  choices: [
    { label: "Grid", image: "/layouts/grid.jpg" },
    { label: "List", image: "/layouts/list.jpg" },
    { label: "Masonry", image: "/layouts/masonry.jpg" }
  ],
  classNames: ["col-6", "xs:col-6"],
  attrs: [
    { name: "style", value: "margin-top: 1rem;" }
  ]
});

Generates the following Markdown-like syntax:

[.col-6 .xs:col-6 style="margin-top: 1rem;"]
layout = PictureChoice(
  | question = Pick your preferred layout
  | choices = Grid && /layouts/grid.jpg, List && /layouts/list.jpg, Masonry && /layouts/masonry.jpg
)

Please see the available CSS utility classes.

Conditional display

Conditionally show or hide a picture choice using the displayCondition parameter. It works as follows:

• dependencies lists the fields to watch.

• condition is the expression that must be true to show the field. This must be a valid Nunjucks expression.

For instance, in the example below, the room style choices will only show up if the user indicates they are interested in interior design.

composer.choiceInput("interest", {
  question: "What is your interest?",
  choices: ["Interior Design", "Photography", "Cooking"],
  required: true
});

composer.pictureChoice("roomStyle", {
  question: "Which room style appeals to you most?",
  choices: [
    { label: "Contemporary", image: "/rooms/contemporary.jpg" },
    { label: "Traditional", image: "/rooms/traditional.jpg" },
    { label: "Industrial", image: "/rooms/industrial.jpg" }
  ],
  displayCondition: {
    dependencies: ["interest"],
    condition: "interest == 'Interior Design'"
  }
});

Generates the following Markdown-like syntax:

interest* = ChoiceInput(
  | question = What is your interest?
  | choices = Interior Design, Photography, Cooking
)

::: [{$ interest $}]
{% if interest == "Interior Design" %}
roomStyle = PictureChoice(
  | question = Which room style appeals to you most?
  | choices = Contemporary && /rooms/contemporary.jpg, Traditional && /rooms/traditional.jpg, Industrial && /rooms/industrial.jpg
)
{% endif %}
:::