API Reference#

Reaction Menus#

Button decorator#

nextcord.ext.menus.button(emoji, **kwargs)#

Denotes a method to be a reaction button for the Menu.

The methods being wrapped must have both a self and a payload parameter of type nextcord.RawReactionActionEvent.

The keyword arguments are forwarded to the Button constructor.

Example

class MyMenu(Menu):
    async def send_initial_message(self, ctx, channel):
        return await channel.send(f'Hello {ctx.author}')

    @button('\N{THUMBS UP SIGN}')
    async def on_thumbs_up(self, payload):
        await self.message.edit(content=f'Thanks {self.ctx.author}!')

    @button('\N{THUMBS DOWN SIGN}')
    async def on_thumbs_down(self, payload):
        await self.message.edit(content=f"That's not nice {self.ctx.author}...")
Parameters

emoji (Union[str, PartialEmoji]) – The emoji to use for the button.

Reordering Reactions#

Position#

class nextcord.ext.menus.Position(number, *, bucket=1)#

Class for repositioning reaction buttons in a menu.

bucket#

The bucket number for the reaction button. The default bucket is 1. Bucket 0 comes at the beginning, bucket 2 at the end.

Type

int

number#

The number of the reaction button in the bucket. A lower number means the button will be closer to the beginning

Type

int

First#

class nextcord.ext.menus.First(number=0)#

Class for repositioning reaction buttons at the beginning of a menu.

This is a shortcut for Position(number=number, bucket=0).

number#

The number of the reaction button within bucket 0. A lower number means the button will be closer to the beginning

Type

int

Last#

class nextcord.ext.menus.Last(number=0)#

Class for repositioning reaction buttons at the end of a menu.

This is a shortcut for Position(number=number, bucket=2).

number#

The number of the reaction button within bucket 2. A lower number means the button will be closer to the beginning

Type

int

Pagination#

Button#

Attributes
class nextcord.ext.menus.Button(emoji, action, *, skip_if=None, position=None, lock=True)#

Represents a reaction-style button for the Menu.

There are two ways to create this, the first being through explicitly creating this class and the second being through the decorator interface, button().

The action must have both a self and a payload parameter of type nextcord.RawReactionActionEvent.

emoji#

The emoji to use as the button. Note that passing a string will transform it into a PartialEmoji.

Type

PartialEmoji

action#

A coroutine that is called when the button is pressed.

Type

Callable[…, Coroutine[Any, Any, Any]]

skip_if#

A callable that detects whether it should be skipped. A skipped button does not show up in the reaction list and will not be processed.

Type

Optional[Callable[[Menu], bool]]

position#

The position the button should have in the initial order. Note that since Discord does not actually maintain reaction order, this is a best effort attempt to have an order until the user restarts their client. Defaults to Position(0).

Type

Position

lock#

Whether the button should lock all other buttons from being processed until this button is done. Defaults to True.

Type

bool

Button Menus#

ButtonMenu#

Attributes
Methods
class nextcord.ext.menus.ButtonMenu(timeout=180.0, clear_buttons_after=False, disable_buttons_after=False, *args, **kwargs)#

An interface that allows handling menus by using button interaction components.

This is a subclass of Menu and as a result, any attributes and methods of Menu are available here as well.

Buttons should be marked with the nextcord.ui.button() decorator. Please note that this expects the methods to have two parameters, the button and the interaction. The button is of type nextcord.ui.Button. The interaction is of type nextcord.Interaction.

timeout#

The timeout to wait between button inputs.

Type

float

delete_message_after#

Whether to delete the message after the menu interaction is done.

Type

bool

check_embeds#

Whether to verify embed permissions as well.

Type

bool

ctx#

The context that started this pagination session or None if it hasn’t been started yet.

Type

Optional[commands.Context]

bot#

The bot that is running this pagination session or None if it hasn’t been started yet.

Type

Optional[commands.Bot]

message#

