Migrating to custom events

The callback props used by interactive components have been replaced by Stencil custom events in v3.2.0. Event names now follow the dhl* convention, such as clickEvent becoming dhlClick and changeEvent becoming dhlChange.

Breaking change

Callback props are not supported in v3.2.0 onwards. Replace them with custom event listeners when upgrading.

Migration checklist

1. Find callback props: Search for props such as clickEvent, changeEvent, or blurEvent in your application.
2. Find the replacement event: Open the component page from the Components overview and check its Events section.
3. Update the binding: Replace the callback prop with the event binding for your framework.
4. Update the handler: Receive a CustomEvent and read its payload from event.detail.
5. Update tests: Listen for or dispatch the replacement event instead of passing or invoking callback props directly.

What changes in an event handler

Callback props received their values as function arguments. Replacement events pass a CustomEvent to the handler. Read the emitted payload from event.detail.

For example, a value callback changes from this:

const changeEvent = (value) => console.log(value);

To this:

const onChange = (event) => console.log(event.detail.value);

Some events put a native event in detail, while others emit an object, number, string, or no detail. Do not assume every event has a value property or read the component value from event.target. Check the component's Events section for the exact payload type.

Event names by framework

The underlying event name is the same, but each framework uses its own binding syntax. For an event named dhlClick, use:

Framework	Event binding
Web Components	addEventListener("dhlClick", ...)
React	onDhlClick={...}
Angular	(dhlClick)="..."
Vue	@dhl-click="..."

Click event example

React

// Before
<DhlButton clickEvent={(event) => console.log(event)} label="Save" />

// After
<DhlButton onDhlClick={(event) => console.log(event.detail)} label="Save" />

Angular

<!-- Before -->
<dhl-button [clickEvent]="onClick" label="Save"></dhl-button>

<!-- After -->
<dhl-button (dhlClick)="onClick($event)" label="Save"></dhl-button>

Vue.js

<!-- Before -->
<dhl-button :clickEvent.prop="onClick" label="Save"></dhl-button>

<!-- After -->
<dhl-button @dhl-click="onClick" label="Save"></dhl-button>

Web Components

<!-- Before -->
<dhl-button id="save-button" label="Save"></dhl-button>

<script>
  document.querySelector("#save-button").clickEvent = (event) => {
      console.log(event);
  };
</script>

<!-- After -->
<dhl-button id="save-button" label="Save"></dhl-button>

<script>
  document.querySelector("#save-button").addEventListener("dhlClick", (event) => {
      console.log(event.detail);
  });
</script>

Value event example

React

// Before
<DhlSelect changeEvent={(value) => console.log(value)} />

// After
<DhlSelect onDhlChange={(event) => console.log(event.detail.value)} />

Angular

<!-- Before -->
<dhl-select [changeEvent]="onChange"></dhl-select>

<!-- After -->
<dhl-select (dhlChange)="onChange($event)"></dhl-select>

Vue.js

<!-- Before -->
<dhl-select :changeEvent.prop="onChange"></dhl-select>

<!-- After -->
<dhl-select @dhl-change="onChange"></dhl-select>

Web Components

<!-- Before -->
<dhl-select id="delivery-option"></dhl-select>
<script>
  document.querySelector("#delivery-option").changeEvent = (value) => {
      console.log(value);
  };
</script>

<!-- After -->
<dhl-select id="delivery-option"></dhl-select>

<script>
  document.querySelector("#delivery-option").addEventListener("dhlChange", (event) => {
      console.log(event.detail.value);
  });
</script>

Non-standard event mappings

Most callback props map directly to a dhl* event: remove the Event suffix and add the dhl prefix. For example, focusEvent becomes dhlFocus and keyDownEvent becomes dhlKeyDown.

The following mappings do not follow that convention:

Component	Callback prop → replacement event
dhl-counter	blurEvent → dhlCounterBlur buttonClickHandler → dhlCounterButtonClick changeEvent → dhlCounterChange
dhl-country-select	optionClickEvent → dhlClickOption
dhl-dropdown	filterChangeEvent → dhlFilter optionClickEvent → dhlClickOption
dhl-modal	handleOnClose → dhlModalHide handleOnShow → dhlModalShow
dhl-multi-select	optionClickEvent → dhlClickOption
dhl-navbar	handleSearchChange → dhlSearchChange
dhl-select	optionClickEvent → dhlClickOption
dhl-stage-tracking	handleSubmit → dhlSubmit

For all supported events and their exact event.detail types, use the Events section on the relevant component page.