Message Components

Messages support a specific set of components.

Type	Actionable	Has ID
Action Row	❌ No	❌ No
Button (Disabled)	❌ No	✅ Yes
Button (Interaction)	✅ Yes	✅ Yes
Button (Link)	❌ No	❌ No
Select Menu	✅ Yes	✅ Yes

Kord Extensions provides a convenient API for shorter-lived message components. The ComponentContainer class is the core type representing this API.

To get started, use the components builder. This builder is available for use in all message creation and editing builders.

channel.createMessage { components { publicButton { label = "OK" style = ButtonStyle.Success action { respond { content = "Clicked: **OK**" } } } publicButton { label = "Cancel" style = ButtonStyle.Danger action { respond { content = "Clicked: **Cancel**" } } } } }

Components DSL

The components DSL function accepts extra arguments:

timeout, an optional timeout Duration. This argument allows you to specify how long to wait (since the components were last interacted with) until the bot should stop waiting for interactions. Defaults to null, meaning the components will work until the bot restarts.

This function requires a callable block, a receiver on the ComponentContainer type. You should use this block to define the components to add to the message. The ComponentContainer will be returned by the function.

The ComponentContainer class is open, and may be extended for advanced use-cases. If you need to create your own objects based on this class, you can use the applyComponents extension function available in all message creation/editing builders to apply its contents.

Adding Components

When adding components to messages directly, you need to define action rows for your components, and space them out yourself. The ComponentContainer still allows you to specify the rows your components belong to. However, for components with undefined rows, it will attempt to automatically pack them as tightly as possible, in the order they were defined. This automatic packing happens after your components are defined,

For example, if you provide a select menu, six buttons and another select menu, then the container packs your components into rows that look like this:

Select menu
Five buttons
One button
Select menu
Nothing

If needed, you can provide row numbers when you define your components. When you provide a row number, the container packs the component within the specified row immediately. If you combine this approach by also defining unsorted components (as mentioned above), the container packs the unsorted components alongside those with defined rows, attempting to fill the rows up as tightly as possible.

For example, if you provide a select menu on row 2, six unsorted buttons, and another select menu on row 3, then the container packs your components into rows that look like this:

Five buttons
Select menu
Select menu
One button
Nothing

DSL Functions

The following functions are available for component creation. We've split these by interaction type, just like the Application Command DSL functions.

All functions take the following arguments:

Optional: ModalForm class constructor
Optional: Row number
Component builder

Name	Component
`disabledButton`	Button (Disabled)
`ephemeralButton`	Button (Interactive)
`linkButton`	Button (Link)
`publicButton`	Button (Interactive)
`ephemeralChannelSelectMenu`	Select Menu (Channel)
`ephemeralRoleSelectMenu`	Select Menu (Role)
`ephemeralStringSelectMenu`	Select Menu (String)
`ephemeralUserSelectMenu`	Select Menu (User)
`publicChannelSelectMenu`	Select Menu (Channel)
`publicRoleSelectMenu`	Select Menu (Role)
`publicStringSelectMenu`	Select Menu (String)
`publicUserSelectMenu`	Select Menu (User)

Component Builder API

The DSL functions above take a callable block as their last argument. This block provides a set of properties and functions that allow you to configure the component. Each DSL function also returns the configured component.

All Components

The following APIs are available within all component builders.

Properties

Name	Type	Description

Actionable Components

The following APIs are available within component builders for actionable components, as defined by the table at the top of this page.

Functions

Name	Description
`action`	Specify a block of code to run when a user interacts with this component. This is a receiver function against the corresponding context type for the component, with the first argument set to an instance of the `ModalForm` provided to the DSL function, if any.
`check`	Define a Check that must pass for the `action` to be run.
`requireBotPermissions`	If your bot requires any permissions to be able to execute the `action`, use this function to register those permissions. If the component is interacted with while the bot doesn’t have the specified permissions, an error will be sent to the user, explaining which permissions the bot is missing.