The message that has been sent for handling the menu. This is the returned message of send_initial_message(). You can set it in order to avoid calling send_initial_message(), if for example you have a pre-existing message you want to attach a menu to.

Type

Optional[Union[nextcord.Message, nextcord.PartialInteractionMessage]]

clear_buttons_after#

Whether to clear buttons after the menu interaction is done. Note that delete_message_after takes priority over this attribute.

Type

bool

disable_buttons_after#

Whether to disable all buttons after the menu interaction is done. Note that delete_message_after and clear_buttons_after take priority over this attribute.

Type

bool

add_item(item)#

Adds an item to the view.

Parameters

item (Item) – The item to add to the view.

Raises

  • TypeError – An Item was not passed.

  • ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

await clear()#

This function is a coroutine. Removes all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If there are already no buttons in the view, the message will not be edited.

clear_items()#

Removes all items from the view.

await disable()#

This function is a coroutine. Disables all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If all buttons are already disabled, the message will not be edited.

await enable()#

This function is a coroutine. Enables all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If all buttons are already enabled, the message will not be edited.

await finalize(timed_out)#

This function is a coroutine.

A coroutine that is called when the menu loop has completed its run. This is useful if some asynchronous clean-up is required after the fact.

Parameters

timed_out (bool) – Whether the menu completed due to timing out.

await interaction_check(interaction)#

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters

interaction (Interaction) – The interaction that occurred.

Returns

Whether the view children’s callbacks should be called.

Return type

bool

is_dispatching()#

bool: Whether the view has been added for dispatching purposes.

is_finished()#

bool: Whether the view has finished interacting.

is_persistent()#

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

await on_error(error, item, interaction)#

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation prints the traceback to stderr.

Parameters

  • error (Exception) – The exception that was raised.

  • item (Item) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

await on_timeout()#

This function is a coroutine.

A callback that is called when a view’s timeout elapses without being explicitly stopped.

remove_item(item)#

Removes an item from the view.

Parameters

item (Item) – The item to remove from the view.

await send_initial_message(ctx, channel)#

This function is a coroutine.

Sends the initial message for the menu session.

This is internally assigned to the message attribute.

A Message or a PartialInteractionMessage object must be returned. When using reaction buttons, the message must be an instance of a nextcord.Message.

Subclasses must implement this if they don’t set the message attribute themselves before starting the menu via start().

Parameters

  • ctx (Context) – The invocation context to use.

  • channel (nextcord.abc.Messageable) – The messageable to send the message to.

Returns

The message that has been sent.

Return type

Union[nextcord.Message, nextcord.PartialInteractionMessage]

should_add_reactions_or_buttons()#

bool: Whether to add reactions or buttons to this menu session.

await start(ctx=None, interaction=None, *, channel=None, wait=False, ephemeral=False)#

This function is a coroutine.

Starts the interactive menu session.

To start a menu session, you must provide either a Context or an Interaction object.

Parameters

  • ctx (Context) – The invocation context to use.

  • interaction (nextcord.Interaction) – The interaction context to use for slash and component responses.

  • channel (nextcord.abc.Messageable) – The messageable to send the message to. If not given then it defaults to the channel in the context or interaction.

  • wait (bool) – Whether to wait until the menu is completed before returning back to the caller.

  • ephemeral (bool) – Whether to make the response ephemeral when using an interaction response. Note: ephemeral messages do not support reactions.

Raises
stop()#

Stops the internal loop and view interactions.

await wait()#

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

Button decorator#

nextcord.ui.button(*, label=None, custom_id=None, disabled=False, style=ButtonStyle.secondary, emoji=None, row=None)#

A decorator that attaches a button to a component.

The function being decorated should have three parameters, self representing the nextcord.ui.View, the nextcord.ui.Button being pressed and the nextcord.Interaction you receive.

Note

Buttons with a URL cannot be created with this function. Consider creating a Button manually instead. This is because buttons with a URL do not have a callback associated with them since Discord does not do any processing with it.

