Interface Button

All Superinterfaces:
ActionComponent, ActionRowChildComponent, Component, ICustomId, IDisableable, SectionAccessoryComponent

Represents a Message Button.

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

Example Usage

public class HelloBot extends ListenerAdapter {
  public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
      if (event.getName().equals("hello")) {
          event.reply("Click the button to say hello")
              .addComponents(
                ActionRow.of(
                  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")
              .addComponents(
                  ActionRow.of(
                    // link buttons don't send events, they just open a link in the browser when clicked
                    Button.link("https://github.com/discord-jda/JDA", "GitHub")
                      .withEmoji(Emoji.fromMarkdown("<:github:849286315580719104>")), // Link Button with label and emoji
                    Button.link("https://docs.jda.wiki/", "Javadocs"))) // Link Button with only a label
              .queue();
      }
  }

  public void onButtonInteraction(ButtonInteractionEvent event) {
      if (event.getComponentId().equals("hello")) {
          event.reply("Hello :)").queue();
      }
  }
}
To see what each button looks like here is an example cheatsheet:
ButtonExample
See Also:
  • Field Details

    • LABEL_MAX_LENGTH

      static final int LABEL_MAX_LENGTH
      The maximum length a button label can have
      See Also:
    • ID_MAX_LENGTH

      static final int ID_MAX_LENGTH
      The maximum length a button id can have
      See Also:
    • URL_MAX_LENGTH

      static final int URL_MAX_LENGTH
      The maximum length a button url can have
      See Also:
  • Method Details

    • getLabel

      @Nonnull String getLabel()
      The visible text on the button, or an empty string if this is a PREMIUM-style button.
      Returns:
      The button label
    • getStyle

      @Nonnull ButtonStyle getStyle()
      The style of this button.
      Returns:
      ButtonStyle
    • getUrl

      @Nullable String getUrl()
      The target URL for this button, if it is a LINK-Style Button.
      Returns:
      The target URL or null
    • getSku

      @Nullable SkuSnowflake getSku()
      The target SKU for this button, if it is a PREMIUM-style Button.
      Returns:
      The target SKU or null
    • getEmoji

      @Nullable EmojiUnion getEmoji()
      The emoji attached to this button.
      This can be either unicode or custom.

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

      Returns:
      Emoji for this button
    • asDisabled

      @Nonnull @CheckReturnValue default Button asDisabled()
      Description copied from interface: ActionComponent
      Returns a copy of this component with ActionComponent.isDisabled() set to true.

      Note: Components in modals cannot be disabled.

      Specified by:
      asDisabled in interface ActionComponent
      Specified by:
      asDisabled in interface IDisableable
      Returns:
      New disabled component instance
      See Also:
    • asEnabled

      @Nonnull @CheckReturnValue default Button asEnabled()
      Description copied from interface: ActionComponent
      Returns a copy of this component with ActionComponent.isDisabled() set to false.
      Specified by:
      asEnabled in interface ActionComponent
      Specified by:
      asEnabled in interface IDisableable
      Returns:
      New enabled component instance
      See Also:
    • withDisabled

      @Nonnull @CheckReturnValue default Button withDisabled(boolean disabled)
      Description copied from interface: ActionComponent
      Returns a copy of this component with ActionComponent.isDisabled() set to the provided value.

      Note: Components in modals cannot be disabled.

      Specified by:
      withDisabled in interface ActionComponent
      Specified by:
      withDisabled in interface IDisableable
      Parameters:
      disabled - True, if this component should be disabled
      Returns:
      New enabled/disabled component instance
      See Also:
    • 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
      Throws:
      IllegalArgumentException - If this is a PREMIUM-styled button
    • withLabel

