View Source Nostrum.Struct.Component behaviour (Nostrum v0.10.0)

Components are a framework for adding interactive elements to the messages your app or bot sends. They're accessible, customizable, and easy to use. There are several different types of components; this documentation will outline the basics of this new framework and each example.

Components have been broken out into individual modules for easy distinction between them and to separate helper functions and individual type checking between component types - especially as more components are added by Discord.

Each of the components are provided all of the valid types through this module to avoid repetition and allow new components to be added quicker and easier.

Action Row

An Action Row is a non-interactive container component for other types of components. It has a type: 1 and a sub-array of components of other types.

You can have up to 5 Action Rows per message
An Action Row cannot contain another Action Row
An Action Row containing buttons cannot also contain a select menu

Buttons

Buttons are interactive components that render on messages. They have a type: 2, They can be clicked by users. Buttons in Nostrum are further separated into two types, detailed below. Only the Interaction Button will fire a Nostrum.Struct.Interaction when pressed.

Discord Buttons

Buttons must exist inside an Action Row
An Action Row can contain up to 5 buttons
An Action Row containing buttons cannot also contain a select menu

For more information check out the Discord API Button Styles for more information.

Link Buttons

Link buttons do not send an interaction to your app when clicked
Link buttons must have a url, and cannot have a custom_id
Link buttons will always use style: 5

Link `style: 5`

Link Button

Interaction Buttons ( Non-link Buttons )

Discord calls these buttons "Non-link Buttons" due to the fact that they do not contain a url. However it would be more accurate to call them an "Interaction Button" as they do fire an interaction when clicked which is far more useful for your applications interactivity. As such they are referred to as "Interaction Button" throughout the rest of this module.

Interaction buttons must have a custom_id, and cannot have a url
Can have one of the below :style applied.

Primary `style: 1`

Primary

Secondary `style: 2`

Secondary

Success `style: 3`

Success

Danger `style: 4`

Danger (1)

🐼 Emoji Buttons

Note: The discord documentation and marketing material in relation to buttons indicates that there are three kinds of buttons: 🐼 Emoji Buttons, Link Buttons & Non-Link Buttons. When in fact all buttons can contain an emoji. Because of this reason 🐼 Emoji Buttons are not included as a separate type. Emojis will be instead handled by the two included ( superior ) button types.

emoji buttons in action

The field requirements are already becoming convoluted especially considering everything so far is all still a "Component". Using the sub types and helper functions will ensure all of the rules are followed when creating components.

Select Menu

Select menus are another interactive component that renders on messages. On desktop, clicking on a select menu opens a dropdown-style UI; on mobile, tapping a select menu opens up a half-sheet with the options.

Discord Selects

Select menus support single-select and multi-select behavior, meaning you can prompt a user to choose just one item from a list, or multiple. When a user finishes making their choice by clicking out of the dropdown or closing the half-sheet, your app will receive an interaction.

Select menus must be sent inside an Action Row
An Action Row can contain only one select menu
An Action Row containing a select menu cannot also contain buttons

Text Input

Text inputs are an interactive component that render on modals. They can be used to collect short-form or long-form text.

Text inputs must be sent inside an Action Row
An Action Row can contain only one text input
An Action Row containing a text input cannot also contain buttons or a select menu

Can be used to collect short-form or long-form text.

For short-form text, use style: 1
For long-form text, use style: 2

Text inputs are only allowed to be sent as part of an Interaction response that opens a MODAL.

Summary

Types

channel_types()

components()

A list of components to place inside an action row.

custom_id()

Used to identify the component when the interaction is sent to you from the user.

default_values()

disabled()

Indicates if the component is disabled or not.

emoji()

A partial emoji to display on the object.

label()

A string that appears on the button, max 80 characters.

max_length()

The maximum length of the text input. Minimum value 1, max 4000.

max_values()

The maximum number of permitted selections. Minimum value 0, max 25.

min_length()

The minimum length of the text input. Minimum value 0, max 4000.

min_values()

The minimum number of permitted selections. Minimum value 0, max 25.

options()

A list of options for select menus, max 25.

placeholder()

Placeholder text if nothing is selected, max 100 characters

required()

Indicates if the text input is required.

style()

Indicates the style.

t()

The currently valid component types.

type()

The type of component.

url()

A url for link buttons.

value()

A pre-filled value for the text input, max 4000 characters.

Callbacks

new(opts)

Create a component from the given keyword list of options

update(t, opts)

Updates a component with the parameters provided.

Functions

to_struct(map)

Types

channel_types()

(since 0.5.0)

@type channel_types() :: [Nostrum.Struct.Channel.type()]

components()

(since 0.5.0)

@type components() :: [
  Nostrum.Struct.Component.SelectMenu.t()
  | Nostrum.Struct.Component.Button.t()
  | nil
]

A list of components to place inside an action row.

