@spec checkbox(
  String.t(),
  keyword()
) :: map()

Creates a single checkbox for use inside label/3 (type 23).

The submitted value is true or false. A checkbox cannot be required; for a box that must be ticked, use a checkbox_group/3 with one option.

Options

• :default — whether it starts ticked

Example

label("Subscribe to updates", checkbox("subscribe", default: true))

@spec checkbox_group(String.t(), [map()], keyword()) :: map()

Creates a checkbox group for use inside label/3 (type 22): any number of choices among 1–10.

The submitted value is the list of chosen values, empty when none is ticked.

Options

• :min_values — minimum choices (0–10, Discord defaults to 1)
• :max_values — maximum choices (1–10, Discord defaults to the number of options)
• :required — whether a choice is needed to submit (Discord defaults to true)

:min_values of 0 needs required: false.

Example

label("Free days", checkbox_group("days", [choice("Monday", "mon"), choice("Friday", "fri")]))

@spec choice(String.t(), String.t(), keyword()) :: map()

Creates an option for radio_group/3 or checkbox_group/3.

Options

• :description — shown under the label (max 100 chars)
• :default — whether the option starts selected

Example

choice("Warrior", "warrior", description: "Strong and brave")

@spec file_upload(
  String.t(),
  keyword()
) :: map()

Creates a file upload for use inside label/3 (type 19).

The user can attach 0 to 10 files; each is limited by the user's own upload limit in the channel. The submitted files arrive as attachments — see get_attachments/2.

Options

• :min_values — minimum number of files (0–10, Discord defaults to 1)
• :max_values — maximum number of files (1–10, Discord defaults to 1)
• :required — whether a file must be attached to submit (Discord defaults to true)
• :file_types — up to 10 filters: :image, :video, :audio, or a dot-prefixed extension such as ".pdf". See EDA.FileType: the filter matches the extension only and never inspects the file, so it does not replace checking what was actually uploaded.

:min_values of 0 needs required: false; Discord refuses the combination otherwise.

Example

label("Screenshots", file_upload("shots", max_values: 5, file_types: [:image]))

@spec get_attachments(map(), String.t()) :: [EDA.Attachment.t()]

Returns the files a file_upload/2 received, as EDA.Attachment structs, in upload order.

Returns [] when the component is absent or nothing was uploaded.

Example

for file <- EDA.Modal.get_attachments(interaction, "evidence") do
  {file.filename, file.url}
end

@spec get_value(map(), String.t(), term()) :: term()

Extracts a single value from a MODAL_SUBMIT interaction by custom_id.

Returns default (nil unless given) when the modal has no such component. See get_values/1 for the shape of each value.

Example

subject = EDA.Modal.get_value(interaction, "subject")

@spec get_values(map()) :: %{required(String.t()) => term()}

Extracts all submitted values from a MODAL_SUBMIT interaction, by custom_id.

Each value has the shape of its component:

• text field — the text, a string
• select, checkbox group — the chosen values, a list of strings (ids for user, role, mentionable and channel selects)
• file upload — the attachment ids, a list of strings; get_attachments/2 returns the files
• radio group — the chosen value, or nil
• checkbox — true or false

Example

EDA.Modal.get_values(interaction)
# => %{"subject" => "Bug report", "platform" => ["windows"], "agree" => true}

@spec label(String.t(), map(), keyword()) :: map()

Wraps a modal component with a label and an optional description (type 18).

Every interactive component in a modal sits in a label. The label text is at most 45 characters, the description at most 100; Discord shows the description above or below the component depending on the platform.

A text input built with text_input/4 carries a label of its own, which Discord deprecates inside a label; use text_field/3 here instead.

Options

• :description — hint text for the field (max 100 chars)
• :id — optional numeric identifier for the component

Example

label("Your name", text_field("name", :short))
label("Favourite colour", string_select("colour", options), description: "Pick one")

@spec modal(
  String.t(),
  String.t(),
  [map()] | map(),
  map() | nil,
  map() | nil,
  map() | nil,
  map() | nil
) :: map()

Creates a modal from its top-level components.

components is a list of 1–5 label/3 and EDA.Component.text_display/1 components. Text inputs from text_input/4 are also accepted, each wrapped in an action row as before.

The older positional form, modal(custom_id, title, input1, ..., input5), still works.

Example

modal("survey", "Quick Survey", [
  label("Favourite colour?", text_field("q1", :short)),
  label("Why?", text_field("q2", :paragraph, required: false))
])

@spec modal_from_list(String.t(), String.t(), [map()]) :: map()

Creates a modal from a list of components. Same as modal/3 with a list.

modal_from_list("profile", "Edit Profile", [
  label("Name", text_field("name", :short)),
  label("Bio", text_field("bio", :paragraph))
])

@spec radio_group(String.t(), [map()], keyword()) :: map()

Creates a radio group for use inside label/3 (type 21): exactly one choice among 2–10.

At most one option may start selected. The submitted value is the chosen option's value, or nil when the group is optional and left empty.

Options

• :required — whether a choice is needed to submit (Discord defaults to true)

Example

label("Class", radio_group("class", [choice("Warrior", "warrior"), choice("Rogue", "rogue")]))

@spec text_field(String.t(), :short | :paragraph, keyword()) :: map()

Creates a text input for use inside label/3 (type 4).

The label and description belong to the label/3 around it.

Options

• :placeholder — hint text when empty (max 100 chars)
• :min_length — minimum input length (0–4000)
• :max_length — maximum input length (1–4000)
• :required — whether the field must be filled (Discord defaults to true)
• :value — pre-filled text (max 4000 chars)

Example

label("About you", text_field("bio", :paragraph, max_length: 1000, required: false))

@spec text_input(String.t(), String.t(), :short | :paragraph, keyword()) :: map()

Creates a text input carrying its own label, for the action-row form of modal/3..7.

Discord no longer recommends this form; label/3 around text_field/3 replaces it and can also hold the other modal components.

Parameters

• custom_id — unique identifier for this field (1–100 chars)
• label — label displayed above the input (max 45 chars)
• style — :short (single line) or :paragraph (multi-line)

Options

Those of text_field/3.

Example

text_input("name", "Your Name", :short, placeholder: "John Doe")
text_input("bio", "About You", :paragraph, required: false, max_length: 1000)