> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awaitio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Select Single

> Asks to pick one of a list of options.

`io.select.single()` asks to pick one option from a drop-down and returns its value. Provided by the `@awaitio/select-single` package.

<Frame>
  <img src="https://mintcdn.com/awaitio/MjbT5AW66vMXbVck/images/io-select-single.png?fit=max&auto=format&n=MjbT5AW66vMXbVck&q=85&s=1e6910a581b742f0a06522457a4bac3d" alt="A Single choice drop-down with Slack chosen, with help text under it" width="1004" height="212" data-path="images/io-select-single.png" />
</Frame>

## Install

```bash theme={null}
npm install @awaitio/select-single
```

## Setup

Register it under the key you want in `io`, see [Input components](/core/components):

```ts app.ts {5} theme={null}
import { selectSingle } from '@awaitio/select-single';

export const app = new AwaitIO({
  // name, actionsDirectory, theme, secret, users…
  components: { select: { single: selectSingle } },
});
```

## Usage

```ts theme={null}
const role = await io.select.single('New role', {
  options: [
    { value: 'admin', label: 'Admin' },
    { value: 'editor', label: 'Editor' },
    { value: 'viewer', label: 'Viewer' },
  ],
  defaultValue: 'editor',
});
```

## Props

| Prop | Type | Required | Description |
| - | - | - | - |
| `options` | `{ value, label }[]` | Required | What to choose from, at least one. The drop-down shows `label`. |
| `defaultValue` | `string` | Optional | The `value` chosen at the start. Nothing is chosen when left out. |
| `helpText` | `string` | Optional | Secondary text under the field. |
| `disabled` | `boolean` | Optional | Shows the starting value without letting it change; the handler gets that value whatever the browser sends. |

## Optional

The field is required. Chain `.optional()` to let it stay empty; the handler then gets `string | undefined`, see [Optional fields](/core/components#optional-fields).

```ts theme={null}
const team = await io.select.single('Team', { options: teams }).optional();
```

## Returns

`string`: the chosen option's `value`.

## Built-in validation

The server checks every answer, so a crafted request cannot slip in another value:

| When | Message |
| - | - |
| Nothing chosen | `Choose <label>.` |
| A value that was not among the options | `<label>: choose one of the options.` |

## Custom validation

Chain `.validate()` for a check of your own. It runs on the server after the checks above, gets the value the handler would get and returns a message to show under the field, or nothing when the value is fine; see [Custom validation](/core/components#custom-validation).

```ts theme={null}
const plan = await io.select.single('Plan', { options: plans }).validate((plan) => {
  return plan === 'enterprise' && !account.hasContract ? 'Enterprise needs a signed contract first.' : undefined;
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.