Components¶

Layouts¶

class uicord.View(*items, owner: int | None = None, lang: str | None = None)¶

Bases: DesignerView, UIMember

The main container for every component.

Parameters:

*items – Components to add at construction time.
owner – User ID that is allowed to interact with this view. When None anyone may use it.
lang – Default language passed to UIString when resolving translated labels inside this view.

add(component)¶

Add component to the view and return it (fluent helper).

Parameters:: component – The component to be added.
Returns:: The component that was added.

async interaction_check(ctx: Interaction) → bool¶

|coro|

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.

If this returns False, on_check_failure() is called.

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

async reload(ctx: Interaction) → None¶

Reload the current view, updating every unsynced component.

Silently defers if the interaction has already been responded to.

class uicord.Modal(title: str = 'Modal Title', lang: str | None = None)¶

Bases: DesignerModal, UIMember

The main input/output system for modal interactions.

Parameters:

title – Title displayed at the top of the modal.
lang – Default language passed to UIString when resolving translated labels inside this modal.

add_input(label: str = 'input label', style: str = 'short', placeholder: str | None = None, default: str | None = None, required: bool = True) → InputText¶

Add a text-input field to the modal.

Parameters:

label – The field’s label (supports UIString).
style – "short" for a single-line input, "long" for paragraph.
placeholder – Ghost text shown when the field is empty.
default – Pre-filled value.
required – Whether the user must fill in this field.

Returns:

The underlying input object (useful for reading .value later).

Return type:

discord.ui.InputText

add_item(label: str = 'input label', item=None, component=None)¶

Add an arbitrary component to the modal wrapped in a ui.Label.

Parameters:

label – The label shown above the component.
component (item /) – The component to add (either keyword works).
required – Whether the user requires a item to fill in

Return type:

The component that was added.

async callback(ctx: Interaction) → None¶: Called when the modal is submitted. Override in subclasses.

async get_value(index: int = 0)¶

Return the value of the text input at index.

Parameters:: index – Zero-based position of the input that was added.

property values: list¶: All input values in order (None for inputs without a value).

Decorators¶

uicord.interaction(component=None)¶

Decorator that assigns an async callback to component.

Any exception raised inside the callback is:

Pretty-printed to stdout.
DMed to every user ID in state.DEV_IDS.
Reported to the interacting user with an ephemeral error message.

Usage:

btn = Button("Click me")

@interaction(btn)
async def on_click(ctx):
    await ctx.respond("clicked!")

Example¶

MyView = View()
MyBtn = Button()
MyView.add(MyBtn)

@uicord.interaction(component=MyBtn)
async def btnclick(ctx):
    print("BUTTON WAS CLICKED!!!!")
    await ctx.respond("Yay you clicked my button")

Components¶

class uicord.Container(*items, **kwargs)¶

Bases: Container, UIMember

A regular Discord container component.

class uicord.Button(text: str = 'My Button', label: str = None, emoji=None, color: int = 2, url: str | None = None, id: str | None = None, disabled: bool = False, callback=None)¶

Bases: Button, UIMember

An interactable button.

Parameters:

text – Label shown on the button.
label – Alias for text.
emoji – Optional emoji displayed alongside the label.
color – One of the Colors constants. Defaults to grey.
url – If provided the button becomes a link-button.
id – Custom ID used to identify the button interaction.
disabled – Whether the button is greyed-out.
callback – Optional coroutine to set as the callback immediately.

property color: int¶: The style / colour of the button.

class uicord.Toggle(*args, cb=<function EMPTY_CALLBACK>, default: bool = True, custom_on: str | None = None, custom_off: str | None = None, **kwargs)¶

Bases: Button, UIMember

A stateful toggle button that flips between an on and off emoji.

Parameters:

**kwargs (*args /) –
Forwarded to Button.
cb – Async callback invoked after the toggle state changes.
default – Initial state - True = on, False = off.
custom_on – Emoji shown when the toggle is on. Defaults to "✅".
custom_off – Emoji shown when the toggle is off. Defaults to "❌".

async callback(ctx) → None¶: Flip the toggle state then call the user’s callback.

class uicord.ActionRow(*args, **kwargs)¶

Bases: ActionRow, UIMember

A regular pycord discord.ui.ActionRow.

Parameters:

**kwargs (*args /) –

Forwarded to the parent.

add(*a, **k)¶: Macro for add_item().

class uicord.Text(text: str = 'myText')¶

Bases: TextDisplay, UIMember

Text display for a View or Modal.

Parameters:: text – The string (or UIString) to display.

class uicord.Grid(rows: int = 2, cols: int | None = None, texts: list[GridItem] | None = None, width: int = 30)¶

Grid display for a View

Parameters:

rows – The amount of rows in a grid.
cols – The amount of cols in a grid.
texts – The list of GridItem to display.
width – The maximum width a column can take.

build()¶

class uicord.GridItem(text='Hi', emoji=None)¶

Item for a Grid

Parameters:

text – The string (or UIString) to display.
emoji – Optional emoji to be seen besides the text.

class uicord.Separator(*, divider: bool = True)¶

Bases: Separator, UIMember

A regular Discord separator component.

class uicord.Thumbnail(url: str)¶

Bases: Thumbnail, UIMember

A regular Discord thumbnail component.

class uicord.Section(*items, **kwargs)¶

Bases: Section, UIMember

A regular Discord section component.

class uicord.MediaGallery(*items, **kwargs)¶

Bases: MediaGallery, UIMember

A regular Discord media gallery component.

class uicord.MediaGalleryItem(*items, **kwargs)¶

Bases: MediaGalleryItem, UIMember

A regular Discord media gallery item.

class uicord.Choices(type=('string_select', 3), placeholder='Pick', options=[], required=False, min_values=1, max_values=1)¶

