BdApi.UI

Create user interfaces and dialogs

UI is a utility class for creating user interfaces. It provides methods for showing modals, toasts, notices, and building settings panels.

Methods

alert

Shows a generic but very customizable modal.

BdApi.UI.alert("Warning", "This action cannot be undone!");

// With React elements
BdApi.UI.alert("Title", [
    "This is a ",
    BdApi.React.createElement("strong", {}, "bold"),
    " message."
]);

title · string · required

Title of the modal.

content · string | ReactElement | Array<string | ReactElement> · required

Content to display in the modal. Can be a string, React element, or array of both.

showConfirmationModal

Shows a generic but very customizable confirmation modal with optional confirm and cancel callbacks.

BdApi.UI.showConfirmationModal("Delete Item", "Are you sure you want to delete this?", {
    danger: true,
    confirmText: "Delete",
    cancelText: "Cancel",
    onConfirm: () => {
        console.log("Item deleted");
    },
    onCancel: () => {
        console.log("Deletion cancelled");
    }
});

title · string · required

Title of the modal.

content · string | ReactElement | Array<string | ReactElement> · required

Single or mixed array of React elements and strings. Everything is wrapped in Discord’s TextElement component so strings will show and render properly.

options · object

Options to modify the modal.

Show properties

danger · boolean · default: "false"

Whether the main button should be red or not.

confirmText · string · default: "Okay"

Text for the confirmation/submit button.

cancelText · string · default: "Cancel"

Text for the cancel button.

onConfirm · function

Callback to occur when clicking the submit button.

onCancel · function

Callback to occur when clicking the cancel button.

onClose · function

Callback to occur when exiting the modal.

Returns: string - The key used for this modal

showChangelogModal

Shows a changelog modal in a similar style to Discord’s. Customizable with images, videos, colored sections and supports markdown.

BdApi.UI.showChangelogModal({
    title: "My Plugin v2.0",
    subtitle: "Major Update",
    blurb: "This update brings exciting new features!",
    banner: "https://example.com/banner.jpg",
    changes: [
        {
            title: "New Features",
            type: "added",
            items: [
                "Added dark mode support",
                "Added user customization options"
            ]
        },
        {
            title: "Bug Fixes",
            type: "fixed",
            items: [
                "Fixed crash on startup",
                "Fixed memory leak"
            ]
        },
        {
            title: "Improvements",
            type: "improved",
            items: [
                "Improved performance by 50%",
                "Better error messages"
            ]
        }
    ],
    footer: "Thank you for using my plugin!"
});

options · object · required

Information to display in the modal.

Show properties

title · string · required

Title to show in the modal header.

subtitle · string · required

Title to show below the main header.

blurb · string

Text to show in the body of the modal before the list of changes.

banner · string

URL to an image to display as the banner of the modal.

video · string

YouTube link or URL of a video file to use as the banner.

poster · string

URL to use for the video freeze-frame poster.

footer · string | ReactElement | Array<string | ReactElement>

What to show in the modal footer.

changes · Array<Changes>

List of changes to show. Each change object has:

• title (string): Section title
• type (string): One of “fixed”, “added”, “progress”, “improved”
• items (Array<string>): List of change items
• blurb (string, optional): Additional description

Returns: string - The key used for this modal

showInviteModal

Shows a modal for joining a guild like you would natively through Discord.

BdApi.UI.showInviteModal("discord-api");

inviteCode · string · required

The Discord invite code (without the discord.gg/ part).

showToast

Shows a toast notification similar to Android towards the bottom of the screen.

BdApi.UI.showToast("Settings saved!", {type: "success"});
BdApi.UI.showToast("An error occurred", {type: "error", timeout: 5000});

content · string · required

The string to show in the toast.

options · object

Options for the toast.

Show properties

type · string · default: ""

Changes the type of the toast stylistically and semantically. Choices: "", “info”, “success”, “danger”/“error”, “warning”/“warn”.

icon · boolean · default: "true"

Determines whether the icon should show corresponding to the type. A toast without type will always have no icon.

timeout · number · default: "3000"

Adjusts the time (in ms) the toast should be shown for before disappearing automatically.

forceShow · boolean · default: "false"

