Skip to content

hikari.components#

Application and entities that are used to describe components on Discord.

AllowedComponentsT module-attribute #

AllowedComponentsT = typing.TypeVar(
    "AllowedComponentsT", bound="PartialComponent"
)

COMPONENT_V2_TYPES module-attribute #

COMPONENT_V2_TYPES: Final[frozenset[ComponentType]] = (
    frozenset(
        (
            ComponentType.SECTION,
            ComponentType.TEXT_DISPLAY,
            ComponentType.THUMBNAIL,
            ComponentType.MEDIA_GALLERY,
            ComponentType.FILE,
            ComponentType.SEPARATOR,
            ComponentType.CONTAINER,
        )
    )
)

Set of the component types which are considered v2 components and can only be used with the appropriate flag.

The following values are included in this:

ContainerTypesT module-attribute #

ContainerTypesT = typing.Union[
    ActionRowComponent[PartialComponent],
    TextDisplayComponent,
    SectionComponent,
    MediaGalleryComponent,
    SeparatorComponent,
    FileComponent,
]

Type hints of the values which are valid for container components.

The following values are valid for this:

InteractiveButtonTypes module-attribute #

InteractiveButtonTypes: AbstractSet[
    InteractiveButtonTypesT
] = frozenset(
    [
        ButtonStyle.PRIMARY,
        ButtonStyle.SECONDARY,
        ButtonStyle.SUCCESS,
        ButtonStyle.DANGER,
    ]
)

Set of the hikari.components.ButtonStyle which are valid for interactive buttons.

The following values are included in this:

InteractiveButtonTypesT module-attribute #

InteractiveButtonTypesT = typing.Literal[
    ButtonStyle.PRIMARY,
    1,
    ButtonStyle.SECONDARY,
    2,
    ButtonStyle.SUCCESS,
    3,
    ButtonStyle.DANGER,
    4,
]

Type hints of the hikari.components.ButtonStyle values which are valid for interactive buttons.

The following values are valid for this:

MessageActionRowComponent module-attribute #

MessageActionRowComponent = ActionRowComponent[
    MessageComponentTypesT
]

A message action row component.

MessageComponentTypesT module-attribute #

MessageComponentTypesT = typing.Union[
    ButtonComponent, SelectMenuComponent
]

Type hint of the hikari.components.PartialComponent that be contained in a hikari.components.PartialComponent.

The following values are valid for this:

ModalActionRowComponent module-attribute #

ModalActionRowComponent = ActionRowComponent[
    ModalComponentTypesT
]

A modal action row component.

ModalComponentTypesT module-attribute #

ModalComponentTypesT = TextInputComponent

Type hint of the hikari.components.PartialComponent that be contained in a hikari.components.PartialComponent.

The following values are valid for this:

SectionAccessoryTypesT module-attribute #

SectionAccessoryTypesT = typing.Union[
    ButtonComponent, ThumbnailComponent
]

Type hints of the values which are valid for section accessories.

The following values are valid for this:

SectionComponentTypesT module-attribute #

SectionComponentTypesT = TextDisplayComponent

Type hints of the values which are valid for section components.

The following values are valid for this:

SelectMenuTypes module-attribute #

SelectMenuTypes: AbstractSet[SelectMenuTypesT] = frozenset(
    (
        ComponentType.TEXT_SELECT_MENU,
        ComponentType.USER_SELECT_MENU,
        ComponentType.ROLE_SELECT_MENU,
        ComponentType.MENTIONABLE_SELECT_MENU,
        ComponentType.CHANNEL_SELECT_MENU,
    )
)

Set of the hikari.components.ComponentType values which are valid for select menus.

The following values are included in this:

SelectMenuTypesT module-attribute #

SelectMenuTypesT = typing.Literal[
    ComponentType.TEXT_SELECT_MENU,
    3,
    ComponentType.USER_SELECT_MENU,
    5,
    ComponentType.ROLE_SELECT_MENU,
    6,
    ComponentType.MENTIONABLE_SELECT_MENU,
    7,
    ComponentType.CHANNEL_SELECT_MENU,
    8,
]

Type hints of the hikari.components.ComponentType values which are valid for select menus.

The following values are valid for this:

