set-up-modus-event-listeners

Set Up Modus Event Listeners

Properly set up and clean up event listeners for Modus web components following established patterns.

When to Use

Use this skill when:

• Adding event handling to any Modus wrapper component
• Components need to respond to web component events
• You need to sync React state with web component state
• Handling user interactions from Modus components

Pattern Overview

All Modus event listeners follow this pattern:

1. Use useRef to get component reference
2. Use useEffect to set up listeners
3. Check for component existence before adding listeners
4. Create typed handler functions for each event
5. Conditionally attach listeners based on prop existence
6. Return cleanup function to remove listeners

Reference Examples

• Simple events: src/components/ModusCheckbox.tsx:91-150
• Multiple events: src/components/ModusDropdownMenu.tsx:79-112
• Complex events: src/components/ModusNavbar.tsx (multiple event handlers)

Basic Template

import { useEffect, useRef } from "react";
import { ModusWcComponent } from "@trimble-oss/moduswebcomponents-react";

export default function ModusComponent({
  onEventName,
}: {
  onEventName?: (event: CustomEvent<EventDetailType>) => void;
}) {
  const componentRef = useRef<HTMLModusWcComponentElement>(null);

  useEffect(() => {
    const component = componentRef.current;
    if (!component) return;

    const handleEventName = (event: Event) => {
      onEventName?.(event as CustomEvent<EventDetailType>);
    };

    if (onEventName) {
      component.addEventListener("eventName", handleEventName);
    }

    return () => {
      if (onEventName) {
        component.removeEventListener("eventName", handleEventName);
      }
    };
  }, [onEventName]);

  return <ModusWcComponent ref={componentRef} />;
}

Multiple Event Handlers

export default function ModusComponent({
  onInputChange,
  onInputFocus,
  onInputBlur,
  onValueChange,
}: {
  onInputChange?: (event: CustomEvent<InputEvent>) => void;
  onInputFocus?: (event: CustomEvent<FocusEvent>) => void;
  onInputBlur?: (event: CustomEvent<FocusEvent>) => void;
  onValueChange?: (event: CustomEvent<boolean>) => void;
}) {
  const componentRef = useRef<HTMLModusWcComponentElement>(null);

  useEffect(() => {
    const component = componentRef.current;
    if (!component) return;

    const handleInputChange = (event: Event) => {
      onInputChange?.(event as CustomEvent<InputEvent>);
    };
    const handleInputFocus = (event: Event) => {
      onInputFocus?.(event as CustomEvent<FocusEvent>);
    };
    const handleInputBlur = (event: Event) => {
      onInputBlur?.(event as CustomEvent<FocusEvent>);
    };
    const handleValueChange = (event: Event) => {
      onValueChange?.(event as CustomEvent<boolean>);
    };

    if (onInputChange)
      component.addEventListener("inputChange", handleInputChange);
    if (onInputFocus)
      component.addEventListener("inputFocus", handleInputFocus);
    if (onInputBlur)
      component.addEventListener("inputBlur", handleInputBlur);
    if (onValueChange)
      component.addEventListener("inputChange", handleValueChange);

    return () => {
      if (onInputChange)
        component.removeEventListener("inputChange", handleInputChange);
      if (onInputFocus)
        component.removeEventListener("inputFocus", handleInputFocus);
      if (onInputBlur)
        component.removeEventListener("inputBlur", handleInputBlur);
      if (onValueChange)
        component.removeEventListener("inputChange", handleValueChange);
    };
  }, [onInputChange, onInputFocus, onInputBlur, onValueChange]);

  return <ModusWcComponent ref={componentRef} />;
}