Package net.dv8tion.jda.api.interactions.components

Interface Button

All Superinterfaces:

Component, SerializableData

public interface Button
extends Component

Represents a Message Button.
These buttons are located below the message in ActionRows.

Each button has either a custom_id or URL attached. The id has to be provided by the user and can be used to identify the button in the ButtonClickEvent.

Example Usage

 public class HelloBot extends ListenerAdapter {
   public void onSlashCommand(SlashCommandEvent event) {
       if (event.getName().equals("hello")) {
           event.reply("Click the button to say hello")
               .addActionRow(
                 Button.primary("hello", "Click Me"), // Button with only a label
                 Button.success("emoji", Emoji.fromMarkdown("<:minn:245267426227388416>"))) // Button with only an emoji
               .queue();
       } else if (event.getName().equals("info")) {
           event.reply("Click the buttons for more info")
               .addActionRow( // link buttons don't send events, they just open a link in the browser when clicked
                   Button.link("https://github.com/DV8FromTheWorld/JDA", "GitHub")
                     .withEmoji(Emoji.fromMarkdown("<:github:849286315580719104>")), // Link Button with label and emoji
                   Button.link("https://ci.dv8tion.net/job/JDA/javadoc/", "Javadocs")) // Link Button with only a label
               .queue();
       }
   }

   public void onButtonClick(ButtonClickEvent event) {
       if (event.getComponentId().equals("hello")) {
           event.reply("Hello :)").queue();
       }
   }
 }
 

To see what each button looks like here is an example cheatsheet:

See Also:

ReplyAction.addActionRow(Component...), ReplyAction.addActionRows(ActionRow...)

Nested Class Summary

Nested classes/interfaces inherited from interface net.dv8tion.jda.api.interactions.components.Component

Component.Type

Field Summary

Fields

Modifier and Type	Field	Description
static int	ID_MAX_LENGTH	The maximum length a button id can have
static int	LABEL_MAX_LENGTH	The maximum length a button label can have
static int	URL_MAX_LENGTH	The maximum length a button url can have

Method Summary

Modifier and Type	Method	Description
default Button	asDisabled()	Returns a copy of this button with isDisabled() set to true.
default Button	asEnabled()	Returns a copy of this button with isDisabled() set to false.
static Button	danger(java.lang.String id, java.lang.String label)	Creates a button with DANGER Style.
static Button	danger(java.lang.String id, Emoji emoji)	Creates a button with DANGER Style.
Emoji	getEmoji()	The emoji attached to this button.
java.lang.String	getLabel()	The visible text on the button.
ButtonStyle	getStyle()	The style of this button.
java.lang.String	getUrl()	The target URL for this button, if it is a LINK-Style Button.
boolean	isDisabled()	Whether this button is disabled.
static Button	link(java.lang.String url, java.lang.String label)	Creates a button with LINK Style.
static Button	link(java.lang.String url, Emoji emoji)	Creates a button with LINK Style.
static Button	of(ButtonStyle style, java.lang.String idOrUrl, java.lang.String label)	Create a button with the provided style, URL or ID, and label.
static Button	of(ButtonStyle style, java.lang.String idOrUrl, java.lang.String label, Emoji emoji)	Create an enabled button with the provided style, URL or ID, label and emoji.
static Button	of(ButtonStyle style, java.lang.String idOrUrl, Emoji emoji)	Create a button with the provided style, URL or ID, and emoji.
static Button	primary(java.lang.String id, java.lang.String label)	Creates a button with PRIMARY Style.
static Button	primary(java.lang.String id, Emoji emoji)	Creates a button with PRIMARY Style.
static Button	secondary(java.lang.String id, java.lang.String label)	Creates a button with SECONDARY Style.
static Button	secondary(java.lang.String id, Emoji emoji)	Creates a button with SECONDARY Style.
static Button	success(java.lang.String id, java.lang.String label)	Creates a button with SUCCESS Style.
static Button	success(java.lang.String id, Emoji emoji)	Creates a button with SUCCESS Style.
default Button	withDisabled(boolean disabled)	Returns a copy of this button with isDisabled() set to the provided value.
default Button	withEmoji(Emoji emoji)	Returns a copy of this button with the attached Emoji.
default Button	withId(java.lang.String id)	Returns a copy of this button with the provided id.
default Button	withLabel(java.lang.String label)	Returns a copy of this button with the provided label.
default Button	withStyle(ButtonStyle style)	Returns a copy of this button with the provided style.
default Button	withUrl(java.lang.String url)	Returns a copy of this button with the provided url.