TopLevelComponentTypesT module-attribute #

TopLevelComponentTypesT = typing.Union[
    ActionRowComponent[PartialComponent],
    TextDisplayComponent,
    SectionComponent,
    MediaGalleryComponent,
    SeparatorComponent,
    FileComponent,
    ContainerComponent,
]

Type hints of the values which are valid for top level components.

The following values are valid for this:

ActionRowComponent #

Bases: PartialComponent, Generic[AllowedComponentsT]

Represents a row of components.

components class-attribute instance-attribute #

components: Sequence[AllowedComponentsT] = attrs.field()

Sequence of the components contained within this row.

ButtonComponent #

Bases: PartialComponent

Represents a button component.

custom_id class-attribute instance-attribute #

custom_id: str | None = attrs.field(hash=True)

Developer defined identifier for this button (will be <= 100 characters).

Note

This is required for the following button styles:

emoji class-attribute instance-attribute #

emoji: Emoji | None = attrs.field(eq=False)

Custom or unicode emoji which appears on the button.

is_disabled class-attribute instance-attribute #

is_disabled: bool = attrs.field(eq=False)

Whether the button is disabled.

label class-attribute instance-attribute #

label: str | None = attrs.field(eq=False)

Text label which appears on the button.

style class-attribute instance-attribute #

style: ButtonStyle | int = attrs.field(eq=False)

The button's style.

url class-attribute instance-attribute #

url: str | None = attrs.field(eq=False)

Url for hikari.components.ButtonStyle.LINK style buttons.

ButtonStyle #

Bases: int, Enum

Enum of the available button styles.

More information, such as how these look, can be found at https://discord.com/developers/docs/interactions/message-components#button-object-button-styles

DANGER class-attribute instance-attribute #

DANGER = 4

A red button (usually indicates a destructive action).

LINK = 5

A grey button which navigates to a URL.

Warning

Unlike the other button styles, clicking this one will not trigger an interaction and custom_id shouldn't be included for this style.

PREMIUM class-attribute instance-attribute #

PREMIUM = 6

A button that will link to a specific SKU item.

Warning

Unlike the other button styles, clicking this one will not trigger an interaction and custom_id shouldn't be included for this style.

PRIMARY class-attribute instance-attribute #

PRIMARY = 1

A blurple "call to action" button.

SECONDARY class-attribute instance-attribute #

SECONDARY = 2

A grey neutral button.

SUCCESS class-attribute instance-attribute #

SUCCESS = 3

A green button.

ChannelSelectMenuComponent #

Bases: SelectMenuComponent

Represents a channel select menu component.

channel_types class-attribute instance-attribute #

channel_types: Sequence[int | ChannelType] = attrs.field(
    eq=False
)

The valid channel types for this menu.

ComponentType #

Bases: int, Enum

Types of components found within Discord.

ACTION_ROW class-attribute instance-attribute #

ACTION_ROW = 1

A non-interactive container component for other types of components.

Note

As of writing this can only contain one component type.

BUTTON class-attribute instance-attribute #

BUTTON = 2

A button component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

CHANNEL_SELECT_MENU class-attribute instance-attribute #

CHANNEL_SELECT_MENU = 8

A channel select component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

CONTAINER class-attribute instance-attribute #

CONTAINER = 17

A container component.

Note

As this is a container component it can never be contained within another component and therefore will always be top-level.

FILE class-attribute instance-attribute #

FILE = 13

A file component.

MEDIA_GALLERY = 12

A media gallery component.

MENTIONABLE_SELECT_MENU class-attribute instance-attribute #

MENTIONABLE_SELECT_MENU = 7

A mentionable (users and roles) select component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

ROLE_SELECT_MENU class-attribute instance-attribute #

ROLE_SELECT_MENU = 6

A role select component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

SECTION class-attribute instance-attribute #

SECTION = 9

A section component.

Note

As this is a container component it can never be contained within another component and therefore will always be top-level.

SEPARATOR class-attribute instance-attribute #

SEPARATOR = 14

A separator component.

TEXT_DISPLAY class-attribute instance-attribute #

TEXT_DISPLAY = 10

A text display component.

TEXT_INPUT class-attribute instance-attribute #

TEXT_INPUT = 4

A text input component.

