feat: components v2 #1294

shiftinv · 2025-04-18T17:21:41Z

Summary

First off, this isn't quite finished, as evidenced by the fact that this is marked as a draft PR and the numerous TODOs scattered across the code, but still very much usable in its current state (once the experiment lock gets removed for everyone).
Most of the remaining changes are quality-of-life/DX improvements. I consider the interface fairly stable at this point, don't expect many further changes there.
It would probably make sense to wait a little longer with any reviews though, unless it's some glaring issue.

Description

discord/discord-api-docs@af1843d

This implements the new v2 components, including:

Section: displays a thumbnail or button next to some text
TextDisplay: plaintext, but as a component
MediaGallery: gallery/mosaic for up to 10 images
File: non-image attachments
Separator: vertical spacer/separator
Container: can be considered similar to an Embed

These new components are all non-interactive and intended for layout only, they are quite a bit more flexible than the previous content/embeds/attachments/components combo, and allow for much nicer looking/better structured messages.

Scope

I feel like it's worth clarifying that this is about as straightforward as the interface could be, only building on the existing implementation/functionality for components. There may very well be better ways (in terms of DX) to implement these components (namely, builder pattern, yippee), but I've considered this out of scope from the start.
I've intentionally not implemented support for the new components in Views, given the intended scope of this PR and the complexities that somehow integrating them would bring, especially since all of the components are non-interactive.
The goal with this PR was to get just about the most basic implementation going, any further work building on top of it will be in separate future PRs.

Example

code

(consider MediaGalleryItem unfinished, it is largely a placeholder implementation for now)

components: Sequence[ui.UIComponent] = [
    ui.TextDisplay("test"),
    ui.Separator(),
    ui.Container(
        ui.TextDisplay("this is text inside a container"),
        ui.MediaGallery(
            disnake.MediaGalleryItem(
                {
                    "media": {"url": "https://placecats.com/500/600"},
                    "description": "a cool media item",
                },
            ),
            disnake.MediaGalleryItem(
                {
                    "media": {"url": "https://placecats.com/800/600"},
                    "description": "more kitty",
                    "spoiler": True,
                },
            ),
        ),
        ui.Section(
            ui.TextDisplay(
                "What an incredible media gallery.\nOkay, that's all the time I've got. I got to get back to playing Animal Crossing New Leaf on my Nintendo 3DS."
            ),
            accessory=ui.Thumbnail(
                media={
                    "url": "https://i.kym-cdn.com/entries/icons/facebook/000/026/585/reggie_animalcrossingtour.jpg"
                },
                description="desc",
            ),
        ),
        ui.Separator(spacing=disnake.SeparatorSpacingSize.large),
        ui.ActionRow(disnake.ui.ChannelSelect(placeholder="Choose a Channel!")),
        accent_colour=disnake.Colour(0xEE99CC),
        spoiler=False,
    ),
]

await inter.response.send_message(components=components, flags=disnake.MessageFlags(is_components_v2=True))

Checklist

If code changes were made, then they have been tested
- I have updated the documentation to reflect the changes
- I have formatted the code properly by running pdm lint
- I have type-checked the code by running pdm pyright
This PR fixes an issue
This PR adds something new (e.g. new method or parameters)
This PR is a breaking change (e.g. methods or parameters removed/renamed)
This PR is not a code change (e.g. documentation, README, ...)

…t` for now to avoid shadowing

…omponent` more specific

…nRow`s

…type

… components

…cut types

…rows`

Enegg · 2025-04-23T21:14:11Z

disnake/ui/_types.py

What's the idea behind suffixing the types with Input?
I think it's a bit of a misnomer given only buttons/selects can be used for actual "input"
I'd say MessageComponentInput => MessageComponent sounds better, wdyt?

Could definitely rename it, it was mostly a decision made on a whim. c:
The [...]Input part of the type name was meant to signify that it's moreso a MessageComponent-like thing, ie. a single component, a list of action rows, a list of buttons and selects, etc etc, instead of only a single component like MessageComponent might suggest(?)
The library internally transforms these shortcuts into the "list of action rows" structure the API would expect (for components v1, at least). But yea, I'll gladly rename these type aliases if we can come up with a more fitting name.