Methods inherited from interface net.dv8tion.jda.api.interactions.components.Component

getId, getMaxPerRow, getType

Methods inherited from interface net.dv8tion.jda.api.utils.data.SerializableData

toData

Field Detail

LABEL_MAX_LENGTH

static final int LABEL_MAX_LENGTH

The maximum length a button label can have

See Also:

Constant Field Values

ID_MAX_LENGTH

static final int ID_MAX_LENGTH

The maximum length a button id can have

See Also:

Constant Field Values

URL_MAX_LENGTH

static final int URL_MAX_LENGTH

The maximum length a button url can have

See Also:

Constant Field Values

Method Detail

getLabel

@Nonnull
java.lang.String getLabel()

The visible text on the button.

Returns:

The button label

getStyle

@Nonnull
ButtonStyle getStyle()

The style of this button.

Returns:

ButtonStyle

getUrl

@Nullable
java.lang.String getUrl()

The target URL for this button, if it is a LINK-Style Button.

Returns:

The target URL or null

getEmoji

@Nullable
Emoji getEmoji()

The emoji attached to this button.
This can be either unicode or Emoji.isCustom() custom.

You can use withEmoji(Emoji) to create a button with an Emoji.

Returns:

Emoji for this button

isDisabled

boolean isDisabled()

Whether this button is disabled.

You can use asDisabled() or asEnabled() to create enabled/disabled instances.

Returns:

True, if this button is disabled

asDisabled

@Nonnull
@CheckReturnValue
default Button asDisabled()

Returns a copy of this button with isDisabled() set to true.

Returns:

New disabled button instance

asEnabled

@Nonnull
@CheckReturnValue
default Button asEnabled()

Returns a copy of this button with isDisabled() set to false.

Returns:

New enabled button instance

withDisabled

@Nonnull
@CheckReturnValue
default Button withDisabled(boolean disabled)

Returns a copy of this button with isDisabled() set to the provided value.

Parameters:

disabled - True, if this button should be disabled

Returns:

New enabled/disabled button instance

withEmoji

@Nonnull
@CheckReturnValue
default Button withEmoji(@Nullable
                         Emoji emoji)

Returns a copy of this button with the attached Emoji.

Parameters:

emoji - The emoji to use

Returns:

New button with emoji

withLabel

@Nonnull
@CheckReturnValue
default Button withLabel(@Nonnull
                         java.lang.String label)

Returns a copy of this button with the provided label.

Parameters:

label - The label to use

Returns:

New button with the changed label

Throws:

java.lang.IllegalArgumentException -

• If the provided label is null or empty.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

withId

@Nonnull
@CheckReturnValue
default Button withId(@Nonnull
                      java.lang.String id)

Returns a copy of this button with the provided id.

Parameters:

id - The id to use

Returns:

New button with the changed id

Throws:

java.lang.IllegalArgumentException -

• If the provided id is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.

withUrl

@Nonnull
@CheckReturnValue
default Button withUrl(@Nonnull
                       java.lang.String url)

Returns a copy of this button with the provided url.

Parameters:

url - The url to use

Returns:

New button with the changed url

Throws:

java.lang.IllegalArgumentException -

• If the provided url is null or empty.
• If the character limit for url, defined by URL_MAX_LENGTH as 512, is exceeded.

withStyle

@Nonnull
@CheckReturnValue
default Button withStyle(@Nonnull
                         ButtonStyle style)

Returns a copy of this button with the provided style.

You cannot use this convert link buttons.

Parameters:

style - The style to use

Returns:

New button with the changed style

Throws:

java.lang.IllegalArgumentException -

• If the provided style is null.
• If the provided style tries to change whether this button is a LINK button.

primary

@Nonnull
static Button primary(@Nonnull
                      java.lang.String id,
                      @Nonnull
                      java.lang.String label)

Creates a button with PRIMARY Style.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

Parameters:

id - The custom button ID

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

primary

@Nonnull
static Button primary(@Nonnull
                      java.lang.String id,
                      @Nonnull
                      Emoji emoji)

Creates a button with PRIMARY Style.
The button is enabled and has no text label. To use labels you can use primary(id, label).withEmoji(emoji)

To disable the button you can use asDisabled().

Parameters:

id - The custom button ID

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.

secondary

@Nonnull
static Button secondary(@Nonnull
                        java.lang.String id,
                        @Nonnull
                        java.lang.String label)

Creates a button with SECONDARY Style.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

Parameters:

id - The custom button ID

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

secondary

@Nonnull
static Button secondary(@Nonnull
                        java.lang.String id,
                        @Nonnull
                        Emoji emoji)