Due to constraints of action rows, this can either be a list of up to five buttons, a single select menu, or a single text input.

Valid for Action Row.

custom_id()

(since 0.5.0)

@type custom_id() :: String.t() | nil

Used to identify the component when the interaction is sent to you from the user.

Valid for Interaction Buttons, Select Menus, and Text Input.

default_values()

(since 0.5.0)

@type default_values() :: [Nostrum.Struct.Component.DefaultValue.t()]

disabled()

(since 0.5.0)

@type disabled() :: boolean() | nil

Indicates if the component is disabled or not.

Valid for Buttons & Select Menus.

emoji()

(since 0.5.0)

@type emoji() ::
  %{
    id: Nostrum.Struct.Emoji.id(),
    name: Nostrum.Struct.Emoji.name(),
    animated: Nostrum.Struct.Emoji.animated()
  }
  | nil

A partial emoji to display on the object.

Valid for Buttons

label()

(since 0.5.0)

@type label() :: String.t() | nil

A string that appears on the button, max 80 characters.

Valid for Buttons

max_length()

(since 0.5.1)

@type max_length() :: integer() | nil

The maximum length of the text input. Minimum value 1, max 4000.

Valid for Text Input.

max_values()

(since 0.5.0)

@type max_values() :: integer() | nil

The maximum number of permitted selections. Minimum value 0, max 25.

Valid for Select Menus.

min_length()

(since 0.5.1)

@type min_length() :: integer() | nil

The minimum length of the text input. Minimum value 0, max 4000.

Valid for Text Input.

min_values()

(since 0.5.0)

@type min_values() :: integer() | nil

The minimum number of permitted selections. Minimum value 0, max 25.

Valid for Select Menus.

options()

(since 0.5.0)

@type options() :: [Nostrum.Struct.Component.Option.t()] | nil

A list of options for select menus, max 25.

Valid for Select Menus.

placeholder()

(since 0.5.0)

@type placeholder() :: String.t() | nil

Placeholder text if nothing is selected, max 100 characters

Valid for Select Menus and Text Input.

required()

(since 0.5.1)

@type required() :: boolean() | nil

Indicates if the text input is required.

Valid for Text Input.

style()

(since 0.5.0)

@type style() :: integer() | nil

Indicates the style.

You can use one of the Nostrum.Constants.ButtonStyle methods.

Valid for Valid for Interaction Buttons and Text Input.

t()

(since 0.5.0)

@type t() ::
  Nostrum.Struct.Component.ActionRow.t()
  | Nostrum.Struct.Component.Button.t()
  | Nostrum.Struct.Component.SelectMenu.t()
  | Nostrum.Struct.Component.TextInput.t()

The currently valid component types.

type()

(since 0.5.0)

@type type() :: integer()

The type of component.

Valid for All Types.

	Component Types
`1`	Action Row
`2`	Button
`3`	SelectMenu
`4`	TextInput

You can use one of the Nostrum.Constants.ComponentType methods.

Check out the Discord API Message Component Types for more information.

url()

(since 0.5.0)

@type url() :: String.t() | nil

A url for link buttons.

Valid for: Buttons

value()

(since 0.5.1)

@type value() :: String.t() | nil

A pre-filled value for the text input, max 4000 characters.

Valid for Text Input.

Callbacks

new(opts)

(since 0.5.0)

@callback new(opts :: [keyword()]) :: t()

Create a component from the given keyword list of options

Note: While using this function directly, you are not guaranteed to produce a valid component and it is the responsibility of the user to ensure they are passing a valid combination of component attributes. eg. if you pass a button component both a custom_id, and a url, the component is invalid as only one of these fields is allowed.

update(t, opts)

(since 0.5.0)

@callback update(t(), opts :: [keyword()]) :: t()

Updates a component with the parameters provided.

Note: While using this function directly, you are not guaranteed to produce a valid component and it is the responsibility of the user to ensure they are passing a valid combination of component attributes. eg. if you pass a button component both a custom_id, and a url, the component is invalid as only one of these fields is allowed.

Functions

to_struct(map)

(since 0.5.0)

@spec to_struct(map()) :: struct()

View Source Nostrum.Struct.Component behaviour (Nostrum v0.10.0)

Action Row

Buttons

Link Buttons

Link style: 5

Interaction Buttons ( Non-link Buttons )

Primary style: 1

Secondary style: 2

Success style: 3

Danger style: 4

🐼 Emoji Buttons

Select Menu

Text Input

Summary

Types

Callbacks

Functions

Types

channel_types()

components()

custom_id()

default_values()

disabled()

emoji()

label()

max_length()

max_values()

min_length()

min_values()

options()

placeholder()

required()

style()

t()

type()

url()

value()

Callbacks

new(opts)

update(t, opts)

Functions

to_struct(map)

Link `style: 5`

Primary `style: 1`

Secondary `style: 2`

Success `style: 3`

Danger `style: 4`