import { useRegisterEventListener } from '@uhg-abyss/parcels/hooks/useRegisterEventListener';

Overview

The useRegisterEventListener hook is used to register event listeners for custom events dispatched to the window, enabling communication between Parcels and the host site or between multiple Parcels. It is useful for listening to events dispatched by other components and is meant to be used in conjunction with the dispatchEvent tool.

Important

useRegisterEventListener is built using React and internally uses a useEffect hook that automatically provides a cleanup mechanism ensuring that the event listener is removed, preventing potential memory leaks. This differs from the registerEventListener tool, where this cleanup is not provided and will need to be added independently.

Non-React-based projects should use registerEventListener.

This hook is bidirectional, meaning that it can be used to register events in both web and parcel components.

Properties

useRegisterEventListener(
  eventName: string,
  handler: (event) => void,
):

Usage

useRegisterEventListener takes in two parameters:

1. eventName: a string representing the name of the custom event to listen for.
2. handler: a callback function that is executed when the event is dispatched.

() => {
  const [text, setText] = useState('Hello');

  useRegisterEventListener('webSubmit', (event) => {
    setText(event.detail.message);
  });

  return <div>{text}</div>;
};

Example

// Example web file
import React from 'react';
import { Button } from '@uhg-abyss/web/ui/Button';
import { dispatchEvent } from '@uhg-abyss/parcels/tools/dispatchEvent';

export const HelloAbyss = () => {
  // 1. Add a dispatch event to the web component
  const onSubmit = () => {
    // When the button is clicked, the event will be dispatched
    dispatchEvent('webSubmit', { message: 'Form submitted!' });
  };
  return (
    <div>
      <abyss-parcel import="parcel-app@test" />
      <Button onClick={onSubmit}>Hello</Button>
    </div>
  );
};

// Example parcel file
import React, { useCallback, useState } from 'react';
import { useRegisterEventListener } from '@uhg-abyss/parcels/hooks/useRegisterEventListener';

export const ParcelApp = () => {
  const [text, setText] = useState('Hello');

  // Memoize the handler function using useCallback
  // By using useCallback, you prevent useRegisterEventListener from unnecessarily
  // removing and re-adding the event listener whenever the component re-renders
  const handleWebSubmit = useCallback((event) => {
    setText(event.detail.message);
  }, []); // Dependencies array is empty since setText doesn't change

  // 2. Add a register event to the parcel component to listen for when the parcel component dispatches the event
  useRegisterEventListener('webSubmit', handleWebSubmit);

  return <div>{text}</div>;
};