Skip to main content

useEvent

Subscribe to an addon signal or a Minecraft event for the lifetime of a component.

Import​

import { useEvent } from '@bedrock-core/ui';

Signature​

function useEvent<T, O = never>(
signal: Signal<T> | NativeSignal<T, O>,
callback: (event: T) => void,
options?: O,
deps?: readonly unknown[]
): void

Parameters​

ParameterTypeDescription
signalSignal<T> | NativeSignal<T, O>A signal that returns a cleanup function, or a native source such as world.afterEvents.playerJoin
callback(event: T) => voidRuns when the source delivers an event
optionsOOptional filters for a direct native subscription
depsreadonly unknown[]Additional values that trigger resubscription

See toSignal for the two subscription contracts and how to convert a native source for reuse or export.

Returns​

void

Usage​

import { world } from '@minecraft/server';
import { Panel, Text, useEvent, useState } from '@bedrock-core/ui';

function EventListener() {
const [lastEvent, setLastEvent] = useState('None');

useEvent(
world.afterEvents.playerJoin,
(event) => {
setLastEvent(event.playerName);
}
);

return (
<Panel padding={10}>
<Text>{`Last event: ${lastEvent}`}</Text>
</Panel>
);
}

Examples​

Subscribe to an adapted signal​

import { toSignal } from '@bedrock-core/observable';
import { Text, useEvent, useState } from '@bedrock-core/ui';
import { world } from '@minecraft/server';

const deaths = toSignal(world.afterEvents.entityDie);

function DeathCounter() {
const [count, setCount] = useState(0);

useEvent(deaths, () => setCount(value => value + 1));

return <Text>{`Deaths: ${count}`}</Text>;
}

Item use counter​

import { world } from '@minecraft/server';
import { Panel, Text, useEvent, useState } from '@bedrock-core/ui';

function ItemUseTracker() {
const [useCount, setUseCount] = useState(0);
const [lastItem, setLastItem] = useState('None');

useEvent(
world.afterEvents.itemUse,
(event) => {
setUseCount(prev => prev + 1);
setLastItem(event.itemStack.typeId);
}
);

return (
<Panel padding={10} gap={4}>
<Text>{`Item uses: ${useCount}`}</Text>
<Text>{`Last used: ${lastItem}`}</Text>
</Panel>
);
}

Multiple event listeners​

import { world } from '@minecraft/server';
import { Panel, Text, useEvent, useState } from '@bedrock-core/ui';

function MultiEventTracker() {
const [eventLog, setEventLog] = useState<string[]>([]);

useEvent(
world.afterEvents.playerJoin,
(event) => {
setEventLog(prev => [...prev, `${event.playerName} joined`].slice(-5));
}
);

useEvent(
world.afterEvents.playerLeave,
(event) => {
setEventLog(prev => [...prev, `${event.playerName} left`].slice(-5));
}
);

return (
<Panel padding={10} gap={4}>
<Text>{'§lEvent Log'}</Text>
{eventLog.map((log, index) => (
<Text key={index}>{log}</Text>
))}
</Panel>
);
}

Notes​

The hook subscribes after mount and releases the subscription before replacing it or on unmount. Changes to the source, callback, options, or any additional dependency replace the subscription. Keep the source outside the render when adapting a shared native event with toSignal.

An inline callback has a new identity on each render and replaces the subscription. The optional dependency array adds triggers to the tracked source, callback and options.

Avoid heavy operations in handlers​

// ✅ Good - update state, process elsewhere
useEvent(signal, (event) => {
setData(event.data);
});

// ❌ Bad - heavy computation in handler
useEvent(signal, (event) => {
const result = expensiveOperation(event.data);
setData(result);
});