Skip to content
hikari-risa hikari-risa

risa.ui.nodes

The components a view's layout is built from, Discord's Components V2.

A layout is one top-level component or a sequence of them. Interactive components take the handler a click routes to, bare as self.save or with wire arguments as risa.bind(self.vote, 2). risa checks only what Discord cannot: that each custom_id fits, and that each handler belongs to the view. Discord's own limits, such as five buttons to a row, are left to Discord.

ContainerChild 

ContainerChild = File | MediaGallery | Row | Section | Separator | TextDisplay

A component that fits in a Container.

Layout 

Layout = TopLevelComponent | Sequence[TopLevelComponent]

What View.render returns: one top-level component, or several in order.

RowChild 

RowChild = (
    Button
    | ChannelSelect
    | LinkButton
    | MentionableSelect
    | PremiumButton
    | RoleSelect
    | TextSelect
    | UserSelect
)

A component that fits in a Row.

SectionAccessory 

SectionAccessory = Button | LinkButton | PremiumButton | Thumbnail

A component that fits beside the text of a Section.

TopLevelComponent 

TopLevelComponent = Container | ContainerChild

A component that can stand at the top of a message.

Button 

Button(
    handler: Handlerish,
    *,
    label: str | None = None,
    emoji: Snowflakeish | Emoji | str | None = None,
    style: ButtonStyle = PRIMARY,
    disabled: bool = False,
)

Bases: Interactive

A button whose clicks route to a handler.

Parameters:

  • handler (Handlerish) –

    The handler a click routes to, bare or through risa.bind.

  • label (str | None, default: None ) –

    The text on the button.

  • emoji (Snowflakeish | Emoji | str | None, default: None ) –

    An emoji on the button.

  • style (ButtonStyle, default: PRIMARY ) –

    The button's color.

  • disabled (bool, default: False ) –

    Grey the button out, so it cannot be clicked.

disabled property 

disabled: bool

Whether the button is greyed out.

emoji property 

emoji: Snowflakeish | Emoji | str | None

The emoji on the button, if any.

label property 

label: str | None

The text on the button, if any.

style property 

style: ButtonStyle

The button's color.

build 

build(ctx: BuildContext, path: str) -> InteractiveButtonBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

ChannelSelect 