      @Nonnull @CheckReturnValue default Button withLabel(@Nonnull 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:
      IllegalArgumentException -
      • If this is a PREMIUM-styled button
      • If the provided label is null or empty.
      • If the character limit for label, defined by LABEL_MAX_LENGTH as 80, is exceeded.
    • withCustomId

      @Nonnull @CheckReturnValue default Button withCustomId(@Nonnull String customId)
      Returns a copy of this button with the provided custom id.
      Parameters:
      customId - The custom id to use
      Returns:
      New button with the changed custom id
      Throws:
      IllegalArgumentException -
      • If this is a LINK-styled or PREMIUM-styled button
      • If the provided customId is null or empty.
      • If the character limit for customId, defined by ID_MAX_LENGTH as 100, is exceeded.
    • withUniqueId

      @Nonnull @CheckReturnValue default Button withUniqueId(int uniqueId)
      Description copied from interface: Component
      Creates a new component with the provided numeric ID.
      If no ID is set, Discord will generate IDs incrementally starting from 1 and will not use existing IDs from the same message/modal.
      Specified by:
      withUniqueId in interface ActionComponent
      Specified by:
      withUniqueId in interface ActionRowChildComponent
      Specified by:
      withUniqueId in interface Component
      Specified by:
      withUniqueId in interface ICustomId
      Specified by:
      withUniqueId in interface IDisableable
      Specified by:
      withUniqueId in interface SectionAccessoryComponent
      Parameters:
      uniqueId - The new ID; must be higher or equal to 1
      Returns:
      The new component
    • withUrl

      @Nonnull @CheckReturnValue default Button withUrl(@Nonnull 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:
      IllegalArgumentException -
      • If this is not a LINK-styled button
      • If the provided url is null or empty.
      • If the character limit for url, defined by URL_MAX_LENGTH as 512, is exceeded.
    • withSku

      @Nonnull @CheckReturnValue default Button withSku(@Nonnull SkuSnowflake sku)
      Returns a copy of this button with the provided SKU.
      Parameters:
      sku - The SKU to use
      Returns:
      New button with the changed url
      Throws:
      IllegalArgumentException - If the provided sku is null, or if the button is not a PREMIUM button
    • 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:
      IllegalArgumentException -
      • If the provided style is null.
      • If the provided style tries to change whether this button is a LINK or PREMIUM button.
    • primary

      @Nonnull static Button primary(@Nonnull String id, @Nonnull 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:
      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 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:
      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 String id, @Nonnull 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:
      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 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:
      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 String id, @Nonnull 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:
      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 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:
      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 String id, @Nonnull 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:
      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 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:
      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 String url, @Nonnull 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 ButtonInteractionEvent. 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:
      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 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 ButtonInteractionEvent. 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:
      IllegalArgumentException -
      • If any provided argument is null or empty.
      • If the character limit for url, defined by URL_MAX_LENGTH as 512, is exceeded.
    • premium

      @Nonnull static Button premium(@Nonnull SkuSnowflake sku)
      Creates a button with PREMIUM Style.
      The button is enabled by default, and cannot have emojis attached to it. You can use asDisabled() to further configure it.

      Note that premium buttons never send a ButtonInteractionEvent. These buttons only open a modal about the SKU.

      Parameters:
      sku - The target SKU for this button
      Returns:
      The button instance
      Throws:
      IllegalArgumentException - If the provided SKU is null
    • of

      @Nonnull static Button of(@Nonnull ButtonStyle style, @Nonnull String idOrUrl, @Nonnull 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.

      This does not support premium buttons, use of(ButtonStyle, String, String, Emoji) instead.

      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:
      IllegalArgumentException -
    • of

      @Nonnull static Button of(@Nonnull ButtonStyle style, @Nonnull 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)

      This does not support premium buttons, use of(ButtonStyle, String, String, Emoji) instead.

      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:
      IllegalArgumentException -
    • of

      @Nonnull static Button of(@Nonnull ButtonStyle style, @Nonnull String idOrUrlOrSku, @Nullable 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), premium(SkuSnowflake) or primary(String, String) for more details.

      Parameters:
      style - The button style
      idOrUrlOrSku - Either the ID, URL, or SKU 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:
      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.
      • A label or emoji was provided for a PREMIUM-style button