# 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 %}
:::
```


---

# 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/select-box.md?ask=<question>
```

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.