useLumioEventListener

useLumioEventListener(type, handler) calls handler once for every event of one type, in the order the host forwards them. It receives the same payloads as useLumioEvent and needs the same manifest permissions.

import { useState } from "react";
import { Lumio, Text, useLumioEventListener } from "@zaflun/lumio-sdk";

function ChatList() {
  const [lines, setLines] = useState<string[]>([]);

  useLumioEventListener("chat:message", (msg) => {
    setLines((prev) => [...prev, `${msg.display_name ?? msg.username}: ${msg.message}`].slice(-50));
  });

  return (
    <div>
      {lines.map((line, i) => (
        <Text key={i} content={line} />
      ))}
    </div>
  );
}

Lumio.render(<ChatList />, { target: "layer" });

Needs chat:read.

Signature

function useLumioEventListener<K extends LumioEventType>(
  eventType: K,
  handler: (payload: LumioEventPayloadMap[K]) => void
): void;

The payload type follows the literal event name, exactly as in useLumioEvent.

When to use which

Hook	Gives you	Use it for
useLumioEvent(type)	The latest payload as state	Showing the current state: the last follower, the playing track
useLumioEventListener(type, handler)	A call per event	Lists and counts: chat, an event feed, a running total

useLumioEvent keeps only the latest payload. When several events arrive before React renders again, as in a busy chat, the earlier ones never reach your component. The listener calls handler for each of them.

Notes

• Update state with the functional form (setLines((prev) => …)): several events can arrive before the next render.
• handler may change between renders; the hook always calls the latest one and does not subscribe again.
• Events that arrived before the component subscribed, or while the surface was closed, are not replayed. In OBS the host replays only the current Spotify state once on mount, as a spotify:track with replay: true; skip it when you count tracks (see useLumioEvent).
• A test event arrives like a real one, with isTest: true in its payload; label it with isTestEvent(payload) (see Test events).
• Every chat message arrives twice, as chat:message and as its platform's chat type. Listen to one of them.
• Declare chat:read and/or events:read in your manifest's permissions (see Delivery).