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

# select()

> Everything a select menu file declares, the three ways to write options, and what the run function receives

`select()` declares a select menu, from any file of `src/`; the name of its export is its id. It takes one object, `SelectConfig`, and types `values` in `run` from it.

```ts src/components/color.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { select } from 'chapterjs';

export default select({
  placeholder: 'Pick a color',
  options: { Red: 'red', Blue: 'blue' },
  async run({ interaction, value }) {
    await interaction.update({ content: `You picked ${value}.`, components: [] });
  },
});
```

> [!NOTE]
>
> How to write a menu and show it is in the [guide](https://www.chapterjs.org/components/selects.md). This page lists what exists. What a menu shares with a button (`data`, `where`, `who`, the place) is on the [button() page](https://www.chapterjs.org/reference/button.md#shared-by-buttons-and-select-menus).

## select()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
select<Options extends SelectOptions, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'>(config: StringSelectConfig<Options, Data, Where>): SelectDeclaration<Data>
select<Type extends EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'>(config: EntitySelectConfig<Type, Data, Where>): SelectDeclaration<Data>
```

Declares a select menu. Export the result from any file of `src/`: the name of the export is what tells the menu apart, so you never write an id.

### SelectDeclaration

What `select()` returns: a declaration the framework finds in the exports of a file. Import it where you send a message, and call it with the data it carries; a menu without data is used as is, or called with what to show.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type SelectDeclaration<Data extends DataShape = {}> = { readonly config: unknown } &
  ({} extends Data
    ? ((options?: SelectInstanceOptions) => SelectComponent) & SelectComponent
    : {} extends DataInputOf<Data>
      ? ((data?: DataInputOf<Data>, options?: SelectInstanceOptions) => SelectComponent) & SelectComponent
      : (data: DataInputOf<Data>, options?: SelectInstanceOptions) => SelectComponent)
```

**config** `unknown`

What the file gave to `select()`, not checked yet.

## SelectConfig

What a select file gives to `select()`: a menu of texts, or of things of the server.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type SelectConfig = StringSelectConfig | EntitySelectConfig
```

Both have every field of [InteractiveConfig](https://www.chapterjs.org/reference/button.md#interactiveconfig) and of [SelectLook](#selectlook), plus:

**min** `number`

How many things must be picked at least (0 to 25). 1 by default.

**max** `number`

How many things can be picked at most (1 to 25). 1 by default.

**run** `(context: SelectContext\<Picked, Data, Where\>) =\> unknown`

What to do when something is picked. Leave it out for a menu that is only waited for (`message.waitForClick()`).

### StringSelectConfig

A menu of texts you declare.

**type** `'string'`

The kind of menu: texts you declare, which is the default.

**options** `SelectOptions` *required*

The options (25 at most): a list of texts, an object from what is shown to what your code receives, or a list of `RichOption`.

### EntitySelectConfig

A menu of users, roles, users and roles, or channels of the server.

**type** `EntitySelectType` *required*

The kind of menu: what Discord lists.

**channelTypes** `readonly ChannelType[]`

For a menu of channels: the kinds of channels listed. All by default.

### SelectType, EntitySelectType

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type SelectType = 'string' | 'user' | 'role' | 'mentionable' | 'channel'
type EntitySelectType = 'user' | 'role' | 'mentionable' | 'channel'
```

The kinds of menus: texts you declare, or things of the server.

[Discord documentation](https://docs.discord.com/developers/components/reference#string-select)

## SelectLook

What a select menu looks like.

**placeholder** `DynamicText\<Data\>`

The text shown when nothing is picked (150 characters at most): written as is, or a function of `t` and the data, run when the message is sent. See [DynamicText](https://www.chapterjs.org/reference/messages.md#dynamictext).

**disabled** `boolean`

Shows the menu greyed out, impossible to use.

### SelectInstanceOptions

What a message can change when it shows a menu: everything of `SelectLook`, plus:

**defaults** `readonly (string | \{ id: Snowflake \})[]`

What is picked when the menu appears: the values of the options for a menu of texts, the ids (or the things themselves) for the others.

## Options

### SelectOptions

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type SelectOptions = readonly string[] | Readonly<Record<string, string>> | readonly RichOption[]
```

The options of a menu: a list of texts (each is shown and received as is), an object whose keys are what is shown and values what your code receives, or a list of `RichOption` for descriptions and emojis. The same type serves the `select`, `radio` and `checkboxes` fields of a [form](https://www.chapterjs.org/reference/modal.md).

### RichOption

One option of a menu, with everything Discord shows for it.

**label** `DynamicText\<Data\>` *required*

What the person sees (100 characters at most): a text, or a function of `t` and the data.

**value** `string` *required*

What your code receives (100 characters at most).

**description** `DynamicText\<Data\>`

A second line under the label (100 characters at most): a text, or a function of `t` and the data.

**emoji** `EmojiInput`

An emoji before the label.

**default** `boolean`

Shows the option as picked when the menu appears.

### OptionValue

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type OptionValue<Options extends SelectOptions> = string
```

What `run` receives for one picked option, typed from the declaration: the union of the texts of a list, of the values of an object, or of the `value` of each `RichOption`.

[Discord documentation](https://docs.discord.com/developers/components/reference#string-select-select-option-structure)

## SelectContext

What `run` receives when something is picked: everything of [InteractiveContext](https://www.chapterjs.org/reference/button.md#interactivecontext), the place as [PlaceOf](https://www.chapterjs.org/reference/button.md#placeof) gives it with a [ComponentInteraction](https://www.chapterjs.org/reference/interaction.md#componentinteraction), and:

**values** `Picked[]` *required*

What was picked, in the order of the menu.

**value** `Picked | undefined` *required*

The first thing picked; `undefined` when nothing was (a menu with `min: 0`).

`Picked` is `OptionValue<Options>` for a menu of texts, `User` for `'user'`, `Role` for `'role'`, `User | Role` for `'mentionable'` and `Channel` for `'channel'`.


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