I think just having it plural, like components: MessageComponents would be good enough
Alternatively, components: abc.Sequence[MessageComponent(s)] to better drive the fact it's always a sequence (unless we want to support singular components?)

(unless we want to support singular components?)

For now, stuff like .send(components=Button()) is supposed to work, yea.

MessageComponents (and the corresponding ModalComponents) seems good though, I've renamed those in a8fb923.

Enegg

bnuuy

disnake/interactions/message.py

Enegg · 2025-04-26T04:36:40Z

disnake/ui/_types.py

I think just having it plural, like components: MessageComponents would be good enough
Alternatively, components: abc.Sequence[MessageComponent(s)] to better drive the fact it's always a sequence (unless we want to support singular components?)

disnake/ui/container.py

disnake/ui/file.py

Enegg · 2025-04-26T04:44:06Z

disnake/ui/file.py

+    file: Any
+        n/a


I think this should work for existing Attachments, since really this only needs a url

Enegg · 2025-04-26T05:24:31Z

disnake/components.py

+
+    __slots__: Tuple[str, ...] = ("accessory", "components")
+
+    __repr_info__: ClassVar[Tuple[str, ...]] = __slots__


Hmm, Component has .__repr_info__, but .ui.UIComponent has .__repr_attributes__. Is this desirable?
(I suggest we use the same class variable name everywhere)

Hm, good point 🤔
I'd say __repr_attributes__ sounds more accurate? *_info could mean anything, really. Both app commands and non-ui components use the latter, though we'd want to rename those in a separate PR to keep the scope somewhat concise in this PR

disnake/components.py

Enegg · 2025-04-26T05:31:28Z

disnake/components.py

+
+def _walk_internal(component: Component, seen: Set[Component]) -> Iterator[Component]:
+    if component in seen:
+        # prevent infinite recursion if anyone manages to nest a component in itself


What it actually does is skipping a component that has already been referenced.
That's not exactly the same as recursion, as a component could be reused between different containers/rows
It is an error if the component has a custom_id/id set, but for non-interactive components with omitted id it's technically fine

good catch, thanks! This should work a little better: 7bee2ce

disnake/components.py

cwmet · 2025-06-02T12:31:51Z

components = [
        ui.Container(
            ui.TextDisplay("this is text inside a container"),
            ui.MediaGallery(
                disnake.MediaGalleryItem(
                    {
                        "media": {"url": "https://placecats.com/500/600"},
                        "description": "a cool media item",
                    },
                ),
                disnake.MediaGalleryItem(
                    {
                        "media": {"url": "https://placecats.com/800/600"},
                        "description": "more kitty",
                        "spoiler": True,
                    },
                ),
            ),
            ui.Separator(spacing=disnake.SeparatorSpacingSize.large),
            ui.ActionRow(ui.ChannelSelect(placeholder="Choose a Channel!")),
        ),
    ]

    await inter.response.send_message(components=components, flags=disnake.MessageFlags(is_components_v2=True))

disnake\ui\item.py", line 48, in ensure_ui_component
    raise TypeError(f"{name} should be a valid UI component, got {type(obj).__name__}.")
TypeError: components should be a valid UI component, got ActionRow.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "disnake\ext\commands\interaction_bot_base.py", line 1465, in process_application_commands
    await app_command.invoke(interaction)
  File "disnake\ext\commands\slash_core.py", line 763, in invoke
    raise CommandInvokeError(exc) from exc
disnake.ext.commands.errors.CommandInvokeError: Command raised an exception: TypeError: components should be a valid UI component, got ActionRow.

There is an issue where can't add ActionRow to ContainerComponent

disnake.ui.UIComponent.register(disnake.ui.ActionRow)
can be added to the bot code as a temporary fix.

