API reference
Components
Buttons and menus that keep working after the command ends. Build them with ComponentBuilder.
ComponentBuilder makes rows of buttons and menus. Unlike a View, its buttons keep working after the command has finished. Use it for panels that people click for days, like a ticket panel or a role menu.
A click goes to one of two places:
| You set | The click runs |
|---|---|
| nothing | A Button Click / Select Menu Change event on the dashboard whose custom IDs include this button's custom_id. |
on_click or on_select | Your own function, in this script. |
Read Buttons and menus to choose between a View and a component.
ComponentBuilder#
Makes an empty builder.
c = ComponentBuilder(interaction=None)Pass interaction when you use private=True. Then send the builder with set_components(c), or send_message(channel, ..., components=c).
c = ComponentBuilder()
c.add_button("Open a ticket", style="primary", custom_id="ticket-open")
c.add_link_button("Rules", "https://example.com/rules")
send_message("support", "Need help? Press the button.", components=c)Then make an event on the dashboard: Create → Event, type Button Click / Select Menu Change, custom ID ticket-open. Its code runs on every click.
add_button#
Adds a button.
c.add_button(
label,
style="primary",
emoji=...,
is_disabled=False,
custom_id=None,
on_click=None,
row=None,
private=False,
)| Argument | What it does |
|---|---|
label | The button text. |
style | primary, secondary, success or danger. |
emoji | An emoji on the button. Leave it out for none. |
custom_id | The name the click carries. Needed for every button that is not a link. |
on_click | A ComponentAction to run on click. |
row | Which row to put it in. Default is the current row. |
private | True: only the member who ran the command can click. |
add_link_button#
Adds a button that opens a website. Link buttons never run code.
c.add_link_button(label, url, emoji=..., is_disabled=False, row=None)add_text_menu#
Adds a menu with your own options.
c.add_text_menu(
options,
custom_id=None,
placeholder=...,
min_values=0,
max_values=1,
is_disabled=False,
on_select=None,
row=None,
private=False,
)options is a list of TextOption(label, value, description=..., emoji=..., default=False).
add_role_menu#
Adds a menu that lists the server's roles.
c.add_role_menu(custom_id=None, placeholder=..., min_values=0, max_values=1,
is_disabled=False, on_select=None, row=None, private=False)add_user_menu#
Adds a menu that lists members. Same arguments as add_role_menu.
add_channel_menu#
Adds a menu that lists channels. The first argument is a list of channel types: text, voice, category, news, news-thread, public-thread, private-thread, forum, stage.
c.add_channel_menu(["text", "voice"], custom_id="pick-channel")add_row#
Starts a new row. Later buttons go into it.
c.add_row(row)
c.remove_row(row)Rules: at most 5 rows, at most 5 buttons in a row, and a menu takes a whole row.
ComponentAction#
Runs your own function when the button or menu is used.
ComponentAction(
type,
ephemeral,
callback,
clickable=0,
clicked=0,
auto_defer=True,
args=[],
)| Argument | What it does |
|---|---|
type | "create": the answer is a new message. "update": the answer changes the message with the button. |
ephemeral | True: the new message is visible to the clicker only. |
callback | Your function. |
clickable | How many clicks in total are allowed. 0 means no limit. |
auto_defer | True: the bot answers the click for you before the callback runs. |
args | Extra values passed to your function. |
A button's callback gets (interaction, *args). A menu's callback gets (interaction, values, *args).
async def claim(interaction):
add_roles(interaction.member, "Early Bird")
await respond_interaction(interaction, "You got the Early Bird role!")
c = ComponentBuilder()
c.add_button("Claim", custom_id="claim-early",
on_click=ComponentAction("create", True, claim, clickable=10))
set_components(c)on_click lives in memory
An on_click function is kept in the bot's memory. After the bot restarts, the button no longer runs it. For panels that must work for weeks, use a dashboard event instead.
Button#
Makes one button on its own, outside a builder.
Button(label, style="primary", emoji=..., is_disabled=False, custom_id=None)LinkButton#
Makes one link button on its own.
LinkButton(label, url, emoji=..., is_disabled=False)Newer layout parts#
Discord's newer message layout uses these parts: TextDisplay, Section, Thumbnail, MediaGallery, Container, Separator, File, Spacing and Color. They are passed straight to Discord, so they follow Discord's own rules.
For most messages, it is easier to design the layout on the dashboard under Components, then load it with load_components.