Events

Convention

Naming

All RenDS custom events follow the prefix ren-. Most are namespaced by component (ren-tab-change, ren-slide-change, ren-files-added); a handful of generic names are reused across components. Their exact flags and payload remain component-specific, so use the catalog below as the contract:

• ren-open / ren-close — fired by several overlay-style components. Some close events include { returnValue }.
• ren-change — fired when a control's value changes. Its payload reflects that control's value model.

If you need to disambiguate between e.g. a Dialog opening and a Combobox opening on the same page, scope your listener to the host element rather than to document.

Defaults

Bubbles, composed, cancelable

• bubbles: true on virtually every event. RenDS components live in light DOM, so events bubble naturally — listen anywhere up the tree.
• composed varies by component. RenDS uses light DOM, so this flag mainly records whether the event is intended to cross a future host boundary.
• cancelable: false by default. ren-submit is the documented exception; listeners may mark it prevented, while asynchronous work is coordinated through detail.waitUntil().

Reference

Event catalog

38 event names across 51 component-event contracts and 26 components. — means the field is not explicitly set (uses the CustomEvent default, which is false).

Patterns

How to listen

Targeted listening (preferred)

Listen on the specific component instance. Best for component-specific logic.

const combo = document.querySelector('ren-combobox[name="country"]');

combo.addEventListener('ren-change', (e) => {
  console.log(e.detail.value, e.detail.item);
});

Global delegation

Listen on document and filter by target. Best for cross-cutting concerns (analytics, undo stack, audit log).

document.addEventListener('ren-tab-change', (e) => {
  analytics.track('tab_changed', {
    component: e.target.id,
    tab: e.detail.tabId,
  });
});

Filtering by detail

table.addEventListener('ren-select', (e) => {
  if (e.detail.selected.length === 0) {
    bulkBar.hidden = true;
  } else {
    bulkBar.hidden = false;
    bulkBar.querySelector('.count').textContent = e.detail.selected.length;
  }
});

One-shot listening

Use the standard { once: true } option — RenDS events are plain CustomEvents.

dialog.addEventListener('ren-close', () => {
  cleanup();
}, { once: true });

Watch out

Common gotchas

• Don't preventDefault() to veto state changes. RenDS events fire after the change applies; cancellation is not wired. To veto, intercept the user action upstream (e.g., disable the trigger button until your check passes).
• Two components, same event. If a Combobox and a Select are on the same page, both dispatch ren-change with similar detail. Use e.target.tagName or scope your listener.
• Cross-component ren-open / ren-close. Dialog, Sheet, Combobox, Hover Card all fire these. Same trick: scope to host or check e.target.tagName.
• Form events fire on the <ren-form> host, not on <form>. Listen on the custom element, not the inner form element.