…ge|Modal)Components`

Co-authored-by: Eneg <[email protected]>

shiftinv · 2025-06-09T10:39:44Z

There is an issue where can't add ActionRow to ContainerComponent

Should be fixed as of 69591bf. I knew about this issue from the start (and had removed the check locally in my workspace while testing all this time), since it would be remedied by eventually making ActionRows subclass UIComponent, apologies for taking so long to actually fix it properly c:

Co-authored-by: Eneg <[email protected]>

Enegg · 2025-06-09T12:20:15Z

disnake/types/components.py

-class ActionRow(TypedDict):
+
+class _BaseComponent(TypedDict):
+    # type: ComponentType  # FIXME: current version of pyright complains about overriding types, latest might be fine


I believe that's because all TypedDict entries are mutable by default, which makes them invariant
Try type: ReadOnly[ComponentType] on the base

Enegg

A few insights;
I've noticed none of ui.{...} components have __slots__, whereas components.{...} have them. I think it makes sense to add them to ui. as well

Enegg · 2025-06-12T15:26:20Z

disnake/enums.py

+    """
+
+    small = 1
+    """TODO"""


I don't think we need to give a lot of context here?

Suggested change

"""TODO"""

"""Small spacing."""

Enegg · 2025-06-12T15:26:36Z

disnake/enums.py

+    small = 1
+    """TODO"""
+    large = 2
+    """TODO"""


Suggested change

"""TODO"""

"""Large spacing."""

Enegg · 2025-06-12T15:43:39Z

disnake/interactions/message.py

@@ -206,6 +217,7 @@ def __init__(
    ) -> None:
        super().__init__(data)
        self.custom_id: str = data["custom_id"]
+        self.id: int = data.get("id")


Since this is always present:

Suggested change

self.id: int = data.get("id")

self.id: int = data["id"]

Enegg · 2025-06-12T16:02:35Z

disnake/ui/item.py

    def __repr__(self) -> str:
        attrs = " ".join(f"{key}={getattr(self, key)!r}" for key in self.__repr_attributes__)


We could change this to always strip _ from keys and then be able to just put private attributes in __repr_attributes__, wdyt?
Wanted to use str.removeprefix but that's 3.9+

Suggested change

def __repr__(self) -> str:

attrs = " ".join(f"{key}={getattr(self, key)!r}" for key in self.__repr_attributes__)

def __repr__(self) -> str:

attrs = " ".join(

f"{key.lstrip('_')}={getattr(self, key)!r}" for key in self.__repr_attributes__

)

Could fix:

disnake/disnake/ui/action_row.py

Lines 198 to 201 in 7bee2ce

def __repr__(self) -> str:

# implemented separately for now, due to SequenceProxy repr

return f"<ActionRow children={self._children!r}>"

disnake/disnake/ui/container.py

Lines 84 to 87 in 7bee2ce

def __repr__(self) -> str:

# implemented separately for now, due to SequenceProxy repr

return f"<Container components={self._components!r} accent_colour={self.accent_colour!r} spoiler={self.spoiler!r}>"

disnake/disnake/ui/section.py

Lines 61 to 64 in 7bee2ce

def __repr__(self) -> str:

# implemented separately for now, due to SequenceProxy repr

return f"<Section components={self._components!r} accessory={self._accessory!r}>"

Enegg · 2025-06-12T16:22:47Z

disnake/ui/action_row.py

-    # n.b. this should be `*components: UIComponentT`, but pyright does not like it
-    def __init__(self, *components: Union[MessageUIComponent, ModalUIComponent]) -> None:
-        self._children: List[UIComponentT] = []
+    # n.b. this should be `*components: ActionRowChildT`, but pyright does not like it


Hmm. I'm guessing this is because self: ActionRow[ActionRowModalComponent] is narrower than self: Self[ActionRowChildT] (the overloads do not consider subclasses); it's probably as good as it gets without HKT or separate constructors

Enegg · 2025-06-12T16:46:59Z

disnake/ui/section.py

+    def __init__(
+        self,
+        *components: TextDisplay,
+        accessory: Union[Thumbnail, Button],


Suggested change

accessory: Union[Thumbnail, Button],

accessory: Union[Thumbnail, Button[Any]],

(need to import Any)

Enegg · 2025-06-12T16:47:37Z

disnake/ui/section.py

+    # TODO: consider moving runtime checks from constructor into property setters, also making these fields writable
+    @property
+    def components(self) -> Sequence[TextDisplay]:
+        """Sequence[:class:`~.ui.TextDisplay`]: A read-only copy of the text items in this section."""


Suggested change

"""Sequence[:class:`~.ui.TextDisplay`]: A read-only copy of the text items in this section."""

"""Sequence[:class:`~.ui.TextDisplay`]: A read-only proxy of the text items in this section."""

Enegg · 2025-06-12T16:48:39Z

disnake/ui/action_row.py

    def __len__(self) -> int:
        return len(self._children)

    @property
-    def children(self) -> Sequence[UIComponentT]:
+    def children(self) -> Sequence[ActionRowChildT]:
        """Sequence[:class:`WrappedComponent`]:
        A read-only copy of the UI components stored in this action row. To add/remove


Suggested change

A read-only copy of the UI components stored in this action row. To add/remove

A read-only proxy of the UI components stored in this action row. To add/remove

Enegg · 2025-06-12T16:49:18Z

disnake/ui/container.py

+    # TODO: consider moving runtime checks from constructor into property setters, also making these fields writable
+    @property
+    def components(self) -> Sequence[ContainerChildUIComponent]:
+        """Sequence[Union[:class:`~.ui.ActionRow`, :class:`~.ui.Section`, :class:`~.ui.TextDisplay`, :class:`~.ui.MediaGallery`, :class:`~.ui.File`, :class:`~.ui.Separator`]]: A read-only copy of the components in this container."""


Suggested change

"""Sequence[Union[:class:`~.ui.ActionRow`, :class:`~.ui.Section`, :class:`~.ui.TextDisplay`, :class:`~.ui.MediaGallery`, :class:`~.ui.File`, :class:`~.ui.Separator`]]: A read-only copy of the components in this container."""

"""Sequence[Union[:class:`~.ui.ActionRow`, :class:`~.ui.Section`, :class:`~.ui.TextDisplay`, :class:`~.ui.MediaGallery`, :class:`~.ui.File`, :class:`~.ui.Separator`]]: A read-only proxy of the components in this container."""

We love lengthy type classifiers!

Enegg · 2025-06-12T16:56:51Z

disnake/components.py


+    ..
+        TODO: add cv2 components to list
+


Suggested change

..

TODO: add cv2 components to list

- :class:`Section`

- :class:`TextDisplay`

- :class:`Thumbnail`

- :class:`MediaGallery`

- :class:`FileComponent`

- :class:`Separator`

- :class:`Container`

Maybe also change "Currently, the only components [...]" to "Currently, the components [...]", the list has expanded quite a bit (or even just "The components [...]")

shiftinv added 30 commits January 9, 2025 13:52

feat(flags): add new message flag

a7cf032

feat(enums): add new component types

9becf08

feat(types): add id field to all component types

215f37f

feat(types): add typeddicts for new components

91325ed

chore: add some comments from testing

c5084d8

fix: thumbnail media field has been renamed now

cf74701

chore: update comment now that sections allow buttons too

bd96624

fix: make SectionComponent.components typing more permissive

e06c077

feat: add SeparatorSpacingSize enum

f2f2817

feat(components): implement new component classes roughly

93902f5

fix(components): rename components.File -> `components.FileComponen…

