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
```javascript
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:
```javascript
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:
```typescript
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](#parameters) below for the full list of options). |
{% hint style="danger" %} \*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](https://github.com/cure53/DOMPurify), and these values may be removed to prevent DOM clobbering.
{% endhint %}
***
## 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](/content/css-utility-classes.md). |
| `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](https://mozilla.github.io/nunjucks/) expression. [See example](#conditional-display). |
### 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`.
```javascript
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:
```javascript
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:
```javascript
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](/content/css-utility-classes.md).
### 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](https://mozilla.github.io/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.
```javascript
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 %}
:::
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.forms.md/input-types/picture-choice.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.