Skip to main content
Command options define the parameters that users can provide when using slash commands.

​
Option

Represents a selectable option for a slash command.

​
Parameters

​
input_type
Type
default:"str"
The type of input that is expected for this option. Can be:
  • Basic types: str, int, float, bool
  • Discord types: User, Member, Role, GuildChannel, Thread, Attachment, Mentionable
  • SlashCommandOptionType enum
  • Converter or converter class
  • enum.Enum - If the enum has ≤25 values, choices are auto-filled. If >25 values, autocomplete is used.
​
description
str
The description of this option. Must be 100 characters or fewer. If input_type is an Enum and description is not specified, the Enum’s docstring will be used.
​
name
str
The name of this option visible in the UI. Inherits from the variable name if not provided as a parameter.
​
choices
Optional[List[Union[Any, OptionChoice]]]
The list of available choices for this option. Can be a list of values or OptionChoice objects. If provided, the input from the user must match one of the choices.
​
required
bool
default:"True"
Whether this option is required. Automatically set to False if default is provided.
​
default
Any
The default value for this option. If provided, required will be considered False.
​
min_value
Optional[Union[int, float]]
The minimum value that can be entered. Only applies to Options with an input_type of int or float.
​
max_value
Optional[Union[int, float]]
The maximum value that can be entered. Only applies to Options with an input_type of int or float.
​
min_length
Optional[int]
The minimum length of the string that can be entered. Must be between 0 and 6000 (inclusive). Only applies to Options with an input_type of str.
​
max_length
Optional[int]
The maximum length of the string that can be entered. Must be between 1 and 6000 (inclusive). Only applies to Options with an input_type of str.
​
channel_types
Optional[List[ChannelType]]
A list of channel types that can be selected in this option. Only applies to Options with an input_type of SlashCommandOptionType.channel. If this argument is used, input_type will be ignored.
​
autocomplete
Optional[AutocompleteFunction]
The autocomplete handler for the option. Accepts a callable (sync or async) that takes an AutocompleteContext or Cog and AutocompleteContext. Must return an iterable of str, int, float, or OptionChoice.
​
name_localizations
Dict[str, str]
The name localizations for this option. The values of this should be "locale": "name". See Discord’s locales documentation for valid locales.
​
description_localizations
Dict[str, str]
The description localizations for this option. The values should be "locale": "description".

​
Attributes

​
input_type
SlashCommandOptionType
The resolved input type for this option.
​
name
str
The name of the option.
​
description
str
The description of the option.
​
required
bool
Whether this option is required.
​
choices
List[OptionChoice]
The list of available choices for this option.
​
autocomplete
Optional[AutocompleteFunction]
The autocomplete handler for the option. Does not validate the input value against the autocomplete results.

​
OptionChoice

Represents a name:value pairing for a selected Option.

​
Parameters

​
name
str
required
The name of the choice. Shown in the UI when selecting an option.
​
value
Optional[Union[str, int, float]]
The value of the choice. If not provided, will use the value of name.
​
name_localizations
Dict[str, str]
The name localizations for this choice. The values should be "locale": "name".

​
Attributes

​
name
str
The display name of the choice.
​
value
Union[str, int, float]
The actual value that gets passed to the command.

​
option()

A decorator that can be used instead of typehinting Option.
​
name
str
required
The name of the option in the Discord UI.
​
input_type
Type
The type of input expected. Defaults to the parameter’s type annotation.
​
parameter_name
str
The name of the target function parameter this option is mapped to. This allows you to have a separate UI name and parameter name.
​
**kwargs
dict
Additional keyword arguments to pass to the Option constructor.
Returns: A decorator function.

​
ThreadOption

Represents a class that can be passed as the input_type for an Option class to specify thread types.

​
Parameters

​
thread_type
Literal['public', 'private', 'news']
required
The thread type to expect for this option’s input.

​
Examples

import discord
from discord.commands import Option

bot = discord.Bot()

@bot.slash_command(description="Greet a user")
async def greet(
    ctx: discord.ApplicationContext,
    name: Option(str, "Enter your name"),
    age: Option(int, "Enter your age", min_value=1, max_value=120, required=False)
):
    if age:
        await ctx.respond(f"Hello {name}! You are {age} years old.")
    else:
        await ctx.respond(f"Hello {name}!")

bot.run("token")

Build docs developers (and LLMs) love

Get started for freeTalk to us