Parameters

  • label (Optional[str]) – The label of the button, if any.

  • custom_id (Optional[str]) – The ID of the button that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • style (ButtonStyle) – The style of the button. Defaults to ButtonStyle.grey.

  • disabled (bool) – Whether the button is disabled or not. Defaults to False.

  • emoji (Optional[Union[str, Emoji, PartialEmoji]]) – The emoji of the button. This can be in string form or a PartialEmoji or a full Emoji.

  • row (Optional[int]) – The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

Pagination#

ButtonMenuPages#

Attributes
Methods
class nextcord.ext.menus.ButtonMenuPages(source, style=ButtonStyle.secondary, **kwargs)#

A special type of Menu dedicated to pagination with button components.

Parameters

style (nextcord.ui.ButtonStyle) – The button style to use for the pagination buttons.

current_page#

The current page that we are in. Zero-indexed between [0, PageSource.max_pages).

Type

int

add_item(item)#

Adds an item to the view.

Parameters

item (Item) – The item to add to the view.

Raises

  • TypeError – An Item was not passed.

  • ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

await change_source(source)#

This function is a coroutine.

Changes the PageSource to a different one at runtime.

Once the change has been set, the menu is moved to the first page of the new source if it was started. This effectively changes the current_page to 0.

Raises

TypeError – A PageSource was not passed.

await clear()#

This function is a coroutine. Removes all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If there are already no buttons in the view, the message will not be edited.

clear_items()#

Removes all items from the view.

await disable()#

This function is a coroutine. Disables all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If all buttons are already disabled, the message will not be edited.

await enable()#

This function is a coroutine. Enables all nextcord.ui.Button components in the menu. If the message is set, it will be edited with the new View. If all buttons are already enabled, the message will not be edited.

await finalize(timed_out)#

This function is a coroutine.

A coroutine that is called when the menu loop has completed its run. This is useful if some asynchronous clean-up is required after the fact.

Parameters

timed_out (bool) – Whether the menu completed due to timing out.

await go_to_first_page(payload=None)#

go to the first page

await go_to_last_page(payload=None)#

go to the last page

await go_to_next_page(payload=None)#

go to the next page

await go_to_previous_page(payload=None)#

go to the previous page

await interaction_check(interaction)#

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters

interaction (Interaction) – The interaction that occurred.

Returns

Whether the view children’s callbacks should be called.

Return type

bool

is_dispatching()#

bool: Whether the view has been added for dispatching purposes.

is_finished()#

bool: Whether the view has finished interacting.

is_persistent()#

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

await on_error(error, item, interaction)#

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation prints the traceback to stderr.

Parameters

  • error (Exception) – The exception that was raised.

  • item (Item) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

await on_timeout()#

This function is a coroutine.

A callback that is called when a view’s timeout elapses without being explicitly stopped.

remove_item(item)#

Removes an item from the view.

Parameters

item (Item) – The item to remove from the view.

await send_initial_message(ctx, channel)#

This function is a coroutine.

The default implementation of Menu.send_initial_message() for the interactive pagination session.

This implementation shows the first page of the source.

should_add_reactions_or_buttons()#

bool: Whether to add reactions or buttons to this menu session.

await show_page(page_number)#

This function is a coroutine. Sets the current page to the specified page and shows it.

property source#

The source where the data comes from.

Type

PageSource

await start(ctx=None, interaction=None, *, channel=None, wait=False, ephemeral=False)#

This function is a coroutine.

Starts the interactive menu session.

To start a menu session, you must provide either a Context or an Interaction object.

Parameters

  • ctx (Context) – The invocation context to use.

  • interaction (nextcord.Interaction) – The interaction context to use for slash and component responses.

  • channel (nextcord.abc.Messageable) – The messageable to send the message to. If not given then it defaults to the channel in the context or interaction.

  • wait (bool) – Whether to wait until the menu is completed before returning back to the caller.

  • ephemeral (bool) – Whether to make the response ephemeral when using an interaction response. Note: ephemeral messages do not support reactions.

