Patching Components

Why patch?

To change Discord’s UI, you patch the component that renders it: intercept the component as it renders and adjust the output. Use this to add a button to a menu, hide an element, or wrap a screen in your own. Discord’s UI is made of React components your plugin doesn’t own, so most visual plugins work this way. Patches are applied with a patcher. A patcher wraps a target’s method, including a component’s render, with your own code, and can revert all of its patches in one call. If you haven’t used it before, read Patcher first. This page applies the same patcher to React components.

Everything your plugin shows on screen gets there by patching a component Discord already renders. You return modified elements from inside Discord’s own render, so your UI is part of Discord’s real tree and can access its context.

The three patch types

A patch hooks a function at one of three points.

After
Before
Instead

Runs after the original and receives its result. Return a new value to replace the original’s output. This is the usual choice for editing what a component renders.

Patcher.after(Component, 'type', ({ result }) => {
	// inspect or replace result
	return result;
});

Runs before the original and receives its args. Mutate the arguments or block the call. Use it to change inputs.

Patcher.before(Component, 'type', ({ args }) => {
	// adjust args in place
});

Replaces the original. You get args, original, and this. Call original yourself if and when you want the default behavior.

Patcher.instead(target, 'method', ({ args, original, this: self }) => {
	return original.apply(self, args);
});

Patching a component’s render

A React component renders through its type (or render) function. To patch it:

Find the module that owns the component.
Patch its type or render function with after.
Return your modified tree from the callback.

import { metro, patcher } from '@unbound-app/api';

const Patcher = patcher.createPatcher('my-plugin');

export default {
	start() {
		const Components = metro.findByProps('ToastContainer');

		Patcher.after(Components.ToastContainer, 'type', ({ result }) => {
			// wrap, replace, or return the original render
			return result;
		});
	},
	stop() {
		Patcher.unpatchAll();
	},
};

findByProps and the other findBy* helpers cache their results, so a repeat lookup of the same component is cheap. Searches with a manual filter function stay slow, because they can’t be cached by default. If you need one, wrap it with createCacheable so its result is remembered after the first cold start.

Component kinds

Each kind of component keeps its render function in a different place, so where you patch depends on the kind.

Memo
Class
Function

A React.memo component wraps the real component and stores it on .type. Patch .type, not the memo wrapper.

const Component = metro.findByProps('SomeMemoComponent').SomeMemoComponent;

// The inner component lives on .type for a memo.
Patcher.after(Component, 'type', ({ result }) => {
	return result;
});

A class component renders through render on its prototype. Patch prototype.render. The component instance is available as this, so you can read its props and state.

const Component = metro.findByName('SomeClassComponent');

Patcher.after(Component.prototype, 'render', ({ this: self, result }) => {
	// self.props and self.state are available here
	return result;
});

A plain function component has no stable handle you can patch directly. It has no prototype, often has no useful name or displayName, and mobile has no source-string search to locate it. Reach it through the parent module that renders it:

Patch the parent’s render.
Find the child in the parent’s output.
Patch the child from there.

See Reaching into a render.

Patch a memo on .type, not on the memo object. Patching the wrapper has no effect, because React calls the inner component on .type. The wrapper has no render of its own.

Reaching into a render

To patch a component that Metro search can’t find, patch a component you can find, then walk its result to reach the child. Many components are like this: they are defined inside another component’s module and only exist as elements in its rendered output. A render result is a tree of React elements. On each element:

type holds the component.
props holds its props.
props.children holds its rendered children.

Walk that tree to find the element you want.

function findInTree(node, predicate) {
	if (!node || typeof node !== 'object') return null;
	if (predicate(node)) return node;

	const children = node.props?.children ?? node.children;
	if (Array.isArray(children)) {
		for (const child of children) {
			const found = findInTree(child, predicate);
			if (found) return found;
		}
	} else if (children) {
		return findInTree(children, predicate);
	}

	return null;
}

Patcher.after(Parent, 'type', ({ result }) => {
	const row = findInTree(result, (n) => n?.type?.name === 'Row');
	if (row) {
		// edit the child element's props, or wrap it
		row.props.style = [row.props.style, { opacity: 0.5 }];
	}

	return result;
});

