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
| Parameter | Type | Description |
|---|---|---|
signal | Signal<T> | NativeSignal<T, O> | A signal that returns a cleanup function, or a native source such as world.afterEvents.playerJoin |
callback | (event: T) => void | Runs when the source delivers an event |
options | O | Optional filters for a direct native subscription |
deps | readonly 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);
});