Raises
stop()#

Stops the internal loop and view interactions.

await stop_pages(payload=None)#

stops the pagination session.

await wait()#

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

Page Sources#

PageSource (Basic Interface)#

Methods
class nextcord.ext.menus.PageSource#

An interface representing a menu page’s data source for the actual menu page.

Subclasses must implement the backing resource along with the following methods:

await format_page(menu, page)#

This function could be a coroutine.

An abstract method to format the page.

This method must return one of the following types.

If this method returns a str then it is interpreted as returning the content keyword argument in nextcord.Message.edit() and nextcord.abc.Messageable.send().

If this method returns a nextcord.Embed then it is interpreted as returning the embed keyword argument in nextcord.Message.edit() and nextcord.abc.Messageable.send().

If this method returns a List[nextcord.Embed] then it is interpreted as returning the embeds keyword argument in nextcord.Message.edit() and nextcord.abc.Messageable.send().

If this method returns a dict then it is interpreted as the keyword-arguments that are used in both nextcord.Message.edit() and nextcord.abc.Messageable.send(). A few of interest are: content, embed, embeds, file, files.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Any) – The page returned by get_page().

Returns

See above.

Return type

Union[str, nextcord.Embed, List[nextcord.Embed], dict]

get_max_pages()#

An optional abstract method that retrieves the maximum number of pages this page source has. Useful for UX purposes.

The default implementation returns None.

Returns

The maximum number of pages required to properly paginate the elements, if given.

Return type

Optional[int]

await get_page(page_number)#

This function is a coroutine.

An abstract method that retrieves an object representing the object to format.

Subclasses must implement this.

Note

The page_number is zero-indexed between [0, get_max_pages()), if there is a maximum number of pages.

Parameters

page_number (int) – The page number to access.

Returns

The object represented by that page. This is passed into format_page().

Return type

Any

is_paginating()#

An abstract method that notifies the MenuPagesBase whether or not to start paginating.

This signals whether to add menus to this page source. Menus can either be buttons or reactions depending on the subclass.

Subclasses must implement this.

Returns

Whether to trigger pagination.

Return type

bool

await prepare()#

This function is a coroutine.

A coroutine that is called after initialisation but before anything else to do some asynchronous set up as well as the one provided in __init__.

By default this does nothing.

This coroutine will only be called once.

ListPageSource#

Attributes
Methods
class nextcord.ext.menus.ListPageSource(entries, *, per_page)#

A data source for a sequence of items.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

entries#

The sequence of items to paginate.

Type

Sequence[Any]

per_page#

How many elements are in a page.

Type

int

await format_page(menu, page)#

An abstract method to format the page.

This works similar to the PageSource.format_page() except the type of the page parameter is documented.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Union[Any, List[Any]]) – The page returned by get_page(). This is either a single element if per_page is set to 1 or a slice of the sequence otherwise.

Returns

See PageSource.format_page().

Return type

Union[str, nextcord.Embed, List[nextcord.Embed], dict]

get_max_pages()#

int: The maximum number of pages required to paginate this sequence.

await get_page(page_number)#

Returns either a single element of the sequence or a slice of the sequence.

If per_page is set to 1 then this returns a single element. Otherwise it returns at most per_page elements.

Returns

The data returned.

Return type

Union[Any, Sequence[Any]]

is_paginating()#

bool: Whether pagination is required.

await prepare()#

This function is a coroutine.

A coroutine that is called after initialisation but before anything else to do some asynchronous set up as well as the one provided in __init__.

By default this does nothing.

This coroutine will only be called once.

GroupByPageSource#

Attributes
Methods
class nextcord.ext.menus.GroupByPageSource(entries, *, key, per_page, sort=True)#

A data source for grouped by sequence of items.

This inherits from ListPageSource.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

