Event Handling

Retend handles user interactions through event props.

Listening to Events

Pass a function to an event prop to register a listener. Use camelCase event names such as onClick, onInput, and onSubmit.

function LoggingButton() {
  const handleClick = () => {
    console.log('Button was clicked!');
  };

  return (
    <button type="button" onClick={handleClick}>
      Click Me
    </button>
  );
}

Working with the Event Object

The event handler receives the standard Event object, which contains information about the event, including its target and input details.

function SearchInput() {
  const handleInput = (event: Event) => {
    const target = event.target;
    if (target instanceof HTMLInputElement) {
      console.log('User typed:', target.value);
    }
  };

  return (
    <div>
      <label for="search">Search:</label>
      <input type="text" id="search" onInput={handleInput} />
    </div>
  );
}

Updating State from Events

To update the interface in response to an event, call .set() on the relevant Cell. Retend then updates the bound interface.

import { Cell } from 'retend';

function ToggleSwitch() {
  const isOn = Cell.source(false);

  const toggle = () => {
    isOn.set(!isOn.get());
  };

  return (
    <div>
      <p>Switch is: {isOn}</p>
      <button type="button" onClick={toggle}>
        Toggle
      </button>
    </div>
  );
}

Event Modifiers

Some event handlers need standard operations such as event.preventDefault(). For example, preventing the default action is commonly required when handling form submission.

Retend provides modifiers for these operations. Append modifiers to event names with double hyphens (--):

function Form() {
  const handleSubmit = () => {
    console.log('Form submitted!');
    // No need to call event.preventDefault() here!
  };

  return (
    <form onSubmit--prevent={handleSubmit}>
      <button type="submit">Submit</button>
    </form>
  );
}

Available Modifiers

• --prevent: Automatically calls event.preventDefault(). Very common for forms and links.
• --stop: Automatically calls event.stopPropagation(). Stops the event from triggering events on parent elements.
• --once: Ensures the event handler only runs a single time, then automatically removes it.
• --passive: Improves performance for scrolling events (like onScroll or onTouchMove). Cannot be used with --prevent.

Modifiers can be combined:

function EventShowcase() {
  const handleOnceClick = () => {
    console.log('Just once!');
  };

  return (
    <button type="button" onClick--stop--once={handleOnceClick}>
      One-Time Click
    </button>
  );
}