Whether to force showing the toast and ignore the BetterDiscord setting.

showNotice

Shows a notice above Discord’s chat layer.

const close = BdApi.UI.showNotice("Update available!", {
    type: "info",
    buttons: [
        {
            label: "Update Now",
            onClick: () => {
                console.log("Updating...");
                close();
            }
        },
        {
            label: "Dismiss",
            onClick: () => close()
        }
    ]
});

content · string | Node · required

Content of the notice.

options · object

Options for the notice.

Show properties

type · string · default: "info"

Type for the notice. Will affect the color. Choices: “info”, “error”, “warning”, “success”.

buttons · Array<{label: string, onClick: function}>

Buttons that should be added next to the notice text.

timeout · number · default: "10000"

Timeout until the notice is closed in milliseconds. Will not fire when set to 0.

Returns: function - A callback for closing the notice. Passing true as first parameter closes immediately without transitioning out

showNotification

Shows a system notification (if enabled in BetterDiscord settings).

BdApi.UI.showNotification({
    title: "New Message",
    content: "You have a new message from John",
    type: "info",
    icon: "https://example.com/icon.png",
    duration: 5000,
    actions: [
        {
            text: "View",
            callback: () => console.log("Viewing message")
        }
    ]
});

notificationObj · object · required

Notification configuration object.

Show properties

title · string · default: ""

Title of the notification.

content · string · default: ""

Content/body of the notification.

type · string · default: "info"

Type of notification. Choices: “info”, “success”, “warning”, “error”.

duration · number · default: "5000"

How long the notification should show in milliseconds.

icon · string

URL to an icon to show in the notification.

actions · Array<{text: string, callback: function}>

Action buttons to show in the notification.

createTooltip

Creates a tooltip to automatically show on hover.

const button = document.querySelector(".my-button");
const tooltip = BdApi.UI.createTooltip(button, "Click me!", {
    side: "top",
    style: "primary"
});

node · HTMLElement · required

DOM node to monitor and show the tooltip on.

content · string | HTMLElement · required

String or HTML element to show in the tooltip.

options · object

Additional options for the tooltip.

Show properties

style · string · default: "primary"

Correlates to the Discord styling/colors. Choices: “primary”, “info”, “success”, “warn”, “danger”.

side · string · default: "top"

Which side of the element to show the tooltip. Choices: “top”, “right”, “bottom”, “left”.

preventFlip · boolean · default: "false"

Prevents moving the tooltip to the opposite side if it is too big or goes offscreen.

disabled · boolean · default: "false"

Whether the tooltip should be disabled from showing on hover.

Returns: Tooltip - The tooltip that was generated

openDialog

Gives access to the Electron Dialog API. Returns a Promise that resolves to an object with the result.

// Open file dialog
const result = await BdApi.UI.openDialog({
    mode: "open",
    openFile: true,
    filters: [{name: "Images", extensions: ["png", "jpg", "gif"]}]
});

if (!result.cancelled) {
    console.log("Selected files:", result.filePaths);
}

// Save file dialog
const saveResult = await BdApi.UI.openDialog({
    mode: "save",
    defaultPath: "~/my-file.txt"
});

if (!saveResult.cancelled) {
    console.log("Save to:", saveResult.filePath);
}

options · object · required

Options object to configure the dialog.

Show properties

mode · string · default: "open"

Determines whether the dialog should open or save files. Choices: “open”, “save”.

defaultPath · string · default: "~"

Path the dialog should show on launch.

filters · Array<{name: string, extensions: string[]}>

An array of file filters (e.g., [{name: "Images", extensions: ["png", "jpg"]}]).

title · string

Title for the titlebar.

message · string

Message for the dialog.

showOverwriteConfirmation · boolean · default: "false"

Whether the user should be prompted when overwriting a file.

showHiddenFiles · boolean · default: "false"

Whether hidden files should be shown in the dialog.

promptToCreate · boolean · default: "false"

Whether the user should be prompted to create non-existent folders.

openDirectory · boolean · default: "false"

Whether the user should be able to select a directory as a target.

openFile · boolean · default: "true"

Whether the user should be able to select a file as a target.

