discord-ui

A discord.py extension for using discord ui/interaction features
pip package ▪ read the docs ▪ examples

Introduction

This is a discord.py ui extension made by 404kuso and RedstoneZockt for using discord's newest ui features like buttons, slash commands and context commands.

Documentation

Installation

Windows

py -m pip install discord-ui

Linux

python3 -m pip install discord-ui

License

This project is under MIT License

Issues

If you find any issues, please report them

https://github.com/discord-py-ui/discord-ui/issues

Note

If you want to use slash commands, in the oauth2 invite link generation, you have to check both bot and application.commands fields

Example

Example for creating a simple slash command

import discord
from discord.ext import commands
from discord_ui import UI, SlashOption

client = commands.Bot(" ")
ui = UI(client)

@ui.slash.command("hello_world", options=[SlashOption(bool, "cool", "whether this libary is cool", required=False)], guild_ids=[785567635802816595])
async def command(ctx, cool=True):
    """This is a simple slash command"""
    # you can use docstrings for the slash command description too
    await ctx.respond("You said this libary is " + str(cool))

client.run("your_token")

Example for creating a user-context command

import discord
from discord.ext import commands
from discurd_ui import UI

client = commands.Bot(" ")
ui = UI(client)

@ui.slash.user_command("avatar", guild_ids=[785567635802816595])
async def avatar(ctx, user: discord.Member):
    """Sends the avatar of a user"""
    await ctx.respond(embed=discord.Embed(description=user.display_name).set_image(url=user.avatar_url))

client.run("your_token")

Example for autocompletion of choices

import discord
from discord_ui import UI, SlashOption, AutocompleteInteraction

async def generator(ctx: AutocompleteInteraction):
    available_choices = ["hmm", "this", "is", "a", "an", "test", "testing"]
    return [(x, x) for x in available_choices if x.startswith(ctx.value_query)]

@ui.slash.command("search_word", options=[SlashOption(str, "query", choice_generator=generator)])
async def search_word(ctx, query):
    await ctx.send("got " + query + " for query")

client.run("your_token")

Example for sending a button and receiving it

import discord
from discord.ext import commands
from discord_ui import UI, LinkButton, Button

from asyncio import TimeoutError

client = commands.Bot(" ")
ui = UI(client)

@client.listen("on_message")
async def on_message(message: discord.Message):
    if message.content == "!btn":
        msg = await message.channel.send("you", components=[
            [Button("press me", color="green"), LinkButton("https://discord.com", emoji="😁")],
            Button(custom_id="my_custom_id")
        ])
        try:
            btn = await msg.wait_for("button", client, by=message.author, timeout=20)
            await btn.respond("you pressed `" + btn.content + "`")
        except TimeoutError:
            await msg.delete()

client.run("your_token_here")

Example for sending Selectmenus and receiving them

import discord
from discord.ext import commands
from discord_ui import UI, SelectMenu, SelectOption

from asyncio import TimeoutError

client = commands.Bot(" ")
ui = UI(client)

@client.listen("on_message")
async def on_message(message: discord.Message):
    if message.content == "!sel":
        msg = await message.channel.send("you", components=[SelectMenu(options=[
            SelectOption("my_value", label="test", description="this is a test"),
            SelectOption("my_other_value", emoji="🤗", description="this is a test too")
        ], "custom_id", max_values=2)])
        try:
            sel = await msg.wait_for("select", client, by=message.author, timeout=20)
            await sel.respond("you selected `" + str([x.content for x in sel.selected_options]) + "`")
        except TimeoutError:
            await msg.delete()

client.run("your_token_here")

Example for cogs

from discord.ext import commands
from discord_ui import UI
from discord_ui.cogs import slash_command, subslash_command, listening_component

bot = commands.Bot(" ")
ui = UI(bot)