Parameters

  • entries (Sequence[Any]) – The sequence of items to paginate and group.

  • key (Callable[[Any], Any]) – A key function to do the grouping with.

  • sort (bool) – Whether to sort the sequence before grouping it. The elements are sorted according to the key function passed.

  • per_page (int) – How many elements to have per page of the group.

entries#

The sequence of items to paginate.

Type

Sequence[Any]

per_page#

How many elements are in a page.

Type

int

await format_page(menu, entry)#

An abstract method to format the page.

This works similar to the PageSource.format_page() except the type of the entry parameter is documented.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • entry (GroupByEntry) – The page returned by get_page(). This will be a GroupByEntry with key, representing the key of the itertools.groupby() function, and items, representing a sequence of paginated items within that group.

Returns

See PageSource.format_page().

Return type

Union[str, nextcord.Embed, List[nextcord.Embed], dict]

get_max_pages()#

int: The maximum number of pages required to paginate this sequence.

await get_page(page_number)#

Returns a GroupByEntry with key, representing the key of the itertools.groupby() function, and items, representing a sequence of paginated items within that group.

Returns

The data returned.

Return type

GroupByEntry

is_paginating()#

bool: Whether pagination is required.

await prepare()#

This function is a coroutine.

A coroutine that is called after initialisation but before anything else to do some asynchronous set up as well as the one provided in __init__.

By default this does nothing.

This coroutine will only be called once.

GroupByEntry#

Attributes
class nextcord.ext.menus.GroupByEntry(key, items)#

Named tuple representing an entry returned by GroupByPageSource.get_page() in a GroupByPageSource.

key#

A key of the itertools.groupby() function.

Type

Callable[[Any], Any]

items#

Slice of the paginated items within the group.

Type

List[Any]

AsyncIteratorPageSource#

Attributes
Methods
class nextcord.ext.menus.AsyncIteratorPageSource(iterator, *, per_page)#

A data source for data backed by an asynchronous iterator.

This page source does not handle any sort of formatting, leaving it up to the user. To do so, implement the format_page() method.

Parameters

  • iterator (AsyncIterator[Any]) – The asynchronous iterator to paginate.

  • per_page (int) – How many elements to have per page.

iterator#

The async iterator of items to paginate.

Type

AsyncIterator[Any]

per_page#

How many elements are in a page.

Type

int

await format_page(menu, page)#

An abstract method to format the page.

This works similar to the PageSource.format_page() except the type of the page parameter is documented.

Parameters

  • menu (Menu) – The menu that wants to format this page.

  • page (Union[Any, List[Any]]) – The page returned by get_page(). This is either a single element if per_page is set to 1 or a slice of the sequence otherwise.

Returns

See PageSource.format_page().

Return type

Union[str, nextcord.Embed, List[nextcord.Embed], dict]

get_max_pages()#

An optional abstract method that retrieves the maximum number of pages this page source has. Useful for UX purposes.

The default implementation returns None.

Returns

The maximum number of pages required to properly paginate the elements, if given.

Return type

Optional[int]

await get_page(page_number)#

Returns either a single element of the sequence or a slice of the sequence.

If per_page is set to 1 then this returns a single element. Otherwise it returns at most per_page elements.

Returns

The data returned.

Return type

Union[Any, List[Any]]

is_paginating()#

bool: Whether pagination is required.

await prepare(*, _aiter=<function _aiter>)#

This function is a coroutine.

A coroutine that is called after initialisation but before anything else to do some asynchronous set up as well as the one provided in __init__.

By default this does nothing.

This coroutine will only be called once.

Exceptions#

CannotSendMessages#

class nextcord.ext.menus.CannotSendMessages#

Exception for when the bot is unable to send messages

CannotAddReactions#

class nextcord.ext.menus.CannotAddReactions#

Exception for when the bot is unable to add reactions

CannotReadMessageHistory#

class nextcord.ext.menus.CannotReadMessageHistory#

Exception for when the bot is unable to read message history