button()

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.

src/components/confirm.ts

import { button } from 'chapterjs';

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

How to write a button, carry data in it and answer a click is in the guide. This page lists what exists.

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 })).

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)

unknown

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

ButtonConfig

What a button file gives to button(). It has every field of ButtonLook and of InteractiveConfig, plus:

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

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.

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.

EmojiInput

An emoji on the button, before the label.

ButtonStyleName

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

boolean

Shows the button greyed out, impossible to click.

ButtonStyleName

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() and premiumButton(). Discord documentation

ButtonContext

What run receives when the button is clicked: everything of InteractiveContext, and the place as PlaceOf gives it for Where, with a ComponentInteraction.

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.

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.

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.

ComponentWho

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

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

Who used it.

Message

The message the component is on.

Every component also receives t when the project has a language: see TranslationContext.

DataValuesOf<Data>

What the component carries, as declared in data.

ComponentWhere

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

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

type DataKind = 'string' | 'number' | 'boolean'

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

DataField

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

type DataShape = Readonly<Record<string, DataField>>

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

DataValuesOf

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

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. The same types serve forms, with a ModalInteraction.

PlaceOf

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.

InGuild<I>

required

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

Guild

required

The server it was used in.

GuildMember

required

Who used it, as a member of the server.

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').

InPrivate<I>

required

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

null

required

No server: it was used in a private message.

null

required

No member: the person is user.

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').

InDm<I>

required

The interaction, on which nothing about a server exists.

DMChannel

required

The private conversation it was used in.

InGuild, InPrivate, InDm

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.

Reference

Your files

Structures

Types

CLI

button()

button()

ButtonDeclaration

ButtonConfig

ButtonLook

ButtonStyleName

ButtonContext

Shared by buttons and select menus

InteractiveConfig

InteractiveContext

ComponentWhere

ComponentWho

Data

DataKind

DataField

DataShape

DataValuesOf

DataInputOf

The place

PlaceOf

PlaceInGuild

PlaceInPrivate

PlaceInDm

InGuild, InPrivate, InDm