> ## 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.

# button()

> Everything a button file declares, what its run function receives, and the types shared by every interactive component

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

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

export default button({
  label: 'Confirm',
  style: 'success',
  async run({ interaction }) {
    await interaction.update({ content: 'Confirmed!', components: [] });
  },
});
```

> [!NOTE]
>
> How to write a button, carry data in it and answer a click is in the [guide](https://www.chapterjs.org/components.md). This page lists what exists.

## button()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
button<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'>(config: ButtonConfig<Data, Where>): ButtonDeclaration<Data>
```

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

`Data` and `Where` are inferred from what you pass: you never write them.

### ButtonDeclaration

What `button()` 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 the button carries (`ban({ userId })`); a button without data is used as is (`confirm`), or called with a look (`confirm({ disabled: true })`).

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ButtonDeclaration<Data extends DataShape = {}> = { readonly config: unknown } &
  ({} extends Data
    ? ((look?: ButtonLook) => ButtonComponent) & ButtonComponent
    : {} extends DataInputOf<Data>
      ? ((data?: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent) & ButtonComponent
      : (data: DataInputOf<Data>, look?: ButtonLook) => ButtonComponent)
```

**config** `unknown`

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

## ButtonConfig

What a button file gives to `button()`. It has every field of [`ButtonLook`](#buttonlook) and of [`InteractiveConfig`](#interactiveconfig), plus:

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

What to do when someone clicks the button. Leave it out for a button that is only waited for (`message.waitForClick()`): once nothing waits, a click answers that it is not available any more. See [Waiting for an answer](https://www.chapterjs.org/waiting.md#a-click).

A button needs a `label` or an `emoji`.

### ButtonLook

What a button looks like. Everything is optional when it is put in a message: what the file says is the default.

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

The text on the button (80 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).

**emoji** `EmojiInput`

An emoji on the button, before the label.

**style** `ButtonStyleName`

The color of the button. `'primary'` by default.

**disabled** `boolean`

Shows the button greyed out, impossible to click.

### ButtonStyleName

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ButtonStyleName = 'primary' | 'secondary' | 'success' | 'danger'
```

The color of a button: `'primary'` (blurple), `'secondary'` (grey), `'success'` (green) or `'danger'` (red). Link and premium buttons are made with [`linkButton()`](https://www.chapterjs.org/reference/layout#linkbutton) and [`premiumButton()`](https://www.chapterjs.org/reference/layout#premiumbutton).

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

## ButtonContext

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

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ButtonContext<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> =
  InteractiveContext<Data> & PlaceOf<Where, ComponentInteraction>
```

## Shared by buttons and select menus

### InteractiveConfig

What every interactive component declares, besides what it looks like.

**data** `DataShape`

What the component carries from the message that shows it to the code that runs when it is used: a name and a kind for each value (`{ userId: 'string', page: 'number' }`). Given when the component is put in a message, received typed in `run`. Discord keeps it in the component itself, so it survives restarts.

**where** `ComponentWhere`

Where the component can be used: `'guild'` (in servers, the default), `'dm'` (in private messages with the bot) or `'both'`. What `run` receives follows it.

**who** `ComponentWho`

Who may use it: `'everyone'` (the default) or only the `'author'` of the command the message answers.

**ephemeral** `boolean`

Make the answers of the component only visible to who used it. On a message only the person sees (an ephemeral answer), they already are.

### InteractiveContext

What every interactive component gives to its `run`, besides the place.

**user** `User`

Who used it.

**message** `Message`

The message the component is on.

Every component also receives `t` when the project has a language: see [`TranslationContext`](https://www.chapterjs.org/reference/messages#translationcontext).

**data** `DataValuesOf\<Data\>`

What the component carries, as declared in `data`.

### ComponentWhere

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ComponentWhere = 'guild' | 'dm' | 'both'
```

Where a component can be used: in messages of servers (`'guild'`), in private messages with the bot (`'dm'`), or in both. A component is where the message that holds it is: this says where your code expects it.

### ComponentWho

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ComponentWho = 'everyone' | 'author'
```

Who may use a component: `'everyone'` who sees the message (the default), or only the `'author'`, the person who used the command the message answers. Anyone else gets a private refusal.

## Data

### DataKind

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type DataKind = 'string' | 'number' | 'boolean'
```

The kinds of values a component can carry in its `data`.

### DataField

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type DataField = DataKind | { type: 'string'; default?: string } | { type: 'number'; default?: number } | { type: 'boolean'; default?: boolean }
```

One value a component carries: its kind, or its kind with a default value, which makes it optional where the component is put in a message.

### DataShape

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type DataShape = Readonly<Record<string, DataField>>
```

What a component carries: a name for each value, and its kind.

### DataValuesOf

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type DataValuesOf<Shape extends DataShape> = { [Name in keyof Shape]: string | number | boolean }
```

The values of a `data` declaration, typed from it: what `run` and the texts of the component receive. A value with a default is always there.

### DataInputOf

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type DataInputOf<Shape extends DataShape> = { [Name in keyof Shape]: string | number | boolean }
```

What a message gives to a component: the values of its `data`, those with a default value being optional.

## The place

What `run` receives about where the component was used follows `where`, like for a [command](https://www.chapterjs.org/reference/command.md#commandcontext). The same types serve forms, with a `ModalInteraction`.

### PlaceOf

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type PlaceOf<Where extends ComponentWhere, I extends Interaction> =
  Where extends 'guild' ? PlaceInGuild<I>
  : Where extends 'dm' ? PlaceInDm<I>
  : PlaceInGuild<I> | PlaceInPrivate<I>
```

What `run` receives about where it was used, following `where`.

### PlaceInGuild

What `run` receives about the place, in a server.

**interaction** `InGuild\<I\>` *required*

The interaction, with its server, member and channel never `null`.

**guild** `Guild` *required*

The server it was used in.

**member** `GuildMember` *required*

Who used it, as a member of the server.

**channel** `GuildTextBasedChannel` *required*

The channel it was used in.

### PlaceInPrivate

What `run` receives about the place, in a private message, when it also works in servers (`where: 'both'`).

**interaction** `InPrivate\<I\>` *required*

The interaction, with `guildId`, `guild` and `member` set to `null`.

**guild** `null` *required*

No server: it was used in a private message.

**member** `null` *required*

No member: the person is `user`.

**channel** `DMChannel` *required*

The private conversation it was used in.

### PlaceInDm

What `run` receives about the place, when it only works in private messages (`where: 'dm'`).

**interaction** `InDm\<I\>` *required*

The interaction, on which nothing about a server exists.

**channel** `DMChannel` *required*

The private conversation it was used in.

### InGuild, InPrivate, InDm

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type InGuild<I extends Interaction> = I & { guildId: string; guild: Guild; member: GuildMember; channel: GuildTextBasedChannel }
type InPrivate<I extends Interaction> = I & { guildId: null; guild: null; member: null; channel: DMChannel }
type InDm<I extends Interaction> = Omit<I, 'guildId' | 'guild' | 'member' | 'channel'> & { channel: DMChannel }
```

An interaction as seen from a server, from a private message for something that also works in servers, and from a private message for something that only works there.


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