> For the complete documentation index, see [llms.txt](https://docs.forms.md/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forms.md/input-types/select-box.md).

# Select box

<figure><img src="/files/7D3dws7EqWbfDBEn7mGj" alt=""><figcaption><p>Select box</p></figcaption></figure>

Use the `selectBox()` function to create select boxes in your forms. It uses the HTML `<select>` element which provides a dropdown list of options.

***

## Basic usage

```javascript
import { Composer } from "formsmd";

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

composer.selectBox("country", {
  question: "Which country are you from?",
  options: ["United States", "Canada", "United Kingdom"]
});
```

Generates the following Markdown-like syntax:

```
#! id = my-form

country = SelectBox(
  | question = Which country are you from?
  | options = United States, Canada, United Kingdom
)
```

### Required

Add the `required` parameter to make the field mandatory:

```javascript
composer.selectBox("country", {
  question: "Which country are you from?",
  options: ["United States", "Canada", "United Kingdom"],
  required: true
});
```

Generates the following Markdown-like syntax:

```
country* = SelectBox(
  | question = Which country are you from?
  | options = United States, Canada, United Kingdom
)
```

***

## Function overview

The following is the overview of the function:

```typescript
selectBox(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.<mark style="color:red;">\*</mark>                                            |
| `params` | `object` | An object containing all the configuration parameters for your select box field (see the [parameters section](#parameters) below for the full list of options). |

{% hint style="danger" %} <mark style="color:red;">\*</mark>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). |

### Select box specific parameters

| Name                 | Type                                                 | Description                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` (required) | `Array<string \| { label: string, value?: string }>` | Array of options that can be either strings (e.g., `["Option 1", "Option 2"]`) or objects with a `label` for display text and an optional `value` (e.g., `[{ label: "Option 1", value: "opt1" }]`). When using objects, if `value` is not provided, `label` is used as the value. |
| `selected`           | `string`                                             | Pre-selected option value.                                                                                                                                                                                                                                                        |
| `placeholder`        | `string`                                             | Sets the placeholder option of the select.                                                                                                                                                                                                                                        |

***

## Examples

### Select box with value-label pairs

Value-label pairs allow different values to be stored than what's shown to users. The `label` appears in the dropdown for users to select, while the `value` is stored in the form data. This pattern is particularly useful for storing concise identifiers in a database while displaying more descriptive text in the interface.\
\
Please note, for `selected` to work with value-label pairs, it must contain the `value`, not the `label`.&#x20;

```javascript
composer.selectBox("experience", {
  question: "Years of experience",
  options: [
    { label: "Junior (0-2 years)", value: "junior" },
    { label: "Mid-level (3-5 years)", value: "mid" },
    { label: "Senior (6+ years)", value: "senior" }
  ],
  selected: "mid",
  required: true
});
```

Generates the following Markdown-like syntax:

```
experience* = SelectBox(
  | question = Years of experience
  | options = "junior" Junior (0-2 years), "mid" Mid-level (3-5 years), "senior" Senior (6+ years)
  | selected = mid
)
```

### Select box with custom placeholder

```javascript
composer.selectBox("language", {
  question: "What's your preferred programming language?",
  description: "Choose the language you're most comfortable with",
  placeholder: "Select a language",
  options: ["JavaScript", "Python", "Java", "C++"],
  required: true
});
```

Generates the following Markdown-like syntax:

```
language* = SelectBox(
  | question = What's your preferred programming language?
  | description = Choose the language you're most comfortable with
  | placeholder = Select a language
  | options = JavaScript, Python, Java, C++
)
```

### Styled select box with custom attributes

Add CSS classes and other HTML attributes using the `classNames` and `attrs` parameters. Please note, these class names and attributes are added to the `<div>` or `<fieldset>` container that contains the actual select field.

```javascript
composer.selectBox("jobRole", {
  question: "Select your role",
  options: ["Developer", "Designer", "Manager"],
  classNames: ["col-6", "xs:col-6"],
  attrs: [
    { name: "style", value: "font-size: 18px;" }
  ]
});
```

Generates the following Markdown-like syntax:

```
[.col-6 .xs:col-6 style="font-size: 18px;"]
jobRole = SelectBox(
  | question = Select your role
  | options = Developer, Designer, Manager
)
```

Please [see the available CSS utility classes](/content/css-utility-classes.md).

### Conditional display

Conditionally show or hide a select box 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 framework select will only show up if the user indicates they are a developer.

```javascript
composer.selectBox("jobTitle", {
  question: "What is your job title?",
  required: true,
  options: ["Developer", "Designer", "Manager"]
});

composer.selectBox("framework", {
  question: "Which framework do you primarily use?",
  options: ["React", "Vue", "Angular"],
  displayCondition: {
    dependencies: ["jobTitle"],
    condition: "jobTitle == 'Developer'"
  }
});
```

Generates the following Markdown-like syntax:

```
jobTitle* = SelectBox(
  | question = What is your job title?
  | options = Developer, Designer, Manager
)

::: [{$ jobTitle $}]
{% if jobTitle == "Developer" %}
framework = SelectBox(
  | question = Which framework do you primarily use?
  | options = React, Vue, Angular
)
{% endif %}
:::
```