Note

This component may only be used inside a modal container.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

TEXT_SELECT_MENU class-attribute instance-attribute #

TEXT_SELECT_MENU = 3

A text select component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

THUMBNAIL class-attribute instance-attribute #

THUMBNAIL = 11

A thumbnail component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.SECTION.

USER_SELECT_MENU class-attribute instance-attribute #

USER_SELECT_MENU = 5

A user select component.

Note

This cannot be top-level and must be within a container component such as hikari.components.ComponentType.ACTION_ROW.

ContainerComponent #

Bases: PartialComponent

Represents a container component.

accent_color class-attribute instance-attribute #

accent_color: Color | None = attrs.field()

The accent colour for the container.

components class-attribute instance-attribute #

components: Sequence[ContainerTypesT] = attrs.field()

The components within the container.

is_spoiler class-attribute instance-attribute #

is_spoiler: bool = attrs.field()

Whether the container is marked as a spoiler.

FileComponent #

Bases: PartialComponent

Represents a file component.

file class-attribute instance-attribute #

file: MediaResource = attrs.field()

The media for the file.

is_spoiler class-attribute instance-attribute #

is_spoiler: bool = attrs.field()

If the file has a spoiler.

MediaGalleryComponent #

Bases: PartialComponent

Represents a media gallery component.

items class-attribute instance-attribute #

items: Sequence[MediaGalleryItem] = attrs.field()

The media gallery's items.

MediaGalleryItem #

Represents a media gallery item.

description class-attribute instance-attribute #

description: str | None = attrs.field()

The description of the gallery item.

is_spoiler class-attribute instance-attribute #

is_spoiler: bool = attrs.field()

Whether the gallery item is marked as a spoiler.

media class-attribute instance-attribute #

media: MediaResource = attrs.field()

The media for the gallery item.

MediaLoadingType #

Bases: int, Enum

Media loading type.

LOADED_NOT_FOUND class-attribute instance-attribute #

LOADED_NOT_FOUND = 3

Media was not found.

LOADED_SUCCESS class-attribute instance-attribute #

LOADED_SUCCESS = 2

Media has successfully loaded.

LOADING class-attribute instance-attribute #

LOADING = 1

Media is loading.

UNKNOWN class-attribute instance-attribute #

UNKNOWN = 0

Media is in an unknown loading state.

MediaResource #

Bases: Resource[AsyncReader]

Represents a media resource.

content_type class-attribute instance-attribute #

content_type: UndefinedNoneOr[str] = attrs.field(repr=True)

The content type of the media item.

filename property #

filename: str

File name of this embed resource.

height class-attribute instance-attribute #

height: UndefinedNoneOr[int] = attrs.field(repr=True)

The height of the media item.

loading_state class-attribute instance-attribute #

loading_state: UndefinedNoneOr[MediaLoadingType] = (
    attrs.field(repr=True)
)

The loading state of the media item.

proxy_filename property #

proxy_filename: str | None

File name of the proxied version of this embed resource if applicable, else None.

proxy_resource class-attribute instance-attribute #

proxy_resource: Resource[AsyncReader] | None = attrs.field(
    default=None, repr=False
)

The proxied version of the resource, or None if not present.

Note

This field cannot be set by bots or webhooks while sending an embed and will be ignored during serialization. Expect this to be populated on any received embed attached to a message event.

proxy_url property #

proxy_url: str | None

Proxied URL of this embed resource if applicable, else None.

resource class-attribute instance-attribute #

resource: Resource[AsyncReader] = attrs.field(repr=True)

The resource this object wraps around.

url property #

url: str

URL of this embed resource.

width class-attribute instance-attribute #

width: UndefinedNoneOr[int] = attrs.field(repr=True)

The width of media item.

stream #

stream(
    *,
    executor: Executor | None = None,
    head_only: bool = False,
) -> AsyncReaderContextManager[AsyncReader]

Produce a stream of data for the resource.

PARAMETER DESCRIPTION
executor

The executor to run in for blocking operations. If None, then the default executor is used for the current event loop.

TYPE: Executor | None DEFAULT: None

head_only

If True, then the implementation may only retrieve HEAD information if supported. This currently only has any effect for web requests.

TYPE: bool DEFAULT: False

