Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

4.6 KiB

Raw Blame History

category
Network

useEventSource

An EventSource or Server-Sent-Events instance opens a persistent connection to an HTTP server, which sends events in text/event-stream format.

Usage

import { useEventSource } from '@vueuse/core';

const { status, data, error, close } = useEventSource('https://event-source-url');

See the Type Declarations for more options.

Named Events

You can define named events with the second parameter

import { useEventSource } from '@vueuse/core';
// ---cut---
const { event, data } = useEventSource('https://event-source-url', ['notice', 'update']);

immediate

Enable by default.

Establish the connection immediately when the composable is called.

autoConnect

Enable by default.

If url is provided as a ref, when the url changes, it will automatically reconnect to the new url.

Auto Reconnection on Errors

Reconnect on errors automatically (disabled by default).

import { useEventSource } from '@vueuse/core';
// ---cut---
const { status, data, close } = useEventSource('https://event-source-url', [], {
  autoReconnect: true,
});

Or with more controls over its behavior:

import { useEventSource } from '@vueuse/core';
// ---cut---
const { status, data, close } = useEventSource('https://event-source-url', [], {
  autoReconnect: {
    retries: 3,
    delay: 1000,
    onFailed() {
      alert('Failed to connect EventSource after 3 retries');
    },
  },
});

Data Serialization

Apply custom transformations to incoming data using a serialization function.

import { useEventSource } from '@vueuse/core';
// ---cut---
const { data } = useEventSource('https://event-source-url', [], {
  serializer: {
    read: (rawData) => JSON.parse(rawData),
  },
});

// If server sends: '{"name":"John","age":30}'
// data.value will be: { name: 'John', age: 30 }

Type Declarations

export type EventSourceStatus = 'CONNECTING' | 'OPEN' | 'CLOSED';
export interface UseEventSourceOptions<Data> extends EventSourceInit {
  /**
   * Enabled auto reconnect
   *
   * @default false
   */
  autoReconnect?:
    | boolean
    | {
        /**
         * Maximum retry times.
         *
         * Or you can pass a predicate function (which returns true if you want to retry).
         *
         * @default -1
         */
        retries?: number | (() => boolean);
        /**
         * Delay for reconnect, in milliseconds
         *
         * @default 1000
         */
        delay?: number;
        /**
         * On maximum retry times reached.
         */
        onFailed?: Fn;
      };
  /**
   * Immediately open the connection when calling this composable
   *
   * @default true
   */
  immediate?: boolean;
  /**
   * Automatically connect to the websocket when URL changes
   *
   * @default true
   */
  autoConnect?: boolean;
  /**
   * Custom data serialization
   */
  serializer?: {
    read: (v?: string) => Data;
  };
}
export interface UseEventSourceReturn<Events extends string[], Data = any> {
  /**
   * Reference to the latest data received via the EventSource,
   * can be watched to respond to incoming messages
   */
  data: ShallowRef<Data | null>;
  /**
   * The current state of the connection, can be only one of:
   * 'CONNECTING', 'OPEN' 'CLOSED'
   */
  status: ShallowRef<EventSourceStatus>;
  /**
   * The latest named event
   */
  event: ShallowRef<Events[number] | null>;
  /**
   * The current error
   */
  error: ShallowRef<Event | null>;
  /**
   * Closes the EventSource connection gracefully.
   */
  close: EventSource['close'];
  /**
   * Reopen the EventSource connection.
   * If there the current one is active, will close it before opening a new one.
   */
  open: Fn;
  /**
   * Reference to the current EventSource instance.
   */
  eventSource: Ref<EventSource | null>;
  /**
   * The last event ID string, for server-sent events.
   * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
   */
  lastEventId: ShallowRef<string | null>;
}
/**
 * Reactive wrapper for EventSource.
 *
 * @see https://vueuse.org/useEventSource
 * @see https://developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource EventSource
 * @param url
 * @param events
 * @param options
 */
export declare function useEventSource<Events extends string[], Data = any>(
  url: MaybeRefOrGetter<string | URL | undefined>,
  events?: Events,
  options?: UseEventSourceOptions<Data>,
): UseEventSourceReturn<Events, Data>;

4.6 KiB Raw Blame History