Properties

Name	Type	Description
`deferredAck`	`Boolean`	Whether to respond with a deferred acknowledgement, which will hide the "Thinking..." message when a user interacts with the component. Defaults to `true`.
`locking`	`Boolean`	Whether to use a Mutex to prevent this component's action from being run concurrently with itself. Defaults to `false`, allowing the component's action to run multiple times concurrently.

Components with IDs

The following APIs are available within component builders for components with IDs, as defined by the table at the top of this page.

Properties

Name	Type	Description
`id`	`String`	A unique identifier for this component. Kord Extensions uses this ID to figure out what code to execute when a user interacts with a components. Defaults to a randomly generated UUID.

Buttons

The following APIs are available within component builders for all types of buttons.

Properties

Name	Type	Description
`label`	`Key`	Key object representing the button's label, for display on discord. You must provide either this or `partialEmoji`, or both. Note: Locales will not be automatically added to the Key object. Remember to use `.withLocale(locale)` when passing a Key object to this property.
`partialEmoji`	`DiscordPartialEmoji`	The button's emoji, for display on discord. You must provide either this or `label`, or both.

Name

Type

Description

label

Key

Key object representing the button's label, for display on discord. You must provide either this or partialEmoji, or both.

Note: Locales will not be automatically added to the Key object. Remember to use .withLocale(locale) when passing a Key object to this property.

partialEmoji

DiscordPartialEmoji

The button's emoji, for display on discord. You must provide either this or label, or both.

Actionable Buttons

Besides the APIs available to actionable components, the following APIs are available to actionable button types.

Functions

Name	Description
`disable`	Disable this button.
`enable`	Enable this button.

Properties

Name	Type	Description
`disabled`	`Boolean`	Whether this button should render as disabled, and be impossible to interact with. Defaults to `false`.

Disabled Buttons

Besides the APIs available to components with IDs, the following APIs are available to disabled buttons.

Properties

Name	Type	Description
`style`	`ButtonStyle`	Button style, used to render the button on Discord. Defaults to `Primary`.

Interaction Buttons

Besides the APIs available to components with IDs and actionable components, the following APIs are available to interaction buttons.

Functions

Name	Description
`initialResponse`	Static callable representing the initial response to provide to Discord. If you don't call this, Kord Extensions will acknowledge the interaction without a message.

Properties

Name	Type	Description
`style`	`ButtonStyle`	Button style, used to render the button on Discord. Defaults to `Primary`.

Link Buttons

The following APIs are available to link buttons.

Properties

Name	Type	Description
`url`	`String`	URL to send the user to when they interact with the button.

Select Menus

Besides the APIs available to actionable components, the following APIs are available to all types of select menu.

Functions

Name	Description
`disable`	Disable this select menu.
`enable`	Enable this select menu.

Properties

Name	Type	Description
`disabled`	`Boolean`	Whether this select menu should render as disabled, and be impossible to interact with. Defaults to `false`.
`maximumChoices`	`Int?`	The maximum number of options a user can pick. Provide `null` to remove the limit. Defaults to `1`.
`minimumChoices`	`Int`	The minimum number of options a user can pick. Must be at least `1`. Defaults to `1`.
`placeholder`	`Key?`	Key object representing the placeholder text to show before the user has selected any options. Defaults to `null`. Note: Locales will not be automatically added to the Key object. Remember to use `.withLocale(locale)` when passing a Key object to this property.

Channel Menus

The following APIs are available to channel select menus.

Functions

Name	Description
`channelType`	Add the given channel type to the list of allowed channel types for this menu.

Properties

Name	Type	Description
`channelTypes`	`MutableList<ChannelType>`	List of allowed channel types for this menu. Mutated by the `channelType` function.

String Menus

The following APIs are available to string select menus.

Functions

