BdApi.DOM

Manipulate the DOM and inject styles

DOM is a simple utility class for DOM manipulation. It provides convenient methods for adding styles, creating elements, and observing DOM changes.

Properties

screenWidth · number

Current width of the user’s screen in pixels.

screenHeight · number

Current height of the user’s screen in pixels.

Methods

addStyle

Adds a <style> element to the document with the given ID.

Global API

BdApi.DOM.addStyle("my-styles", `
    .my-class {
        color: red;
        font-weight: bold;
    }
`);

id · string · required

ID to use for the style element. When using scoped API with a single parameter, the plugin name is used as the ID.

css · string · required

CSS to apply to the document.

removeStyle

Removes a <style> element from the document corresponding to the given ID.

Global API

BdApi.DOM.removeStyle("my-styles");

id · string · required

ID used for the style element. When using scoped API with no parameters, the plugin name is used.

onRemoved

Adds a listener for when the node is removed from the document body.

const element = document.querySelector(".my-element");
BdApi.DOM.onRemoved(element, () => {
    console.log("Element was removed!");
});

node · HTMLElement · required

Node to be observed for removal.

callback · function · required

Function to run when the node is removed from the DOM.

onAdded

Adds a listener for when a node matching a selector is added to the document body. The listener is automatically removed upon firing.

BdApi.DOM.onAdded(".chat-message", (element) => {
    console.log("New message element added!", element);
});

selector · string · required

CSS selector for the node to wait for.

callback · function · required

Function to be called when a matching element is added. The callback receives the matching element as an argument.

animate

Utility to help smoothly animate using JavaScript.

const element = document.querySelector(".my-element");

BdApi.DOM.animate((progress) => {
    // progress goes from 0 to 1
    element.style.opacity = progress;
}, 1000); // 1 second duration

update · function · required

Render function indicating the style should be updated. Receives a progress value from 0 to 1.

duration · number · required

Duration in milliseconds to animate for.

options · object

Options to customize the animation.

Show properties

timing · function

Optional function calculating progress based on current time fraction. Linear by default.

Example easing functions:

// Ease-in-out
const easeInOut = t => t < 0.5 ? 2*t*t : -1+(4-2*t)*t;

BdApi.DOM.animate(update, 1000, {timing: easeInOut});

createElement

Utility function to make creating DOM elements easier. Acts similarly to React.createElement.

const button = BdApi.DOM.createElement("button", {
    className: "my-button",
    id: "submit-btn",
    onclick: () => console.log("Clicked!")
}, "Click Me");

document.body.appendChild(button);

tag · string · required

HTML tag name to create (e.g., “div”, “button”, “span”).

options · object

Options object to customize the element.

Show properties

className · string

Class name to add to the element.

id · string

ID to set for the element.

target · HTMLElement

Target element to automatically append to.

Any other properties are set as attributes or event handlers on the element.

children · Node | string

Child nodes to add. Can be DOM nodes, strings, or arrays of either.

Returns: HTMLElement - The created HTML element

parseHTML

Parses a string of HTML and returns the results. If the second parameter is true, the parsed HTML will be returned as a document fragment.

// Parse and get elements
const elements = BdApi.DOM.parseHTML('<div class="container"><span>Hello</span></div>');

// Parse as fragment
const fragment = BdApi.DOM.parseHTML('<div>One</div><div>Two</div>', true);
document.body.appendChild(fragment);

html · string · required

HTML string to be parsed.

fragment · boolean · default: "false"

Whether or not the return should be the raw DocumentFragment. This is extremely useful if you have multiple top-level elements that you want to append all at once.

Returns: DocumentFragment | NodeList | HTMLElement - The result of HTML parsing

Examples

Adding plugin styles

class MyPlugin {
    constructor() {
        this.BdApi = new BdApi("MyPlugin");
    }

    start() {
        // Add custom styles for your plugin
        this.BdApi.DOM.addStyle(`
            .my-plugin-badge {
                background: #7289da;
                color: white;
                padding: 2px 6px;
                border-radius: 3px;
                font-size: 12px;
            }
        `);
    }

    stop() {
        // Clean up styles when plugin stops
        this.BdApi.DOM.removeStyle();
    }
}

Creating custom UI elements

const container = BdApi.DOM.createElement("div", {
    className: "my-container",
    style: "padding: 20px;"
});

const title = BdApi.DOM.createElement("h2", {}, "Settings");
const description = BdApi.DOM.createElement("p", {}, "Configure your plugin here.");

container.appendChild(title);
container.appendChild(description);

document.body.appendChild(container);

Observing DOM changes

// Wait for a specific element to be added
BdApi.DOM.onAdded(".user-profile", (profile) => {
    console.log("User profile opened:", profile);
    
    // Add custom content to the profile
    const badge = BdApi.DOM.createElement("div", {
        className: "custom-badge"
    }, "Premium User");
    
    profile.appendChild(badge);
    
    // Clean up when profile is closed
    BdApi.DOM.onRemoved(profile, () => {
        console.log("Profile closed");
    });
});

Smooth animations

const element = document.querySelector(".my-element");

// Fade in animation
BdApi.DOM.animate((progress) => {
    element.style.opacity = progress;
}, 500);

// Custom easing
const easeOutBounce = (t) => {
    const n1 = 7.5625;
    const d1 = 2.75;
    if (t < 1 / d1) {
        return n1 * t * t;
    } else if (t < 2 / d1) {
        return n1 * (t -= 1.5 / d1) * t + 0.75;
    } else if (t < 2.5 / d1) {
        return n1 * (t -= 2.25 / d1) * t + 0.9375;
    } else {
        return n1 * (t -= 2.625 / d1) * t + 0.984375;
    }
};

BdApi.DOM.animate((progress) => {
    element.style.transform = `translateY(${-100 + progress * 100}px)`;
}, 1000, {timing: easeOutBounce});

Getting screen dimensions

console.log(`Screen size: ${BdApi.DOM.screenWidth}x${BdApi.DOM.screenHeight}`);

// Create a fullscreen overlay
const overlay = BdApi.DOM.createElement("div", {
    style: `
        position: fixed;
        top: 0;
        left: 0;
        width: ${BdApi.DOM.screenWidth}px;
        height: ${BdApi.DOM.screenHeight}px;
        background: rgba(0, 0, 0, 0.8);
        z-index: 9999;
    `
});