PartialComponent #

Base class for all component entities.

id class-attribute instance-attribute #

id: int = attrs.field()

The ID of the interaction.

type class-attribute instance-attribute #

type: ComponentType | int = attrs.field()

The type of component this is.

SectionComponent #

Bases: PartialComponent

Represents a section component.

accessory class-attribute instance-attribute #

accessory: SectionAccessoryTypesT = attrs.field()

The sections accessory.

components class-attribute instance-attribute #

components: Sequence[SectionComponentTypesT] = attrs.field()

The sections components.

SelectMenuComponent #

Bases: PartialComponent

Represents a select menu component.

custom_id class-attribute instance-attribute #

custom_id: str = attrs.field(hash=True)

Developer defined identifier for this menu (will be <= 100 characters).

is_disabled class-attribute instance-attribute #

is_disabled: bool = attrs.field(eq=False)

Whether the select menu is disabled.

max_values class-attribute instance-attribute #

max_values: int = attrs.field(eq=False)

The minimum amount of options which can be chosen for this menu.

This will be less than or equal to 25 and will be greater than or equal to hikari.components.SelectMenuComponent.min_values.

min_values class-attribute instance-attribute #

min_values: int = attrs.field(eq=False)

The minimum amount of options which must be chosen for this menu.

This will be greater than or equal to 0 and will be less than or equal to hikari.components.SelectMenuComponent.max_values.

placeholder class-attribute instance-attribute #

placeholder: str | None = attrs.field(eq=False)

Custom placeholder text shown if nothing is selected, max 100 characters.

SelectMenuOption #

Represents an option for a hikari.components.SelectMenuComponent.

description class-attribute instance-attribute #

description: str | None = attrs.field()

Optional description of the option, max 100 characters.

emoji class-attribute instance-attribute #

emoji: Emoji | None = attrs.field(eq=False)

Custom or unicode emoji which appears on the button.

is_default class-attribute instance-attribute #

is_default: bool = attrs.field()

Whether this option will be selected by default.

label class-attribute instance-attribute #

label: str = attrs.field()

User-facing name of the option, max 100 characters.

value class-attribute instance-attribute #

value: str = attrs.field()

Dev-defined value of the option, max 100 characters.

SeparatorComponent #

Bases: PartialComponent

Represents the separator component.

divider class-attribute instance-attribute #

divider: bool = attrs.field()

If there is a divider for the separator.

spacing class-attribute instance-attribute #

spacing: SpacingType = attrs.field()

The spacing for the separator.

SpacingType #

Bases: int, Enum

Spacing Type.

The type of spacing for a [SeparatorComponent][]

LARGE class-attribute instance-attribute #

LARGE = 2

A large separator.

SMALL class-attribute instance-attribute #

SMALL = 1

A small separator.

TextDisplayComponent #

Bases: PartialComponent

Represents a text display component.

content class-attribute instance-attribute #

content: str = attrs.field()

The content of the text display.

TextInputComponent #

Bases: PartialComponent

Represents a text input component.

custom_id class-attribute instance-attribute #

custom_id: str = attrs.field(repr=True)

Developer set custom ID used for identifying interactions with this modal.

value class-attribute instance-attribute #

value: str = attrs.field(repr=True)

Value provided for this text input.

TextInputStyle #

Bases: int, Enum

A text input style.

PARAGRAPH class-attribute instance-attribute #

PARAGRAPH = 2

Intended for much longer inputs.

SHORT class-attribute instance-attribute #

SHORT = 1

Intended for short single-line text.

TextSelectMenuComponent #

Bases: SelectMenuComponent

Represents a text select menu component.

options class-attribute instance-attribute #

options: Sequence[SelectMenuOption] = attrs.field(eq=False)

Sequence of up to 25 of the options set for this menu.

ThumbnailComponent #

Bases: PartialComponent

Represents a thumbnail component.

description class-attribute instance-attribute #

description: str | None = attrs.field()

The description of the thumbnail.

is_spoiler class-attribute instance-attribute #

is_spoiler: bool = attrs.field()

Whether the thumbnail is marked as a spoiler.

media class-attribute instance-attribute #

media: MediaResource = attrs.field()

The media for the thumbnail.