Creates a button with SECONDARY Style.
The button is enabled and has no text label. To use labels you can use secondary(id, label).withEmoji(emoji)

To disable the button you can use asDisabled().

Parameters:

id - The custom button ID

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.

success

@Nonnull
static Button success(@Nonnull
                      java.lang.String id,
                      @Nonnull
                      java.lang.String label)

Creates a button with SUCCESS Style.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

Parameters:

id - The custom button ID

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

success

@Nonnull
static Button success(@Nonnull
                      java.lang.String id,
                      @Nonnull
                      Emoji emoji)

Creates a button with SUCCESS Style.
The button is enabled and has no text label. To use labels you can use success(id, label).withEmoji(emoji)

To disable the button you can use asDisabled().

Parameters:

id - The custom button ID

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.

danger

@Nonnull
static Button danger(@Nonnull
                     java.lang.String id,
                     @Nonnull
                     java.lang.String label)

Creates a button with DANGER Style.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

Parameters:

id - The custom button ID

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

danger

@Nonnull
static Button danger(@Nonnull
                     java.lang.String id,
                     @Nonnull
                     Emoji emoji)

Creates a button with DANGER Style.
The button is enabled and has no text label. To use labels you can use danger(id, label).withEmoji(emoji)

To disable the button you can use asDisabled().

Parameters:

id - The custom button ID

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for id, defined by ID_MAX_LENGTH as 100, is exceeded.

link

@Nonnull
static Button link(@Nonnull
                   java.lang.String url,
                   @Nonnull
                   java.lang.String label)

Creates a button with LINK Style.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

Note that link buttons never send a ButtonClickEvent. These buttons only open a link for the user.

Parameters:

url - The target URL for this button

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for url, defined by URL_MAX_LENGTH as 512, is exceeded.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

link

@Nonnull
static Button link(@Nonnull
                   java.lang.String url,
                   @Nonnull
                   Emoji emoji)

Creates a button with LINK Style.
The button is enabled and has no text label. To use labels you can use link(url, label).withEmoji(emoji)

To disable the button you can use asDisabled().

Note that link buttons never send a ButtonClickEvent. These buttons only open a link for the user.

Parameters:

url - The target URL for this button

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the character limit for url, defined by URL_MAX_LENGTH as 512, is exceeded.

of

@Nonnull
static Button of(@Nonnull
                 ButtonStyle style,
                 @Nonnull
                 java.lang.String idOrUrl,
                 @Nonnull
                 java.lang.String label)

Create a button with the provided style, URL or ID, and label.
The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

See link(String, String) or primary(String, String) for more details.

Parameters:

style - The button style

idOrUrl - Either the ID or URL for this button

label - The text to display on the button

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the id is longer than 100, as defined by ID_MAX_LENGTH.
• If the url is longer than 512, as defined by URL_MAX_LENGTH.
• If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.

of

@Nonnull
static Button of(@Nonnull
                 ButtonStyle style,
                 @Nonnull
                 java.lang.String idOrUrl,
                 @Nonnull
                 Emoji emoji)

Create a button with the provided style, URL or ID, and emoji.
The button is enabled and has no text label. To use labels you can use of(style, idOrUrl, label).withEmoji(emoji)

See link(String, Emoji) or primary(String, Emoji) for more details.

Parameters:

style - The button style

idOrUrl - Either the ID or URL for this button

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException -

• If any provided argument is null or empty.
• If the id is longer than 100, as defined by ID_MAX_LENGTH.
• If the url is longer than 512, as defined by URL_MAX_LENGTH.

of

@Nonnull
static Button of(@Nonnull
                 ButtonStyle style,
                 @Nonnull
                 java.lang.String idOrUrl,
                 @Nullable
                 java.lang.String label,
                 @Nullable
                 Emoji emoji)

Create an enabled button with the provided style, URL or ID, label and emoji.

You can use asDisabled() to disable it.

See link(String, String) or primary(String, String) for more details.

Parameters:

style - The button style

idOrUrl - Either the ID or URL for this button

label - The text to display on the button

emoji - The emoji to use as the button label

Returns:

The button instance

Throws:

java.lang.IllegalArgumentException - If any of the following scenarios occurs:

• The style is null
• You provide a URL that is null, empty or longer than 512 characters, as defined by URL_MAX_LENGTH or you provide an ID that is null, empty or longer than 100 characters, as defined by ID_MAX_LENGTH.
• The label is non-null and longer than 80 characters, as defined by LABEL_MAX_LENGTH.
• The label is null/empty, and the emoji is also null.