Bases: Select, UIMember

A select / drop-down menu.

Parameters:

type – discord.ComponentType for the select kind (string, user, role …).
placeholder – Hint text shown when nothing is selected.
options – Pre-built list of discord.SelectOption objects.
required – Checks if the Select menu is required inside a modal.

add(option: str = 'Option', emoji=None, description: str | None = None, default: bool = False) → None¶

Add a new select option.

Parameters:

option – Displayed label.
emoji – Optional emoji.
description – Sub-text below the label.
default – Whether this option is pre-selected.

async callback(ctx) → None¶: Default callback: update then reload the parent view.

async disable(v: bool = True) → None¶: Disable (or re-enable) the select and persist the selection.

async force(index: int) → None¶: DEPRECATED - no longer functional, kept for API compatibility.

property picked¶: The currently selected value, or the default option’s value.

async update() → None¶: Refresh the select’s buffer (re-enables it).

Pycord 2.8+ Components¶

Note

The following components require pycord ≥ 2.8. On older versions, instantiating them raises NotImplementedError.

class uicord.Checkbox(*, custom_id: str | None = None, default: bool = False, id: int | None = None, label: str | None = None)¶

Bases: Checkbox, UIMember

A Discord checkbox component (pycord ≥ 2.8).

Parameters:

custom_id – The interaction ID for this checkbox.
default – Whether the checkbox is checked by default.
id – The component’s numeric ID.
label – Human-readable label (library convenience - wraps in a discord.ui.Label automatically when added to a modal).

property checked: bool | None¶: Whether the user checked this box (available after submission).

property label: str | None¶

class uicord.CheckboxGroup(*checkboxes, custom_id: str | None = None, required: bool = True, min_values: int = 0, max_values: int = 1)¶

Bases: CheckboxGroup, UIMember

A group of Discord checkboxes (pycord ≥ 2.8).

Parameters:

*checkboxes – Checkbox instances to include.
custom_id – Interaction ID for the group.
required – Whether at least one checkbox must be selected.
max_values (min_values /) – Selection count constraints (0-10 / 1-10).

property checked_values: list[bool] | None¶: List of selected states after submission.

Internationalisation¶

class uicord.UIString(text: str = '', lang: str | None = None)¶

Bases: str

A string subclass that is optionally passed through state.translator_function at creation time.

Parameters:

text – The raw string or translation key.
lang – The language code to pass to the translator. When None the translator receives None and can fall back to a default locale.

translate(lang: str | None = None) → UIString¶: Return a new UIString translated into lang.

with_lang(lang: str | None) → UIString¶: Alias for translate().

Example¶

from uicord import state, UIString, View, Button

# Plug in your own translation backend
state.translator_function = lambda text, lang: my_i18n(text, lang)

# Strings are translated at construction time
label = UIString("btn.confirm")            # uses lang=None (default locale)
label_fr = UIString("btn.confirm", lang="fr")

# Views and Modals carry a lang that UIString picks up automatically
view = View(lang="fr")
btn  = Button(view._("btn.confirm"))       # translated to French

State¶

uicord.state¶: alias of <uicord.state._State object>

Utilities¶

class uicord.Container(*items, **kwargs)¶

Bases: Container, UIMember

A regular Discord container component.

class uicord.Button(text: str = 'My Button', label: str = None, emoji=None, color: int = 2, url: str | None = None, id: str | None = None, disabled: bool = False, callback=None)¶

Bases: Button, UIMember

An interactable button.

Parameters:

text – Label shown on the button.
label – Alias for text.
emoji – Optional emoji displayed alongside the label.
color – One of the Colors constants. Defaults to grey.
url – If provided the button becomes a link-button.
id – Custom ID used to identify the button interaction.
disabled – Whether the button is greyed-out.
callback – Optional coroutine to set as the callback immediately.

property color: int¶: The style / colour of the button.

class uicord.ActionRow(*args, **kwargs)¶

Bases: ActionRow, UIMember

A regular pycord discord.ui.ActionRow.

Parameters:

**kwargs (*args /) –

Forwarded to the parent.

add(*a, **k)¶: Macro for add_item().

class uicord.Text(text: str = 'myText')¶

Bases: TextDisplay, UIMember

Text display for a View or Modal.

Parameters:: text – The string (or UIString) to display.

class uicord.Separator(*, divider: bool = True)¶

Bases: Separator, UIMember

A regular Discord separator component.

class uicord.Thumbnail(url: str)¶

Bases: Thumbnail, UIMember

A regular Discord thumbnail component.

class uicord.Section(*items, **kwargs)¶

Bases: Section, UIMember

A regular Discord section component.

class uicord.Choices(type=('string_select', 3), placeholder='Pick', options=[], required=False, min_values=1, max_values=1)¶

Bases: Select, UIMember

A select / drop-down menu.

Parameters:

type – discord.ComponentType for the select kind (string, user, role …).
placeholder – Hint text shown when nothing is selected.
options – Pre-built list of discord.SelectOption objects.
required – Checks if the Select menu is required inside a modal.

add(option: str = 'Option', emoji=None, description: str | None = None, default: bool = False) → None¶

Add a new select option.

Parameters:

option – Displayed label.
emoji – Optional emoji.
description – Sub-text below the label.
default – Whether this option is pre-selected.

async callback(ctx) → None¶: Default callback: update then reload the parent view.

async disable(v: bool = True) → None¶: Disable (or re-enable) the select and persist the selection.

async force(index: int) → None¶: DEPRECATED - no longer functional, kept for API compatibility.

property picked¶: The currently selected value, or the default option’s value.

async update() → None¶: Refresh the select’s buffer (re-enables it).

dev