@four-leaf-studios/twitch-overlay

React component library for listening to Twitch EventSub events and rendering browser source overlays (e.g. in OBS).

Install

npm install @four-leaf-studios/twitch-overlay

Peer dependencies: react and react-dom (v18 or v19).

Quick Start

import {
  TwitchProvider,
  TwitchOverlay,
  useTwitchEvent,
  useTwitchConnection,
} from "@four-leaf-studios/twitch-overlay";

function Alerts() {
  useTwitchEvent("channel.subscribe", (event) => {
    console.log("New sub!", event);
  });

  const { status } = useTwitchConnection();

  return <div>Status: {status}</div>;
}

function App() {
  return (
    <TwitchProvider>
      <TwitchOverlay>
        <Alerts />
      </TwitchOverlay>
    </TwitchProvider>
  );
}

API

<TwitchProvider>

Wraps your app and connects to the Twitch EventSub WebSocket.

| Prop | Type | Default | Description | | ----- | -------- | --------------------------------- | ---------------------- | | url | string | wss://eventsub.wss.twitch.tv/ws | EventSub WebSocket URL |

<TwitchOverlay>

Transparent container sized for use as a browser source overlay.

| Prop | Type | Default | Description | | -------- | -------- | ------- | ------------------------ | | width | number | 1920 | Overlay width in pixels | | height | number | 1080 | Overlay height in pixels |

useTwitch()

Returns the TwitchContext value — connection state and a subscribe function for raw event handling.

useTwitchEvent(eventType, callback)

Subscribe to a specific Twitch event type. The callback fires whenever an event of that type arrives.

useTwitchEvent("channel.follow", (event) => {
  // event is Record<string, unknown>
});

useTwitchConnection()

Returns the current connection state:

{
  status: "disconnected" | "connecting" | "connected";
  sessionId: string | null;
}

Development

npm run build    # Build with Rollup