class Example(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
    
    @slash_command(name="example", guild_ids=[785567635802816595])
    async def example(self, ctx):
        await ctx.respond("gotchu")

    @subslash_command(base_names="example", name="command"):
    async def example_command(self, ctx):
        await ctx.respond("okayy")
    
bot.add_cog(Example(bot))
bot.run("your token")

You can find more (and better) examples here

Contact

You can contact us on discord

Changelog

This will be moved to https://discord-py-ui.github.io/discord-ui/

5.1.2

Fixed
- commands.nuke
- nextcord import issue (#112)
5.1.0

Breaking changes
- Component custom ids are now optional, if no custom id is passed, a 100 characters long random string will be used and because of that the order of Component init params changed
- The order of SelectMenus init params changed, custom_id comes now after options
```
SelectMenu("my_custom_id", [options...here])
# is now
SelectMenu([options...here], "my_custom_id")
```
- Same for Buttons
```
Button("my_custom_id", "label")
# is now
Button("label", "my_custom_id")
```
- ButtonStyles is now ButtonStyle
- renamed cog decorators, the old ones still work but they will show a deprecation warning: slash_command -> slash_command, subslash_command -> subslash_command, context_cog -> context_command, listening_component -> listening_component
- Removed Slash.edit_command and Slash.edit_subcommand, "moved" to Command.edit
- SlashedCommand is now SlashInteraction, SlashedSubCommand is now SubSlashInteraction and SlashedContext is now ContextInteraction
- The command attributes of CommandInteractions (SlashedCommand, ...) are now moved to Interaction.command. (the .command attribute is a reference to the real command, if you change properties of the command they will be updated)
- The component attributes of an interaction are now moved to .component
- ContextCommands .param attribute is now .target
Changed
- argument_type in SlashOption is now type
- ButtonStyle value names changed: color names are now capitalized and Danger is now Destructive
- Listener.target_user is now Listener.target_users and can take users, members and ids as the value
- BaseCommand.options and SlashOption.options is now of type SlashOptionCollection, which allows you to acces options by index and name
```
my_command.options["option name"]
# or
my_command.options[0]
```
You can also use some methods like .get, .set (which will return itself after it set something, so SlashOption.set(key, value).set(key, value) would work) and SlashOption.options + SlashOption.option will add both SlashOptions together
- If an invalid guild id was passed to a slashcommand, no exception will be raised anymore, it will just be printed into the console and ignored logging.error()
- Moved the discord_ui.ext.py module into a folder
- on_button_press and on_menu_select is now on_button and on_select. The old event names will still work but will be removed in the next release
Fixed
- disable_action_row
- ActionRow.disable
- no interaction events being dispatched because subclasses of dpy2 commands.Bot instances wouldn't get overriden which lead to not enabling needed debug events
- when no matching component listener in Listener could be found, the events for components events wouldn't be dispatched
- delete_after keyword in message send override not working
- mentionable type in slashoptions not being parsed to objects
- @discord.ext.commands.Cooldown not working on cog slashcommands
Added
- **fields to all functions that edit the message components (like .disable_components, .disable_component, ...). The **fields parameter can be used to edit other properties of the message without using .edit again and send a "useless" request
- @Lister.on_error and @Listener.wrong_user decorators for handling Exceptions in Listeners
- When no keyword was passed to @Listener.button or @Listener.select, the function will be called on every button/slect
- channel_type to SlashOption, list of discord.ChannelType. This will restrict the shown channels for channel slash options to this list.
- support for nextcord. Other libs should work too, but they are not tested.
- Mentionable type for SlashOptions
- description for short slashoptions. If you set the options for a slash command via callback params, you can add a description (and a type) to them with your docstring. There are 3 different styles you can use:
```
# style 1
@ui.slash.command()
async def my_command(ctx, my_option, my_other_option):
    """This is my command description

    my_option: `int`:
        This is the description for the my_option parameter
    my_other_option: `str`:
        This is the description for another option
    """
    ...

# style 2
@ui.slash.command()
async def my_command(ctx, my_option: int, my_other_option: str):
    """This is my command description

    my_option: This is the description for the my_option parameter
    my_other_option: This is the description for another option
    """
    ...

# style 3
@ui.slash.command()
async def my_command(ctx, my_option, my_other_option: str):
    """This is my command description


    `int`: This is the description for the my_option parameter

    This is the description for another option
    """
    ...
```
Note: You don't have to use `type`, you can just use type
- Empty descriptions for slashcommands and slashoptions. The default description value is now \u200b which is an "empty" char
- Modifying slashcommand options is now WWAAYYYY easier. You can just do .options[name or index].name = "new name" and the option will be updated
- You can set the autocomplete choice generator with a decorator now
```
ui.slash.command(options=[SlashOption(str, "my_option")])
async def my_command(ctx, my_option):
    ...


@my_command.options["my_option"].autocomplete_function
async def my_generator(ctx):
    ...
# or
@my_command.options[0].autocomplete_function
async def my_generator(ctx):
    ...
```
- All apllication command decorators will now return the created Command
```
@ui.slash.command(...)
async my_command(ctx):
    ...
type(my_command) # SlashCommand
```
- Added edit and delete method to slashcommand. You can use this for editing or deleting the command later
```
# edit
await my_command.edit(name="test")
# delete
await my_command.delete()
```
- id to SlashCommand
- commands_synced event which will be dispatched when all commands where synced with the api (UI.Slash.sync_commands)
- BaseCommmand.update method which updates the api command with the lcoal changes
- SlashSubCommand.base, which will be shared among all subslashcommands with the same base
Removed
- discord.ext.commands.Bot override for enabling the debug event, this will be enabled when creating a UI instance from the bot
5.0.1

Fixed
- Choices not working
5.0.0

Fixed
- Roles not being parsed correctly
Changed
- default_permission
default_permission can now be of type discord.Permissions but the api doesn't support that yet.
- slash http
some code changes to slash-http features

Added
- ChoiceGeneratorContext
Context class for choice generation
- SlashOption
choice_generator keyword and autocomplete keyword. autocomplete is not needed if you pass choice_generator
- File sending
You are now able to send hidden files
4.3.8

Fixed
- Issue with SlashOptions
required is now false by default again
4.3.7

Changed
- SlashOption
Required is now True by default

Fixed
- AttributeError: 'LinkButton' object has no attribute 'component_type'
Removed
- decompressing
The lib now doesn't decompress byte data anymore, which means everything before the dpy commit 848d752 doesn't work with this lib.

message reference in discordpy discord server
4.3.6

Fixed
- Slashcommand comparing
- Ephemeralmessage keyerror exception
4.3.5

Fixed
- send function issues
4.3.4

Fixed
- SlashOption not accepting tuple
4.3.3

Fixed
- fixed TypeError: 'NoneType' object is not iterable
4.3.2

Fixed
- Could not find a matching option type for parameter '<class 'NoneType'>'
4.3.1

Removed
- unused parameter
4.3.0

Fixed
- Message.wait_for
by keyword doesn't work properly

Removed
- Hash
Removed the hash property from Buttons and SelectMenus due to the removal of it from the api

Added
- discord_ui.ext
A module with useful tools and decorators to use more information
- BaseCommand
BaseCommand (the superclass for all applicationcommands) has now some extra properties:
```
- is_chat_input
> Whether this command is a slash command

- is_message_context
> Whether this command is a message context command

- is_user_context
> Whether this command is a user context command
```
- SlashedCommand
Added properties:
```
- is_alias
> Whether the invoked command is an alias or not

- aliases
> All the available aliases for the command
```
- Listeners
Listeners are something that you can use for a better processing of received components. You could see them as a cog to the message components more information

Changed
- SelectInteraction
SelectInteraction.selected_values are not the raw values that were selected, SelectMenu.selected_options are the options of type SlashOption that were selected
- MISSING => None
All instance values that were MISSING by default are now None
4.2.15

Fixed
- #97
4.2.14

Fixed
- small SelectOption issues
- context commands
Changed
- allow context commands to have names with spaces
4.2.13

Fixed
- TypeError: 'EMPTY' is not a callable object in context commands
4.2.12

Fixed
- context commands
4.2.11

Fixed
- cog context commands returned wrong type
4.2.10

Fixed
- cog context commands typo with guild_permission keyword
4.2.8

Added
- edit_subcomand
Fixed
- print statements
Fixed
- #94 (again 💀)
- received subcommands
The base_names and the name will be now set to the right value
4.2.7

Added
- on_component
There is now an event with the name component that will be dispatched whenever a component was received If you use Message.wait_for, there is now a new event choice with the name component (message.wait_for("component", client))

Fixed
- #94
DM issue with deleting messages

Changed
- edit
Edit now takes "content" as not positional (.edit("the content") works now)
- component lenght
You are now able to set component values with the right max lenght
4.2.6

Fixed
- emebds
there was an issue with sending embeds
4.2.5

Fixed
- listening_components
There was an issue with listening components that they needed two parameters but only one was passed Another issue was TypeError: __init__() missing 1 required positional argument: 'custom_id'?
- emebds
there was an issue with sending embeds
4.2.2

Changed
- sync_commands
the delete_unused keyword is now optional, if you don't pass a parameter, slash.delete_unused will be used (from the __init__ function)
4.2.1

Fixed
- cannot import name 'InteractionResponseType' from 'discord.enums'

4.2.0

Added

cog_remove sync

when you remove a cog the slash commands will now get deleted if you set delete_unused to True and set sync_on_cog to True

alternativ slash options

you don't have to specify options in one of the slash decorators anymore. Instead, you can set them in your callback function Example

@ui.slash.command()
async def greet(ctx, user):                         # This will add an required option with the name "user" of type "user"
    """Greets a user
    
    You can use multiline docstrings, because only the first line will be used for the description
    """
    ...

@ui.slash.command()
async def tag(ctx, target: discord.User = None):    # This will add an optional option with the name "target" of type "user"
                                                    # Note: you could also use target: "user" = None or anything else you would use in SlashOption for the type
    ...

Fixed

sync_commands

if you would sync the commands after the first sync, it threw an error

4.1.4

Fixed
- slashcommands in forbidden guilds
when trying to get slash commands in a guild with no appication.commands permission, it won't throw an exepction anymore
4.1.2

Fixed
- Subcommands editing
subcommand checks were wrong and this would result in errors like In options.0.options.2: Option name 'name' is already used in these options
4.1.1

Fixed
- Interaction.author.voice
For some reason the voice property of the creator or the interaction would be set
- Global slashcommands
They wouldn't be registered to the api
4.1.0

Added
- py 3.6 < support
You should be able to use this package with python 3.6 or newer

Fixed
- print
Forgot to remove print statements💀
4.0.4

Fixed
- slashcommand
when a user was passed in an option, its guild was always None
- context commands
if no name passed, the context command wouldn't take the callback name as the name of the command
4.0.3

Fixed
- Message.wait_for
4.0.2

Fixed
- Issue with receiving context commands
4.0.1

Fixed
- discord.ext import error
4.0.0

Added

You now have much more control over your slash commands!
- Permissions
You can update your permissions with the Slash.update_permissions function
- Creating commands
You can now create slash commands without the decorator in a much more eaisier way! Check out the Slash.add_command function
- Edit commands
You can edit commands in code with the Slash.edit_command function
- Listening components
You can add and remove listening components now with the Components.add_listening_component, Components.remove_listening_component and Components.remove_listening_components functions
- Cogs
You can now use cog decorators like slash_command, subslash_command and listening_component

Fixed
- SlashCommand
Slash commands wouldn't be updated if only default_permission was changed

Changed
- wait_for
Message.wait_for now takes by and check as parameters and event_name and client switched place (wait_for(client, "event_name") is now wait_for("event_name", client))
- listening components
You can specify listening_components now more presicely, you can add messages, users, and a check to filter
- Interaction.member
Interaction.member is now Interaction.author
- listening comonents
Listening component callback functions now only take one parameter, the used component
- on_button_press and on_menu_select
These events now take a sole parameter, the used component. If you want to acces to message, use passed_component.message

Removed
- ResponseMessage
Removed ResponseMessage
3.3.5

Fixed
- SelectMenu
SelectMenu issue when creating it from data
3.3.4

Changed
- edit
Message.edit now takes a embed parameter

Fixed
- print
Forgot to remove some print statements
3.3.3

Added
- class representation
classes have now a __repr__ function
- UI(override_dpy)
You can now choose whether you want to override some of dpy objects and functions (default is True) (see the override module for more information) This also appeals to the Components class (Components(override_dpy)) note: if you don't want to create a UI object, you can instead override dpy with the override_dpy method
```
from discord_ui import override_dpy

override_dpy()
```
Fixed
- dpy2
discord.py v2 now auto-decompresses socket data and passes a string instead of the uncompressed data.
- override dpy message
when overriding dpy message object, the components would mix
3.3.2

Added
- EphemeralResponseMessage
You can now edit a ephemeral message which was created from an interaction (ex. when a button in a hidden message was pressed)
3.3.1

Added
- interaction
Interaction.channel and Interaction.guild
3.3.0

Fixed
- interaction usage in dms
3.2.9

Added
- ratelimit fix
The lib will now retry after the ratelimit reset and doesn't throw an HTTPException anymore

Fixed
- sync_commands
Got KeyError exception while syncing commands
3.2.8

Fixed
- hidden responding
When a hidden response was about to be send without defering the interaction it would thrown an error
3.2.7

Added
- warnings
  - When a guild_permission with an invalid guild id is passed, it will throw an exception when syncing the commands
  - When the value of a guild_permission is not of type SlashPermission it will throw an exception
- context-commands
You can now have context commands with the same name as a normal slash command
- slashcommand description
You can use docstrings """docstring""" for setting the description of a slash commmand by setting the dosctring for the callback function

Changed
- auto_defer
auto_defer is now disabled by default
- slash sync
You can now disable auto_sync for slash commmands and sync them by yourself with Slash.sync_commands(delete_unused)
- Interacion.defer
Interaction._deferred is not Interaction.deferred and Interaction.defer() doesn't throw an exception anymore, it will just log the error with logging.error()

Fixed
- try
There was a try/catch in the Interaction.respond function that would allow the code to continue when an exception occured while responding with ninja_mode
- context commands
There was an issue adding context-commands
- Command checking
Now, the libary only edits commands when changes were made
3.2.6

Added
- auto ninja_mode
If you use .respond(), the function will try to use ninja_mode automatically

Changed
- project
Moved git-project to https://github.com/discord-py-ui/discord-ui

Fixed
- ninja_mode response
responding with ninja_mode would end up in an exception
- file sending
fixed another file sending issue with slash commands
3.2.5

Fixed
- #89 (thanks for reporting)
3.2.4
- Fixed version issues with the package
3.2.2

Fixed
- #85: AttributeError: module 'discord' has no attribute '_Components__version'
3.2.0

Fixed

I'm really sorry for all the issues this libary got, if you still find issues, please report them in https://github.com/discord-py-ui/discord-ui/issues
- SelectOpion
There was an issue with emojis not being set in SelectOptions
- LinkButton
There was an issue with setting the url not being set
- SlashCommands
There was an issue with creating commands that don't already exist

Changed
- SelectInteraction
.values is not .selected_values

Added
- Interaction
Buttons and SelectMenus have a .message property for the message where their interaction was creted ResponseMessages have a .interaction property for the received interaction
- Events
We added a interaction_received event for all interactions that are received
3.1.0

Added
- discordpy 2 support
We added support for discord.py v2, so you can stay loyal to our libary and use it together with discord.py v2!
- Exceptions
Added own Exceptions for errors
- ParseMethod
You can change the way the extension parses interaction data. You can choose between different Methods
- Auto-defer
The libary will autodefer all interactions public. If you want to change that, take a look at the documentation for this feature
- slashcommand edit check
Slash commands will only be edited if there were some changes, so you won't get a invalid interaction error in discord after starting the bot If only permissions were changed, just the permissions will be edited and not the whole command like before

Fixed
- slash commands
I finally fixed the damn slashcommand system, it should work now
- Parsing
The resolving, fetching and pulling from the cache methods should all work
3.0.1

Fixed
- small project issues
3.0.0

Added
- context commands
Context commands are now available

Changed
- Project name
The project's name was changed from discord-message-components to discord-ui
- Extension is now UI
2.1.0

Added
- Webhook support
You are now able to use webhooks together with message components, to send a webhook message with the components, use the Components.send_webhook function. The standart webhook function is also overriden with the new component function
- Float type
You can now use float as the argument type for a slash command option
- Auto empty names
Buttons, LinkButtons and SelectOptions labels are now by default \u200b, which is an "empty" char

Changed
- Code documentation to more be more informative
Fixed
- Fixed small code issues (they were already fixed in previous versions, but I just wanna list this here)
- Docs are now working
2.0.2

Fixed
- SelectOption
Select option threw an exception if it was smaller than 1 or higher than 100
2.0.0

Added
- Slashcomamnd support
  - Slash class for slash commands
  - Slash.command, Slash.subcommand and Slash.subcommand_groups are available for creating slash commands
  - SlashedCommand and SlashedSubCommand are there for used slash commands
- Message
  - disable_action_row(row_numbers: int | range, disable: bool)
  disables (enables) component row(s) in the message
  - disable_components(disable: bool)
  disables (enables) all componentss
- overrides
  - Messageable.send returns Message instead of discord.Message and takes components parameter
  - override_client function added
- interaction.send, creates followup messages which can be hidden
- Component.listening_component
A listening component with a callback function that will always be executed whenever a component with the specified custom_id was used

Changed
- Message
  - All Message objects don't use the client object anymore
  - Message.wait_for now needs the client as the first parameter
Fixed
- Interaction
All interaction responses work now
- A lot of issues I fogor💀
1.2.2

Fixed
- Docs fixed
1.2.1

Fixed
- Small code fixes
1.2.0

Added
- Complete message component suppport
- Select menus
- documentation
1.1.2

Fixed
- Small code fixes
1.1.1

Added
- Message.edit()
  
  You can now edit messages with button support
1.1.0

Changed
- Major changes to request code, now using the client's request
- ResponseMessage.acknowledge() -> ResponseMessage.defer()
  
  Changed the name of the function + changed ResponseMessage.acknowledged -> ResponseMessage.deferred
- ResponseMessage.defer() => await ResponseMessage.defer()
  
  defer (acknowledge) is now async and needs to be awaited
Added
- hidden responses
  
  You can now send responses only visible to the user
Fixed
- ResponseMessage.respond()
  
  Now doesn't show a failed interaction
1.0.5

Fixed
- ResponseMessage.respond()
  
  responding now doesn't fail after sending the message, it will now defer the interaction by it self if not already deferred and then send the message
1.0.4

Added
- ResponseMessage.acknowledged
  
  Whether the message was acknowledged with the ResponseMessage.acknowledged() function
Changed
- ResponseMessage.respond() => await ResponseMessage.respond()
  
  respond() function is now async and needs to be awaited
- ResponseMessage.respond() -> None => ResponseMessage.respond() -> Message or None
  
  respond() now returns the sent message or None if ninja_mode is true
1.0.3

Added
- Button.hash
  
  Buttons have now a custom hash property, generated by the discord api

discord-ui Release 3.0.1

Release 3.0.1 Toggle Dropdown 5.1.6 5.1.5 5.1.4 5.1.3 5.1.2 5.1.1 5.1.0 5.0.2 5.0.1 5.0.0

Documentation

discord-ui

Introduction

Installation

Windows

Linux

License

Issues

Note

Example

Contact

Changelog

Fixed

Breaking changes

Changed

Fixed

Added

Removed

Fixed

Fixed

Changed

Added

Fixed

Changed

Fixed

Removed

Fixed

Fixed

Fixed

Fixed

Fixed

Removed

Fixed

Removed

Added

Changed

Fixed

Fixed

Changed

Fixed

Fixed

Fixed

Fixed

Added

Fixed

Fixed

Added

Fixed

Changed

Fixed

Fixed

Changed

Fixed

Added

Fixed

Fixed

Fixed

Fixed

Added

Fixed

Fixed

Fixed

Fixed

Fixed

Added

Fixed

Changed

Removed

Fixed

Changed

Fixed

Added

Fixed

Added

Added

Fixed

Added

Fixed

discord-ui
Release 3.0.1

Release 3.0.1

5.1.6

5.1.5

5.1.4

5.1.3

5.1.2

5.1.1

5.1.0

5.0.2

5.0.1

5.0.0