How to correctly type a custom element event bubbling on the imported component?

[haleksandre]

I tried a few things but each doesn't seem to type correctly.

// Melt types
export type EventHandler<T extends Event = Event> = (event: T) => void;
export type MeltEvent<E extends Event> = CustomEvent<{
    originalEvent: E;
}>;
export type MeltEventHandler<E extends Event> = EventHandler<Expand<Omit<MeltEvent<E>, 'initCustomEvent'>>>;

// Svelte DOM enhancement
declare module "svelte/elements" {
	// works for the button element
	export interface DOMAttributes {
		"on:m-click"?: MeltEventHandler<MouseEvent> | undefined | null;
	}

	// this work for the button element as well
	export interface HTMLButtonAttributes {
		"on:m-click": MeltEventHandler<MouseEvent> | undefined | null;
	}
}

// button.svelte
// this will correctly be typed as defined above
...
<button on:m-click on:m-click={(e) => void}>button</button>
...

// app.svelte
// On the component the type will be every possible Event (m-click: Event | MouseEvent | UIEvent | ClipboardEvent | CompositionEvent | FocusEvent | InputEvent | ... 11 more ... | SecurityPolicyViolationEvent)
)
...
<Button on:m-click={(e) => void}>

// Even if I declare the handler within the `script` tag with the `ComponentEvents` type it still defaults to a generic handler.
<script lang="ts">
// ...
const handler = async (e: ComponentEvents<Button>["m-click"]) => void);
// ...
</script>

I'm guessing that Svelte is defaulting the type of any on:${string} as a generic event handler. Is there a way to narrow the type such as when I use on:m-click on the Button component, it correctly assesses the type as it is in the declare module?

[harshagarwalnyu]

There are two distinct problems here — typing a custom event on an HTML element vs. typing it on a Svelte component. They need different module augmentations.

---

For HTML elements (e.g., <button on:m-click={handler}>):

// app.d.ts or a .d.ts file included in tsconfig
declare module "svelte/elements" {
  interface DOMAttributes<T extends EventTarget> {
    "on:m-click"?: MeltEventHandler<MouseEvent> | undefined | null;
  }
}
export {};

Note: DOMAttributes is generic in newer Svelte versions — add the type parameter.

---

For Svelte components (e.g., <MyButton on:m-click={handler}>):

Svelte components expose events through createEventDispatcher or $events in Svelte 5. For a component that forwards a custom element event, you need to declare it in the component's event map:

// In the component's script block or a companion .d.ts
import type { SvelteHTMLElements } from 'svelte/elements';

// For Svelte 5 runes mode — events are just props:
interface Props {
  'on:m-click'?: MeltEventHandler<MouseEvent>;
}

---

Root cause of the mismatch: DOMAttributes augmentation applies to all HTML element templates but Svelte components use a separate type path through ComponentEvents<T> and SvelteHTMLElements. Augmenting DOMAttributes alone doesn't make the event visible on a Svelte component wrapper.

Recommended pattern for Melt UI components specifically: define an Events type in the component and use ComponentEvents — Melt's own typing approach. The MeltEventHandler utility type is already the right shape; the gap is attaching it to both surfaces.

[gitsult4n]

forwarded element events never go through svelte/elements

for <button on:m-click> svelte2tsx puts __sveltets_2_mapElementEvent('m-click') into the component event map
packages/svelte2tsx/src/svelte2tsx/nodes/event-handler.ts:66
and that shim is <K extends keyof HTMLElementEventMap>(event: K): HTMLElementEventMap[K]
packages/svelte2tsx/svelte-shims-v4.d.ts:108

m-click is not a key of HTMLElementEventMap so K cannot infer a literal and falls back to its constraint
the entry becomes HTMLElementEventMap[keyof HTMLElementEventMap] which is exactly the union you are seeing

so augment that map too

export {};

declare global {
  interface HTMLElementEventMap {
    'm-click': MeltEvent<MouseEvent>;
  }
}

declare module 'svelte/elements' {
  interface DOMAttributes<T extends EventTarget> {
    'on:m-click'?: MeltEventHandler<MouseEvent> | undefined | null;
  }
}

you need both
the HTMLElementEventMap one is what makes ComponentEvents<Button>['m-click'] resolve to MeltEvent<MouseEvent>
the svelte/elements one is what makes on:m-click legal on the <button> at all — drop it and you get '"on:m-click"' does not exist in type 'HTMLProps<"button", HTMLAttributes<any>>' even for bare forwarding with no handler attached

if you would rather not add a global event
declare it inside the component instead

interface $$Events {
  'm-click': MeltEvent<MouseEvent>;
}

that fixes the component side with no global augmentation but $$Events replaces the whole map
add on:click forwarding after it and you get Argument of type '"click"' is not assignable to parameter of type '"m-click"' so every forwarded event has to be listed
the svelte/elements augmentation is still needed either way

checked with svelte 4.2.12 and svelte-check 3.6.6 and typescript 5.4.2
the tradeoff of the global one is that addEventListener('m-click') gets typed everywhere