Skip to content

Using Message Components

This guide explains how to work with the disagreement message component models. These examples are up to date with the current code base.

Enabling the New Component System

Messages that use the component system must include the flag IS_COMPONENTS_V2 (value 1 << 15). Once this flag is set on a message it cannot be removed.

Component Categories

The library exposes three broad categories of components:

  • Layout Components – organize the placement of other components.
  • Content Components – display static text or media.
  • Interactive Components – allow the user to interact with your message.

Action Row

ActionRow is a layout container. It may hold up to five buttons or a single select menu.

from disagreement import ActionRow, Button, ButtonStyle

row = ActionRow(components=[
    Button(style=ButtonStyle.PRIMARY, label="Click", custom_id="btn")
])

Button

Buttons provide a clickable UI element.

from disagreement import Button, ButtonStyle

button = Button(
    style=ButtonStyle.SUCCESS,
    label="Confirm",
    custom_id="confirm_button",
)

Select Menus

SelectMenu lets the user choose one or more options. The type parameter controls the menu variety (STRING_SELECT, USER_SELECT, ROLE_SELECT, MENTIONABLE_SELECT, CHANNEL_SELECT).

from disagreement import SelectMenu, SelectOption, ComponentType, ChannelType

menu = SelectMenu(
    custom_id="example",
    options=[
        SelectOption(label="Option 1", value="1"),
        SelectOption(label="Option 2", value="2"),
    ],
    placeholder="Choose an option",
    min_values=1,
    max_values=1,
    type=ComponentType.STRING_SELECT,
)

For channel selects you may pass channel_types with a list of allowed ChannelType values.

Section

Section groups one or more TextDisplay components and can include an accessory Button or Thumbnail.

from disagreement import Section, TextDisplay, Thumbnail, UnfurledMediaItem

section = Section(
    components=[
        TextDisplay(content="## Section Title"),
        TextDisplay(content="Sections can hold multiple text displays."),
    ],
    accessory=Thumbnail(media=UnfurledMediaItem(url="https://example.com/img.png")),
)

Text Display

TextDisplay simply renders markdown text.

from disagreement import TextDisplay

text_display = TextDisplay(content="**Bold text**")

Thumbnail

Thumbnail shows a small image. Set spoiler=True to hide the image until clicked.

from disagreement import Thumbnail, UnfurledMediaItem

thumb = Thumbnail(
    media=UnfurledMediaItem(url="https://example.com/image.png"),
    description="A picture",
    spoiler=False,
)

MediaGallery holds multiple MediaGalleryItem objects.

from disagreement import MediaGallery, MediaGalleryItem, UnfurledMediaItem

gallery = MediaGallery(
    items=[
        MediaGalleryItem(media=UnfurledMediaItem(url="https://example.com/1.png")),
        MediaGalleryItem(media=UnfurledMediaItem(url="https://example.com/2.png")),
    ]
)

File

File displays an uploaded file. Use spoiler=True to mark it as a spoiler.

from disagreement import File, UnfurledMediaItem

file_component = File(
    file=UnfurledMediaItem(url="attachment://file.zip"),
    spoiler=False,
)

Separator

Separator adds vertical spacing or an optional divider line between components.

from disagreement import Separator

separator = Separator(divider=True, spacing=2)

Container

Container visually groups a set of components and can apply an accent colour or spoiler.

from disagreement import Container, TextDisplay

container = Container(
    components=[TextDisplay(content="Inside a container")],
    accent_color="#FF0000",  # int or Color() also work
    spoiler=False,
)

A container can itself contain layout and content components, letting you build complex messages.

Persistent Views

Views with timeout=None are persistent. Their custom_id components are saved to persistent_views.json so they survive bot restarts.

class MyView(View):
    @button(label="Press", custom_id="press")
    async def handle(self, view, inter):
        await inter.respond("Pressed!")

client.add_persistent_view(MyView())

When the client starts, it loads this file and registers each view again. Remove the file to clear stored views.

Next Steps