Fixing Event Propagation Issues with shadcn Dialog Inside Next.js Links

Learn how to fix the frustrating issue of shadcn Dialog components triggering unwanted navigation when placed inside Next.js Link components, using a reusable PropagationStopper component.

Fixing Event Propagation Issues with shadcn/ui Dialog Inside Next.js Links

The Frustrating Case of Nested Clickable Components

When building modern web applications with Next.js and shadcn/ui, you'll likely encounter a common yet frustrating issue: event propagation conflicts between nested interactive components. This post explains how to solve a specific case where a shadcn Dialog component inside a Next.js Link causes unexpected navigation.

The Problem: Dialog Inside Link Triggers Navigation

Consider this common UI pattern: a card or list item that is entirely clickable (wrapped in a Link), but also contains a button that opens a dialog for additional actions. The expected behavior is:

1. Clicking the button opens the dialog
2. Clicking anywhere else on the card navigates to the linked page

However, in practice, clicking the button that opens the dialog also triggers the parent Link component's navigation, causing the user to be redirected before they can interact with the dialog.

This happens because the click event "bubbles up" from the dialog trigger to the parent Link component through a process called event propagation.

Understanding Event Propagation

In React and the DOM, events follow a propagation path:

1. Capture phase: Events travel from the root to the target element
2. Target phase: Event reaches the clicked element
3. Bubbling phase: Events bubble back up from the target to the root

Our issue occurs during the bubbling phase. When we click the Dialog trigger button:

1. The button's click handler executes, opening the dialog
2. The event bubbles up to the parent Link component
3. The Link component processes the same click event, triggering navigation

The Solution: A Propagation Stopper Component

To fix this issue, we need a component that definitively stops event propagation. Here's a simple yet effective solution:

"use client";

function preventDefaultPropagtion(
	e: React.MouseEvent<HTMLElement, MouseEvent>
) {
	e.nativeEvent.stopImmediatePropagation();
	e.nativeEvent.preventDefault();
	e.preventDefault();
	e.stopPropagation();
}

type PropagationStopperProps = React.HTMLAttributes<HTMLDivElement>;

export function PropagationStopper({
	children,
	onClick,
	...props
}: PropagationStopperProps) {
	return (
		<div
			{...props}
			onClick={(e) => {
				preventDefaultPropagtion(e);
				if (onClick) onClick(e);
			}}
		>
			{children}
		</div>
	);
}

This component takes a belt-and-suspenders approach to stopping event propagation:

1. e.nativeEvent.stopImmediatePropagation(): Prevents other listeners on the same element from firing
2. e.nativeEvent.preventDefault(): Prevents the default action of the native event
3. e.preventDefault(): Prevents the default action of the React synthetic event
4. e.stopPropagation(): Prevents bubbling/capturing for the React synthetic event

By using all four methods, we ensure maximum compatibility across different React versions and browser quirks.

How to Use the PropagationStopper

Simply wrap your Dialog component with the PropagationStopper:

<Link href="/item/123">
	<div className="card p-4">
		<h2>Item Title</h2>
		<p>Item description goes here...</p>

		<PropagationStopper>
			<Dialog>
				<DialogTrigger asChild>
					<Button variant="outline">Actions</Button>
				</DialogTrigger>
				<DialogContent>
					<DialogHeader>
						<DialogTitle>Item Actions</DialogTitle>
					</DialogHeader>
					<div className="flex gap-4">
						<Button variant="destructive">Delete</Button>
						<Button>Edit</Button>
					</div>
				</DialogContent>
			</Dialog>
		</PropagationStopper>
	</div>
</Link>

With this implementation, clicking the "Actions" button will open the dialog without triggering navigation, while clicking elsewhere on the card will still navigate as expected.

Why This Approach Works Better Than Alternatives

You might be tempted to simply add onClick={e => e.stopPropagation()} to your Dialog trigger, but this approach has several issues:

1. It doesn't stop all forms of propagation (missing stopImmediatePropagation)
2. It's easy to forget to add this to every instance
3. It doesn't handle complex nested interactive components consistently

The PropagationStopper component encapsulates this behavior in a reusable way and handles all edge cases.

Conclusion

Event propagation issues are a common source of bugs in React applications, especially when using UI component libraries like shadcn/ui with routing frameworks like Next.js. Understanding how events propagate and having a reliable solution like PropagationStopper in your toolkit helps create a more predictable user experience.

The next time you need to nest interactive components inside clickable containers, you'll be prepared to handle event propagation properly.

Happy coding!