multiSelections · boolean · default: "false"

Whether the user should be able to select multiple targets.

modal · boolean · default: "false"

Whether the dialog should act as a modal to the main window.

Returns: Promise<object> - Promise that resolves to an object with:

• cancelled (boolean): Whether the dialog was cancelled
• filePath (string): Selected file path for save mode
• filePaths (Array<string>): Selected file paths for open mode

buildSettingItem

Creates a single setting wrapped in a setting item that has a name and note.

const setting = BdApi.UI.buildSettingItem({
    type: "switch",
    id: "enable-feature",
    name: "Enable Feature",
    note: "Turns the feature on or off",
    value: true,
    onChange: (value) => {
        console.log("Setting changed:", value);
    }
});

document.body.appendChild(setting);

setting · object · required

Setting configuration object.

Show properties

type · string · required

One of: “dropdown”, “number”, “switch”, “text”, “slider”, “radio”, “keybind”, “color”, “custom”.

id · string · required

Identifier to use for callbacks.

name · string · required

Visual name to display.

note · string · required

Visual description to display.

value · any · required

Current value of the setting.

onChange · function

Callback when the value changes (only argument is new value).

disabled · boolean · default: "false"

Whether this setting is disabled.

inline · boolean · default: "true"

Whether the input should render inline with the name (false by default for radio type).

children · ReactElement

Only used for “custom” type.

Returns: A SettingItem React element with an input as the child

buildSettingsPanel

Creates a settings panel (React element) based on JSON-like data.

const panel = BdApi.UI.buildSettingsPanel({
    settings: [
        {
            type: "category",
            id: "general",
            name: "General Settings",
            shown: true,
            settings: [
                {
                    type: "switch",
                    id: "enabled",
                    name: "Enable Plugin",
                    note: "Turns the plugin on or off",
                    value: true
                },
                {
                    type: "text",
                    id: "username",
                    name: "Username",
                    note: "Your username",
                    value: "John"
                }
            ]
        },
        {
            type: "slider",
            id: "volume",
            name: "Volume",
            note: "Adjust the volume",
            value: 50,
            min: 0,
            max: 100
        }
    ],
    onChange: (category, id, value) => {
        console.log(`Setting changed: ${category || 'root'}.${id} = ${value}`);
    }
});

props · object · required

Panel configuration object.

Show properties

settings · Array<object> · required

Array of settings to show. Each setting follows the same structure as buildSettingItem, with an additional “category” type that groups settings.

onChange · function · required

Function called on every change. Receives three arguments: category (null for root settings), id, and value.

onDrawerToggle · function

Optionally used to save drawer states. Receives categoryId and current shown state.

getDrawerState · function

Optionally used to recall drawer states. Receives categoryId and defaultShown state, should return the saved state.

Returns: React element usable for a settings panel

Examples

Complete settings panel

class MyPlugin {
    getSettingsPanel() {
        return BdApi.UI.buildSettingsPanel({
            settings: [
                {
                    type: "category",
                    id: "appearance",
                    name: "Appearance",
                    settings: [
                        {
                            type: "switch",
                            id: "darkMode",
                            name: "Dark Mode",
                            note: "Enable dark mode",
                            value: this.settings.darkMode
                        },
                        {
                            type: "color",
                            id: "accentColor",
                            name: "Accent Color",
                            note: "Choose your accent color",
                            value: this.settings.accentColor
                        }
                    ]
                }
            ],
            onChange: (category, id, value) => {
                this.settings[id] = value;
                this.saveSettings();
            }
        });
    }
}

User feedback with toasts

function saveSettings() {
    try {
        // Save settings...
        BdApi.UI.showToast("Settings saved!", {type: "success"});
    } catch (error) {
        BdApi.UI.showToast("Failed to save settings", {type: "error"});
    }
}

Confirmation before destructive action

function deleteAllData() {
    BdApi.UI.showConfirmationModal(
        "Delete All Data",
        "This will permanently delete all your data. This action cannot be undone.",
        {
            danger: true,
            confirmText: "Delete Everything",
            onConfirm: () => {
                // Perform deletion
                BdApi.UI.showToast("All data deleted", {type: "success"});
            }
        }
    );
}