API reference
Modals
Open a pop-up form, then read what the member typed.
A modal is a pop-up form in Discord. It has a title and up to 5 text boxes. You open it in answer to a command or a click. When the member presses Submit, a Modal Submit event runs with what they typed.
For a walk-through, read Forms.
ModalBuilder#
Makes an empty form.
form = ModalBuilder(title, custom_id)| Argument | What it does |
|---|---|
title | The text at the top of the form. |
custom_id | The name the submit carries. Your Modal Submit event listens for it. |
add_text_input#
Adds a text box. Each box gets its own row.
form.add_text_input(
name,
label,
style="short",
placeholder=...,
value=...,
required=True,
min_length=0,
max_length=4000,
)| Argument | What it does |
|---|---|
name | The key for this box in values. |
label | The text above the box. |
style | "short": one line. "long": a big box for many lines. |
placeholder | Grey hint text in the empty box. |
value | Text already filled in. |
required | False lets the member leave it empty. |
min_length, max_length | The shortest and longest answer allowed. |
send_modal#
Opens the form. Needs await.
await send_modal(form) # from a command or a component handler
await send_modal(form, interaction) # from a View button or menuOpening the form is the answer to the command or click. Do not defer before it.
Slash commands: turn off Show thinking
A slash command answers Discord at once when Show "thinking…" is on. Then a form can no longer open. Turn it off under Behavior on the command.
Inside a View
Pass the click as the second argument: send_modal(form, interaction). With one argument the form answers the command, which is already answered, and Discord refuses it.
Example: a feedback command
# pre-hook of /feedback, with Show "thinking…" turned off
form = ModalBuilder(title="Send feedback", custom_id="feedback-form")
form.add_text_input("topic", "Topic", placeholder="Bug, idea, other…")
form.add_text_input("details", "Tell us more", style="long", max_length=1000)
await send_modal(form)values#
In a Modal Submit event, values is a dictionary. Each key is a box name. Each value is what the member typed.
# Modal Submit event, custom ID: feedback-form
await defer_response(ephemeral=True)
send_message("feedback", f"**{values['topic']}** from {user.mention}\n{values['details']}")
await respond_interaction(interaction, "Thanks! We got your feedback.")An empty optional box gives "".
get_modal_values#
Reads the answers from a submit, as the same dictionary as values.
get_modal_values(interaction)You only need it when you have a submit outside a Modal Submit event, for example one you got from wait_for("modal_submit").