7765c46

…t` for now to avoid shadowing

feat: add new components to factory function

0222377

fix: improve Container repr

9bb4013

refactor: rename existing action row component type aliases

928033c

perf: use mapping for _component_factory

b37c87c

refactor: make child component typehints more specific

ff6c20d

chore: move some TODOs

2522af4

docs: add docstrings for new components

103c1c2

feat(types): make child component types for ActionRow and `SectionC…

a363451

…omponent` more specific

fix(typing): resolve pyright complaints related to Message.components

3cfcdd0

refactor(typing): expand Message.components type beyond just `Actio…

7cd06f0

…nRow`s

fix: update relevant methods to account for new Message.components …

82eb456

…type

feat: add id field to message/modal interaction data

a7c2648

refactor: introduce yet another ui base type, for non-actionrow-child…

891ca40

… components

feat(ui): add new ui components, still partially broken

bd2865a

refactor(ui): rework section and container to actually be usable

222f513

docs: add ui components to docs, fix references

962c5d7

fix(ui): fix MediaGallery parameter type

a95e1b2

refactor(types): move action row types to ui._types, add some short…

6198aa6

…cut types

feat(types): add new components to MessageComponentInput union

0ded39d

shiftinv added 2 commits April 18, 2025 18:45

feat: support v2 components in normalize_components/`components_to_…

2ad9e10