Other plugins may patch the same component, so write tree patches that work alongside them:

Guard every tree lookup with optional chaining and a null check. findInTree returns null when Discord’s structure changes, and another plugin may have already changed the tree you’re walking.
Add to children instead of replacing it. To insert an element, push onto the existing children array (or make children an array if it isn’t one). Overwriting it would remove an earlier plugin’s additions.

Temporary patches from a parent

To patch a child component’s own render when Metro can’t find a stable reference to it, patch the stable parent. Inside that patch, apply a one-time patch to the child that only lasts for that render. This is needed when the child is created fresh on each parent render. A patch left on it would target a reference that no longer exists on the next render. Every patch call returns an unpatch function, and the patcher (built on possess) accepts a { once: true } option that reverts the patch automatically after it fires once.

Patcher.after(Parent, 'type', ({ result }) => {
	const child = findInTree(result, (n) => n?.type?.name === 'Child');
	if (!child) return result;

	// Patch the child's render for this one render, then auto-revert.
	Patcher.after(child.type, 'type', ({ result: childResult }) => {
		// modify the child's output
		return childResult;
	}, { once: true });

	return result;
});

{ once: true } is what makes this safe. The child reference is new on every parent render, so the patch must not outlive the render that created it. For finer control, keep the unpatch function the patch call returns and call it yourself.

const unpatch = Patcher.after(child.type, 'type', cb);
// ...later:
unpatch();

Cleaning up

Cleaning up takes two steps:

Call unpatchAll in stop. The component goes back to Discord’s original render, with no leftover wrappers and no double-patching when the plugin is re-enabled.
Force the affected components to re-render.

The second step is needed because unpatching only restores the original function. Components that already rendered with your patch keep showing the patched output until React renders them again, so a mounted screen won’t update on its own. Forcing a re-render brings back the original UI without the user having to navigate away and back. How you force the re-render depends on the kind of component you patched.

Class
Function

A class component instance has a built-in forceUpdate method. If your patch captured the instance through this, call self.forceUpdate() to re-render it.

Patcher.after(Component.prototype, 'render', ({ this: self, result }) => {
	instance = self; // keep a reference to the mounted instance
	return result;
});

// in stop(), after unpatchAll():
instance?.forceUpdate();

A function component has no forceUpdate. If your patch added or removed an element that holds hooks, you also can’t simply re-run its render. The number of hook calls would differ between renders, and React throws a “rendered more/fewer hooks than expected” error.Instead:

In your patch, add a useEffect that listens for your plugin stopping.
When it fires, change the key of the element you return.

A new key makes React unmount the old element and mount a fresh one, which avoids the hook-count mismatch.

Patcher.after(Component, 'type', ({ result }) => {
	const [version, setVersion] = React.useState(0);

	React.useEffect(() => {
		// emitter is your plugin's own event source.
		const onStop = () => setVersion((v) => v + 1);
		emitter.on('stop', onStop);
		return () => emitter.off('stop', onStop);
	}, []);

	// Changing the key remounts the subtree instead of re-rendering it.
	return <Wrapper key={version}>{result}</Wrapper>;
});

A render patch that survives a disable leaves modified UI on screen with no running plugin behind it. You must call unpatchAll in stop and then force a re-render. Until something re-renders, the patched output stays on screen even though the patch is gone.

Patch the smallest target that does the job. Wrapping a deep, frequently rendered component runs your code on every render. Find the specific element you need and patch it there.

Addons

Plugins

Themes

Icon Packs

Development

API Reference

Loader

Patching Components

Why patch?

The three patch types

Patching a component’s render

Component kinds

Reaching into a render

Temporary patches from a parent

Cleaning up

​Why patch?

​The three patch types

​Patching a component’s render

​Component kinds

​Reaching into a render

​Temporary patches from a parent

​Cleaning up

Why patch?

The three patch types

Patching a component’s render

Component kinds

Reaching into a render

Temporary patches from a parent

Cleaning up