Skip to content
On this page

useEventBus

Category
Last Changed
7 days ago

A basic event bus.

Demo

News channel:
Television:
--- no signal ---

Usage

import { useEventBus } from '@vueuse/core'

const bus = useEventBus<string>('news')

const listener = (event: string) => {
  console.log(`news: ${event}`)
}

// listen to an event
const unsubscribe = bus.on(listener)

// fire an event
bus.emit('The Tokyo Olympics has begun')

// unregister the listener
unsubscribe()
// or
bus.off(listener)

// clearing all listeners
bus.reset()
import { useEventBus } from '@vueuse/core'

const bus = useEventBus<string>('news')

const listener = (event: string) => {
  console.log(`news: ${event}`)
}

// listen to an event
const unsubscribe = bus.on(listener)

// fire an event
bus.emit('The Tokyo Olympics has begun')

// unregister the listener
unsubscribe()
// or
bus.off(listener)

// clearing all listeners
bus.reset()

Listeners registered inside of components setup will be unregistered automatically when the component gets unmounted.

TypeScript

Using EventBusKey is the key to bind the event type to the key, similar to Vue's InjectionKey util.

// fooKey.ts
import type { EventBusKey } from '@vueuse/core'

export const fooKey: EventBusKey<{ name: foo }> = Symbol()
// fooKey.ts
import type { EventBusKey } from '@vueuse/core'

export const fooKey: EventBusKey<{ name: foo }> = Symbol()
import { useEventBus } from '@vueuse/core'

import { fooKey } from './fooKey'

const bus = useEventBus(fooKey)

bus.on((e) => {
  // `e` will be `{ name: foo }`
})
import { useEventBus } from '@vueuse/core'

import { fooKey } from './fooKey'

const bus = useEventBus(fooKey)

bus.on((e) => {
  // `e` will be `{ name: foo }`
})

Type Declarations

Show Type Declarations
export declare type EventBusListener<T = unknown, P = any> = (
  event: T,
  payload?: P
) => void
export declare type EventBusEvents<T, P = any> = EventBusListener<T, P>[]
export interface EventBusKey<T> extends Symbol {}
export declare type EventBusIdentifier<T = unknown> =
  | EventBusKey<T>
  | string
  | number
export interface UseEventBusReturn<T, P> {
  /**
   * Subscribe to an event. When calling emit, the listeners will execute.
   * @param listener watch listener.
   * @returns a stop function to remove the current callback.
   */
  on: (listener: EventBusListener<T, P>) => Fn
  /**
   * Similar to `on`, but only fires once
   * @param listener watch listener.
   * @returns a stop function to remove the current callback.
   */
  once: (listener: EventBusListener<T, P>) => Fn
  /**
   * Emit an event, the corresponding event listeners will execute.
   * @param event data sent.
   */
  emit: (event?: T, payload?: P) => void
  /**
   * Remove the corresponding listener.
   * @param listener watch listener.
   */
  off: (listener: EventBusListener<T>) => void
  /**
   * Clear all events
   */
  reset: () => void
}
export declare function useEventBus<T = unknown, P = any>(
  key: EventBusIdentifier<T>
): UseEventBusReturn<T, P>
export declare type EventBusListener<T = unknown, P = any> = (
  event: T,
  payload?: P
) => void
export declare type EventBusEvents<T, P = any> = EventBusListener<T, P>[]
export interface EventBusKey<T> extends Symbol {}
export declare type EventBusIdentifier<T = unknown> =
  | EventBusKey<T>
  | string
  | number
export interface UseEventBusReturn<T, P> {
  /**
   * Subscribe to an event. When calling emit, the listeners will execute.
   * @param listener watch listener.
   * @returns a stop function to remove the current callback.
   */
  on: (listener: EventBusListener<T, P>) => Fn
  /**
   * Similar to `on`, but only fires once
   * @param listener watch listener.
   * @returns a stop function to remove the current callback.
   */
  once: (listener: EventBusListener<T, P>) => Fn
  /**
   * Emit an event, the corresponding event listeners will execute.
   * @param event data sent.
   */
  emit: (event?: T, payload?: P) => void
  /**
   * Remove the corresponding listener.
   * @param listener watch listener.
   */
  off: (listener: EventBusListener<T>) => void
  /**
   * Clear all events
   */
  reset: () => void
}
export declare function useEventBus<T = unknown, P = any>(
  key: EventBusIdentifier<T>
): UseEventBusReturn<T, P>

Source

SourceDemoDocs

Contributors

Anthony Fu
TuiMao233
webfansplz
Jairo Blatt

Changelog

v7.7.0 on 2/26/2022
e4ceb - feat: payload support (#1279)
v6.3.2 on 9/8/2021
4fbe8 - fix: update linter rule, close #729
v6.1.0 on 9/2/2021
a39ec - feat: new Function once (#680)
v6.0.0-beta.2 on 8/9/2021
9dfd2 - feat: new function (#647)
useEventBus has loaded