Name	Description
`option`	Add an option to the list of potential options for this menu. This is optionally a builder function, used to configure the option's description, emoji, and default selection state.

Properties

Name	Type	Description
`options`	`MutableList<SelectOptionBuilder>`	List of potential options for this menu. Add options using the `option` function.

Component Container API

The ComponentContainer type exposes several useful APIs. The components DSL function is a receiver for an object of this type, and it also returns that object.

Functions

Name	Description
`add`	Manually add a component to this container.
`cancel`	Cancel the timeout task, and remove all components from this container. This is equivalent to timing out the container early, but it will not run the callback defined via the `onTimeout` function. Note: This will not update the components in any related messages — you'll need to edit them to clear their components manually.
`onTimeout`	Register the callback to be run when the container times out. Note: The `cancel` function won't run this callback.
`remove`	Remove the given component from the container, and prevent it from being used. Note: This will not update the components in any related messages — use the `applyToMessage` function to do so.
`removeAll`	Remove all components from the container, and prevent them from being used. Note: This will not update the components in any related messages — use the `applyToMessage` function to do so.
`replace`	Replace a component within this container with another. Note: This will not update the components in any related messages — use the `applyToMessage` function to do so.
`sort`	Pack any unsorted components into rows. Note: You generally won't need to call this function yourself.

Receiver	Name	Description
`MessageBuilder`	`applyToMessage`	Apply the components within this container to the given message builder.

Properties

Name	Type	Description
`rows`	`Array< MutableList<Component> >`	An array representing sorted rows of components. The `sort` function fills this.
`timeout`	`Duration?`	If defined, the container will remove and unregister its components once it reaches the timeout, unless component interactions have happened. When interactions happen, the timeout resets.
`timeoutCallback`	`ComponentContainer.() -> Unit`	A callback run when the timeout expires. Defined by the `onTimeout` function.
`timeoutTask`	`Task?`	The scheduled timeout task, if a timeout exists.
`unsortedComponents`	`MutableList<Component>`	A list containing unsorted components, to be sorted by the `sort` function.

Handling Components Manually

For longer-lived message components, including those that must work after the bot restarts, it may be better to create your components manually, and write your own Event Handlers.

Defining Components

You can define components using Kord's built-in APIs in any message creation/editing builder. You'll need to define the action rows first, and then place components within them.

actionRow { interactionButton(ButtonStyle.Success, "roles/add") { label = "Add" } interactionButton(ButtonStyle.Danger, "roles/remove") { label = "Remove" } }

You may use the following functions to define components:

Name	Description
`channelSelect`	Create a channel select menu.
`interactionButton`	Create an interaction button. You may create a disabled button by setting `disabled` to `true` in the builder. Providing a style of `Link` will result in an error. For link buttons, use `linkButton` instead.
`linkButton`	Create a link button.
`mentionableSelect`	Create a select menu for all mentionable entity types.
`roleSelect`	Create a role select menu.
`stringSelect`	Create a string select menu.
`userSelect`	Create a user select menu.

For more information, see the Kord docs.

Defining Event Handlers

Once you've created your components, you'll need to create some event handlers. Kord provides several event types that are suitable for this:

ComponentInteractionCreateEvent, fired when a user interacts with any of this bot's components.
ButtonInteractionCreateEvent, fired when a user interacts with any of this bot's buttons.
SelectMenuInteractionCreateEvent, fired when a user interacts with any of this bot's select menus.

These events also come in global and guild variants.

val matchRegex = "role/\\w+".toRegex() event<GuildButtonInteractionCreateEvent> { check { failIf(!matchRegex.matches(event.interaction.componentId)) } action { val action = matchRegex .matchEntire(event.interaction.componentId)!! .groupValues[1] when (action) { "add" -> { // Add the role } "remove" -> { // Remove the role } else -> event.interaction.respondEphemeral { content = "Unknown action: $action" } } } }

For more information, see the Kord docs.

Last modified: 20 November 2024