…rows`

docs: add changelog entry

58b6045

shiftinv added t: api support Support of Discord API features s: in progress Issue/PR is being worked on s: waiting for api/docs Issue/PR is waiting for API support/documentation labels Apr 18, 2025

shiftinv added this to the disnake v2.11 milestone Apr 18, 2025

shiftinv added this to disnake Apr 18, 2025

github-project-automation bot moved this to Todo in disnake Apr 18, 2025

shiftinv removed the s: waiting for api/docs Issue/PR is waiting for API support/documentation label Apr 23, 2025

Enegg reviewed Apr 23, 2025

View reviewed changes

Enegg reviewed Apr 26, 2025

View reviewed changes

shiftinv and others added 5 commits June 9, 2025 11:58

fix: make ActionRow subclass UIComponent

69591bf

chore: rename (Message|Modal)ComponentInput utility type to `(Messa…

a8fb923

…ge|Modal)Components`

chore(typing): declare __repr_attributes__ in components as classvars

95ac094

Co-authored-by: Eneg <[email protected]>

chore: clarify name of action row child type tuple

3dd1aa7

refactor: try/catch component_factory

61cb394

shiftinv and others added 3 commits June 9, 2025 12:42

fix(types): typing.TypeAlias is 3.10+

567a685

perf: reduce _message_component_factory call overhead

23ac2e1

Co-authored-by: Eneg <[email protected]>

fix: support reused components in _walk_all_components

7bee2ce

Enegg reviewed Jun 11, 2025

View reviewed changes

Enegg reviewed Jun 12, 2025

View reviewed changes


		__slots__: Tuple[str, ...] = ("accessory", "components")

		__repr_info__: ClassVar[Tuple[str, ...]] = __slots__

		def __repr__(self) -> str:
		attrs = " ".join(f"{key}={getattr(self, key)!r}" for key in self.__repr_attributes__)

	def __repr__(self) -> str:
	# implemented separately for now, due to SequenceProxy repr
	return f"<ActionRow children={self._children!r}>"

	def __repr__(self) -> str:
	# implemented separately for now, due to SequenceProxy repr
	return f"<Container components={self._components!r} accent_colour={self.accent_colour!r} spoiler={self.spoiler!r}>"

	def __repr__(self) -> str:
	# implemented separately for now, due to SequenceProxy repr
	return f"<Section components={self._components!r} accessory={self._accessory!r}>"

	accessory: Union[Thumbnail, Button],
	accessory: Union[Thumbnail, Button[Any]],

	"""Sequence[:class:`~.ui.TextDisplay`]: A read-only copy of the text items in this section."""
	"""Sequence[:class:`~.ui.TextDisplay`]: A read-only proxy of the text items in this section."""

	A read-only copy of the UI components stored in this action row. To add/remove
	A read-only proxy of the UI components stored in this action row. To add/remove

	"""Sequence[Union[:class:`~.ui.ActionRow`, :class:`~.ui.Section`, :class:`~.ui.TextDisplay`, :class:`~.ui.MediaGallery`, :class:`~.ui.File`, :class:`~.ui.Separator`]]: A read-only copy of the components in this container."""
	"""Sequence[Union[:class:`~.ui.ActionRow`, :class:`~.ui.Section`, :class:`~.ui.TextDisplay`, :class:`~.ui.MediaGallery`, :class:`~.ui.File`, :class:`~.ui.Separator`]]: A read-only proxy of the components in this container."""

-    ..
-        TODO: add cv2 components to list
+    - :class:`Section`
+    - :class:`TextDisplay`
+    - :class:`Thumbnail`
+    - :class:`MediaGallery`
+    - :class:`FileComponent`
+    - :class:`Separator`
+    - :class:`Container`

feat: components v2 #1294

Are you sure you want to change the base?

feat: components v2 #1294

Conversation

shiftinv commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Description

Scope

Example

Checklist

Uh oh!

Enegg Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Enegg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cwmet commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shiftinv commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Enegg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Enegg Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shiftinv commented Apr 18, 2025 •

edited

Loading

Enegg Apr 23, 2025 •

edited

Loading

cwmet commented Jun 2, 2025 •

edited

Loading

Enegg Jun 12, 2025 •

edited

Loading