ChannelSelect(
    handler: Handlerish,
    *,
    channel_types: Sequence[ChannelType] = (),
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: Select

A select menu of channels. The handler finds them in ctx.resolved.

Parameters:

  • handler (Handlerish) –

    The handler a pick routes to, bare or through risa.bind.

  • channel_types (Sequence[ChannelType], default: () ) –

    The kinds of channel to offer; every kind by default.

  • placeholder (str | None, default: None ) –

    The text shown while nothing is picked.

  • min_values (int, default: 1 ) –

    The fewest channels the user must pick.

  • max_values (int, default: 1 ) –

    The most channels the user may pick.

  • disabled (bool, default: False ) –

    Grey the menu out.

channel_types property 

channel_types: Sequence[ChannelType]

The kinds of channel offered; empty for every kind.

build 

build(ctx: BuildContext, path: str) -> ChannelSelectMenuBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Component

Bases: ABC

Base class of every component a layout can hold.

name property 

name: str

The component's type name, used in tree paths.

build abstractmethod 

build(ctx: BuildContext, path: str) -> ComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Container 

Container(
    *children: ContainerChild,
    accent_color: Colorish | None = None,
    spoiler: bool = False,
)

Bases: Component

A box around components, like an embed, with an optional accent color.

Parameters:

  • *children (ContainerChild, default: () ) –

    The components inside.

  • accent_color (Colorish | None, default: None ) –

    The color of the stripe down the left side.

  • spoiler (bool, default: False ) –

    Hide the contents behind a spoiler.

accent_color property 

accent_color: Colorish | None

The color of the stripe down the left side, if any.

children property 

children: Sequence[ContainerChild]

The components inside.

spoiler property 

spoiler: bool

Whether the contents are hidden behind a spoiler.

build 

build(ctx: BuildContext, path: str) -> ContainerComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

File 

File(file: Resourceish, *, spoiler: bool = False)

Bases: Component

An attached file, shown as a download.

Parameters:

  • file (Resourceish) –

    The file: a path, bytes, or data named through hikari.Bytes. Discord's documentation allows only attachment:// references for a file, so a URL will not do.

  • spoiler (bool, default: False ) –

    Hide it behind a spoiler.

file property 

file: Resourceish

The file.

spoiler property 

spoiler: bool

Whether it is hidden behind a spoiler.

build 

build(ctx: BuildContext, path: str) -> FileComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Interactive 

Interactive(handler: Handlerish)

Bases: Component

Base class of the components a click routes from to a handler.

Parameters:

  • handler (Handlerish) –

    The handler a click routes to, bare or through risa.bind.

binding property 

binding: Binding

The handler a click routes to, with its wire arguments.

LinkButton 

LinkButton(
    url: str,
    *,
    label: str | None = None,
    emoji: Snowflakeish | Emoji | str | None = None,
    disabled: bool = False,
)

Bases: Component

A button that opens a URL. Clicks on it never reach the bot.

Parameters:

  • url (str) –

    The URL to open.

  • label (str | None, default: None ) –

    The text on the button.

  • emoji (Snowflakeish | Emoji | str | None, default: None ) –

    An emoji on the button.

  • disabled (bool, default: False ) –

    Grey the button out.

disabled property 

disabled: bool

Whether the button is greyed out.

emoji property 

emoji: Snowflakeish | Emoji | str | None

The emoji on the button, if any.

label property 

label: str | None

The text on the button, if any.

url property 

url: str

The URL the button opens.

build 

build(ctx: BuildContext, path: str) -> LinkButtonBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

MediaGallery 

MediaGallery(*items: MediaGalleryItem)

Bases: Component

A grid of images and videos.

Parameters:

items property 

items: Sequence[MediaGalleryItem]

The images and videos, in order.

build 

build(ctx: BuildContext, path: str) -> MediaGalleryComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

MediaGalleryItem 

MediaGalleryItem(
    media: Resourceish, *, description: str | None = None, spoiler: bool = False
)

One image or video of a MediaGallery.

Parameters:

  • media (Resourceish) –

    The image or video: a URL, a file, or anything else hikari accepts as a resource.

  • description (str | None, default: None ) –

    Alternative text for it.

  • spoiler (bool, default: False ) –

    Blur it until it is clicked.

description property 

description: str | None

The alternative text, if any.

media property 

media: Resourceish

The image or video.

spoiler property 

spoiler: bool

Whether it is blurred until clicked.

build 

build() -> MediaGalleryItemBuilder

Return hikari's builder for the item.

MentionableSelect 

MentionableSelect(
    handler: Handlerish,
    *,
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: _EntitySelect

A select menu of users and roles. The handler finds them in ctx.resolved.

It takes the parameters of Select.

PremiumButton 

PremiumButton(sku_id: Snowflakeish, *, disabled: bool = False)

Bases: Component

A button that offers one of the app's SKUs for purchase.

Parameters:

  • sku_id (Snowflakeish) –

    The SKU to offer.

  • disabled (bool, default: False ) –

    Grey the button out.

disabled property 

disabled: bool

Whether the button is greyed out.

sku_id property 

sku_id: Snowflakeish

The SKU the button offers.

build 

build(ctx: BuildContext, path: str) -> PremiumButtonBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

RoleSelect 

RoleSelect(
    handler: Handlerish,
    *,
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: _EntitySelect

A select menu of roles. The handler finds them in ctx.resolved.

It takes the parameters of Select.

Row 

Row(*components: RowChild)

Bases: Component

A row of buttons, or a single select menu.

Parameters:

  • *components (RowChild, default: () ) –

    The buttons or the select menu, in order.

components property 

components: Sequence[RowChild]

The components in the row.

build 

build(ctx: BuildContext, path: str) -> MessageActionRowBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Section 

Section(*text_displays: TextDisplay, accessory: SectionAccessory)

Bases: Component

Text with a button or a thumbnail beside it.

Parameters:

  • *text_displays (TextDisplay, default: () ) –

    The text, as one or more TextDisplays.

  • accessory (SectionAccessory) –

    The button or thumbnail beside the text.

accessory property 

accessory: SectionAccessory

The button or thumbnail beside the text.

text_displays property 

text_displays: Sequence[TextDisplay]

The text displays.

build 

build(ctx: BuildContext, path: str) -> SectionComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Select 

Select(
    handler: Handlerish,
    *,
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: Interactive

Base class of the select menus. The handler reads the picks from ctx.values.

Parameters:

  • handler (Handlerish) –

    The handler a pick routes to, bare or through risa.bind.

  • placeholder (str | None, default: None ) –

    The text shown while nothing is picked.

  • min_values (int, default: 1 ) –

    The fewest picks the user must make.

  • max_values (int, default: 1 ) –

    The most picks the user may make.

  • disabled (bool, default: False ) –

    Grey the menu out.

disabled property 

disabled: bool

Whether the menu is greyed out.

max_values property 

max_values: int

The most options the user may pick.

min_values property 

min_values: int

The fewest options the user must pick.

placeholder property 

placeholder: str | None

The text shown while nothing is picked, if any.

SelectOption 

SelectOption(
    label: str,
    value: str | None = None,
    *,
    description: str | None = None,
    emoji: Snowflakeish | Emoji | str | None = None,
    default: bool = False,
)

One option of a TextSelect.

Parameters:

  • label (str) –

    The text the user sees.

  • value (str | None, default: None ) –

    What the handler receives in ctx.values when it is picked; the label by default.

  • description (str | None, default: None ) –

    A line of text under the label.

  • emoji (Snowflakeish | Emoji | str | None, default: None ) –

    An emoji beside the label.

  • default (bool, default: False ) –

    Pick it in advance.

default property 

default: bool

Whether the option is picked in advance.

description property 

description: str | None

The line under the label, if any.

emoji property 

emoji: Snowflakeish | Emoji | str | None

The emoji beside the label, if any.

label property 

label: str

The text the user sees.

value property 

value: str

What the handler receives when the option is picked.

build 

build() -> SelectOptionBuilder

Return hikari's builder for the option.

Separator 

Separator(*, divider: bool = True, spacing: SpacingType = SMALL)

Bases: Component

Space between components, with or without a dividing line.

Parameters:

  • divider (bool, default: True ) –

    Draw a line.

  • spacing (SpacingType, default: SMALL ) –

    How much space to leave.

divider property 

divider: bool

Whether a line is drawn.

spacing property 

spacing: SpacingType

How much space is left.

build 

build(ctx: BuildContext, path: str) -> SeparatorComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

TextDisplay 

TextDisplay(content: str)

Bases: Component

Markdown text.

Parameters:

  • content (str) –

    The text, in Discord's markdown.

content property 

content: str

The text, in Discord's markdown.

build 

build(ctx: BuildContext, path: str) -> TextDisplayComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

TextSelect 

TextSelect(
    handler: Handlerish,
    /,
    *options: SelectOption,
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: Select

A select menu of the options the bot lists, as SelectOptions.

Parameters:

  • handler (Handlerish) –

    The handler a pick routes to, bare or through risa.bind.

  • *options (SelectOption, default: () ) –

    The options, in order.

  • placeholder (str | None, default: None ) –

    The text shown while nothing is picked.

  • min_values (int, default: 1 ) –

    The fewest options the user must pick.

  • max_values (int, default: 1 ) –

    The most options the user may pick.

  • disabled (bool, default: False ) –

    Grey the menu out.

options property 

options: Sequence[SelectOption]

The options, in order.

build 

build(ctx: BuildContext, path: str) -> TextSelectMenuBuilder[NoReturn]

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

Thumbnail 

Thumbnail(
    media: Resourceish, *, description: str | None = None, spoiler: bool = False
)

Bases: Component

A small image, as the accessory of a Section.

Parameters:

  • media (Resourceish) –

    The image: a URL, a file, or anything else hikari accepts as a resource.

  • description (str | None, default: None ) –

    Alternative text for the image.

  • spoiler (bool, default: False ) –

    Blur the image until it is clicked.

description property 

description: str | None

The alternative text, if any.

media property 

media: Resourceish

The image.

spoiler property 

spoiler: bool

Whether the image is blurred until clicked.

build 

build(ctx: BuildContext, path: str) -> ThumbnailComponentBuilder

Turn the component into hikari's builder for it.

risa calls this while building a view, once to measure the layout and once to emit it; path names the component's place in the tree for error messages.

Parameters:

  • ctx (BuildContext) –

    The build in progress, which hands out the custom_id of an interactive component.

  • path (str) –

    Where the component stands in the tree, for example Row[0] > Button[1].

UserSelect 

UserSelect(
    handler: Handlerish,
    *,
    placeholder: str | None = None,
    min_values: int = 1,
    max_values: int = 1,
    disabled: bool = False,
)

Bases: _EntitySelect

A select menu of users. The handler finds them in ctx.resolved.

It takes the parameters of Select.