React EventSource

React hook for Server-Sent Events with custom headers support

A simple React hook for Server-Sent Events with the key feature that native EventSource lacks: custom headers support.

Perfect for authenticated Server-Sent Events, API keys, and any scenario where you need to send headers with your SSE connection.

Installation

npm install react-eventsource

Quick Start

import React from 'react'
import { useSSE } from 'react-eventsource'

function ServerUpdates() {
  const { readyState, close, reconnect } = useSSE({
    url: '/api/events',
    headers: {
      'Authorization': 'Bearer your-token',
      'X-API-Key': 'your-api-key'
    },
    onMessage: (message) => {
      console.log('Received:', message.data)
    },
    onError: (error) => {
      console.error('SSE Error:', error)
    }
  })

  const status = ['CONNECTING', 'OPEN', 'CLOSED'][readyState]

  return (
    <div>
      <p>Connection: {status}</p>
      <button onClick={close}>Close</button>
      <button onClick={reconnect}>Reconnect</button>
    </div>
  )
}

API Reference

useSSE(options)

Options

Property	Type	Required	Description
url	string	Yes	Server-Sent Events endpoint URL
headers	Record<string, string>	No	Custom headers (auth, API keys, etc.)
method	string	No	HTTP method (defaults to 'GET')
body	string | FormData	No	Request body (rarely needed for SSE)
onMessage	(message: EventSourceMessage) => void	No	Message event handler
onOpen	(response: Response) => void	No	Connection open handler
onError	(error: unknown) => void	No	Error handler
fetch	typeof window.fetch	No	Custom fetch implementation
openWhenHidden	boolean	No	Keep connection open when page is hidden (defaults to true)

Return Values

Property	Type	Description
readyState	number	Connection state: 0=CONNECTING, 1=OPEN, 2=CLOSED
close	() => void	Manually close the connection
reconnect	() => void	Close current connection and immediately reconnect

TypeScript Support

The hook is fully typed and exports the following types:

import { useSSE, type UseSSEOptions, type UseSSEResult } from 'react-eventsource'

// Type your own variables
const config: UseSSEOptions = {
  url: '/api/events',
  headers: { 'Authorization': 'Bearer token' }
}

// Extend the interface if needed
interface MySSEOptions extends UseSSEOptions {
  retryCount?: number
}

Examples

Authenticated Events

useSSE({
  url: '/api/user-notifications',
  headers: {
    'Authorization': `Bearer ${userToken}`
  },
  onMessage: (msg) => {
    const notification = JSON.parse(msg.data)
    showNotification(notification)
  }
})

POST with Body (Advanced)

useSSE({
  url: '/api/stream',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-User-ID': userId
  },
  body: JSON.stringify({ 
    channels: ['updates', 'alerts'] 
  }),
  onMessage: handleStreamMessage
})

Connection Management

function ChatStream() {
  const { readyState, close, reconnect } = useSSE({
    url: '/api/chat-stream',
    headers: { 'Authorization': `Bearer ${token}` },
    onMessage: (msg) => addMessage(JSON.parse(msg.data)),
    onError: (err) => console.error('Chat stream error:', err)
  })

  const isConnected = readyState === 1

  return (
    <div>
      <div className={`status ${isConnected ? 'connected' : 'disconnected'}`}>
        {isConnected ? '🟢 Connected' : '🔴 Disconnected'}
      </div>
      
      <button onClick={reconnect} disabled={readyState === 0}>
        Reconnect
      </button>
      
      <button onClick={close}>
        Disconnect
      </button>
    </div>
  )
}

Page Visibility Behavior

By default, this hook keeps SSE connections open even when the browser tab/window is hidden (minimized, switched away, etc.). This matches the behavior of the native EventSource API.

If you want to close the connection when the page is hidden and automatically reconnect when visible again (to reduce server load), set openWhenHidden to false:

useSSE({
  url: '/api/events',
  openWhenHidden: false,  // Close connection when page is hidden
  onMessage: (msg) => console.log(msg.data)
})

When to use openWhenHidden: false:

• You want to reduce server load by closing idle connections
• Your app doesn't need real-time updates when the user isn't viewing the page
• You're implementing a background sync that should pause when hidden

When to keep the default (true):

• You need continuous updates regardless of page visibility
• You're building a real-time monitoring dashboard
• Missing events while hidden would cause data inconsistency

Why This Hook?

• Native EventSource limitation: Cannot send custom headers
• This hook solves that: Built on @microsoft/fetch-event-source which supports headers
• React-friendly: Manages connection lifecycle with useEffect
• Simple API: Familiar EventSource-like interface
• TypeScript: Full type safety out of the box

License

MIT License. See LICENSE for details.