useLumioEvent

Subscribe to a live stream event type. Returns the most recent event of that type, or null if no event has been received yet.

Signature

const event = useLumioEvent(eventType: LumioEventType);

Parameters

Parameter	Type	Required	Description
eventType	LumioEventType	Yes	The event type to subscribe to (e.g. "twitch:follower")

Return value

Type	Description
LumioEvent<T> | null	The most recent event of this type, or null before the first event

LumioEvent shape

interface LumioEvent<T = unknown> {
  type: string;           // e.g. "twitch:follower"
  timestamp: string;      // ISO 8601
  data: T;                // Event-specific payload
}

Supported event types

Twitch

Event type	Payload fields
"twitch:follower"	userName, userId, followedAt
"twitch:subscribe"	userName, userId, tier, months, message
"twitch:gift_sub"	gifterName, gifterUserId, recipientName, recipientUserId, tier
"twitch:resub"	userName, userId, tier, months, message
"twitch:cheer"	userName, userId, bits, message
"twitch:raid"	fromBroadcasterName, fromBroadcasterId, viewerCount
"twitch:reward"	userName, userId, rewardId, rewardTitle, rewardCost, input, status
"twitch:hype_train"	level, total, progress, goal
"twitch:hype_train_end"	level, total
"twitch:poll"	pollId, title, choices, status
"twitch:poll_end"	pollId, title, choices, winningChoiceId, status
"twitch:prediction"	predictionId, title, outcomes, status
"twitch:prediction_lock"	predictionId, title, outcomes
"twitch:prediction_end"	predictionId, title, outcomes, winningOutcomeId, status
"twitch:goal"	goalId, type, description, currentAmount, targetAmount
"twitch:goal_end"	goalId, type, description, currentAmount, targetAmount, isAchieved
"twitch:ad_break"	durationSeconds, startedAt
"twitch:ban"	userName, userId, reason, moderatorName
"twitch:unban"	userName, userId, moderatorName
"twitch:stream_online"	broadcasterName, broadcasterId, startedAt
"twitch:stream_offline"	broadcasterName, broadcasterId
"twitch:stream_update"	title, categoryName, categoryId

YouTube

Event type	Payload fields
"youtube:subscribe"	channelName, channelId
"youtube:member"	channelName, channelId, level
"youtube:superchat"	channelName, channelId, amount, currency, message
"youtube:supersticker"	channelName, channelId, amount, currency, stickerId
"youtube:gift_membership"	gifterName, gifterId, recipientCount, level
"youtube:gift_membership_received"	channelName, channelId, level
"youtube:poll"	question, choices, status

Kick

Event type	Payload fields
"kick:follower"	userName, userId, followedAt
"kick:subscribe"	userName, userId, months
"kick:gift"	gifterName, gifterId, recipientName, recipientUserId
"kick:stream_online"	broadcasterName, startedAt
"kick:stream_offline"	broadcasterName
"kick:chat"	userName, userId, message, emotes, badges, color

Trovo

Event type	Payload fields
"trovo:subscribe"	userName, userId, months
"trovo:spell"	userName, userId, spellName, valueMana, valueElixir
"trovo:chat"	userName, userId, message, emotes, badges

Spotify

Event type	Payload fields
"spotify:track"	title, artist, album, albumArtUrl, duration, progress, isPlaying
"spotify:play"	title, artist, progress
"spotify:pause"	title, artist, progress
"spotify:skip"	title, artist
"spotify:volume"	volume
"spotify:queue_add"	title, artist, addedBy
"spotify:device"	deviceName, deviceType
"spotify:playlist_add"	playlistId, playlistName, title, artist
"spotify:playlist_remove"	playlistId, playlistName, title, artist
"spotify:playlist_create"	playlistId, playlistName
"spotify:playlist_edit"	playlistId, playlistName
"spotify:playlist_delete"	playlistId, playlistName

StreamElements

Event type	Payload fields
"streamelements:tip"	userName, amount, currency, message

Chat — per-platform

Event type	Platform	Payload fields
"twitch:chat"	Twitch	userName, userId, message, emotes, badges, color
"youtube:chat"	YouTube	userName, userId, message, emotes, badges
"kick:chat"	Kick	userName, userId, message, emotes, badges, color
"trovo:chat"	Trovo	userName, userId, message, emotes, badges

Chat — catch-all

Event type	Payload fields
"chat:message"	platform, userName, userId, message, emotes, badges, color

Fires for all connected platforms. Use this instead of per-platform chat events when platform-agnostic handling is preferred.

Example: Follower alert

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

function FollowerAlert() {
  const event = useLumioEvent("twitch:follower");
  const [isVisible, setIsVisible] = useState(false);
  const [name, setName] = useState("");

  useEffect(() => {
    if (event) {
      setName(event.data.userName);
      setIsVisible(true);
      const timer = setTimeout(() => setIsVisible(false), 5000);
      return () => clearTimeout(timer);
    }
  }, [event]);

  if (!isVisible) return null;

  return (
    <Box
      style={{
        position: "absolute",
        bottom: 80,
        left: "50%",
        transform: "translateX(-50%)",
        background: "rgba(99, 102, 241, 0.9)",
        borderRadius: 12,
        padding: "16px 24px",
      }}
    >
      <Text content={`New follower: ${name}!`} variant="heading" />
    </Box>
  );
}

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

Example: Now playing (Spotify)

import { Box, Text, Image, useLumioEvent } from "@zaflun/lumio-sdk";

function NowPlaying() {
  const event = useLumioEvent("spotify:track");

  if (!event) return null;

  const track = event.data;

  return (
    <Box style={{ display: "flex", gap: 12, alignItems: "center" }}>
      <Image src={track.albumArtUrl} alt="Album art" style={{ width: 48, height: 48, borderRadius: 4 }} />
      <Box>
        <Text content={track.title} variant="default" />
        <Text content={track.artist} variant="muted" />
      </Box>
    </Box>
  );
}

Notes

• useLumioEvent() returns the latest event each time a new one arrives — the reference changes on every new event
• Use useEffect with the event as a dependency to trigger side effects when a new event arrives
• The extension must have the appropriate permission to receive events (e.g., events:read for platform events)
• Events are only delivered when the overlay is open — missed events while offline are not replayed