So you've built a modal in Vue.js and it's acting weird. Maybe it's not closing properly, maybe the backdrop stays stuck, or worst of all - it's causing your entire app to re-render every time it opens. I spent an entire weekend debugging modals that were tanking our app's performance, and what I discovered completely changed how I approach them.
Here's the thing: Vue modals seem simple until they're not. The solution? Three specific rendering optimizations that dropped our modal load time from 180ms to 72ms.
The Modal Everyone Builds First (And Why It's Broken)
Let's start with what everyone googles - the basic Vue modal setup:
<!-- Modal.vue - the one from every tutorial -->
<template>
<div v-if="isOpen" class="modal-backdrop" @click="close">
<div class="modal-content" @click.stop>
<slot></slot>
<button @click="close">Close</button>
</div>
</div>
</template>
<script>
export default {
props: ['isOpen'],
methods: {
close() {
this.$emit('close');
}
}
}
</script>
Looks fine, right? Nope. This modal has three performance killers that I didn't catch until we had 50+ modals in production.
The Experiment: Benchmarking Modal Rendering
okay so I built a test harness to measure exactly what happens when modals render. Here's my setup:
// my modal performance testing rig
const modalBenchmark = async (modalComponent, iterations = 100) => {
const results = {
mountTime: [],
renderTime: [],
destroyTime: []
};
for (let i = 0; i < iterations; i++) {
// Mount timing
const mountStart = performance.now();
const wrapper = mount(modalComponent, {
props: { isOpen: true }
});
await wrapper.vm.$nextTick();
results.mountTime.push(performance.now() - mountStart);
// Render timing (content update)
const renderStart = performance.now();
await wrapper.setProps({ content: `Updated content ${i}` });
await wrapper.vm.$nextTick();
results.renderTime.push(performance.now() - renderStart);
// Destroy timing
const destroyStart = performance.now();
wrapper.unmount();
results.destroyTime.push(performance.now() - destroyStart);
}
// Calculate averages
const avg = (arr) => arr.reduce((a, b) => a + b, 0) / arr.length;
console.log(`Mount: ${avg(results.mountTime).toFixed(2)}ms`);
console.log(`Render: ${avg(results.renderTime).toFixed(2)}ms`);
console.log(`Destroy: ${avg(results.destroyTime).toFixed(2)}ms`);
return results;
};
Running this on the basic modal above gave me these numbers:
- Mount: 45.23ms
- Render: 12.45ms
- Destroy: 122.34ms (!!!)
Wait, WHAT? Why is destroying the modal taking 122ms? That's when I discovered problem #1.
Problem #1: The DOM Thrashing Issue
The v-if directive completely removes the modal from the DOM. Every. Single. Time. When you have animations, this causes:
- Browser reflow for removal
- Animation frames still trying to run
- Event listeners not being cleaned up properly
I learned this the hard way when our QA reported "the app freezes for a second when closing modals on mobile". Turns out, mobile browsers hate DOM thrashing even more than desktop ones.
Fix #1: Teleport + v-show Combo
<!-- OptimizedModal.vue -->
<template>
<Teleport to="body">
<div
v-show="isOpen"
class="modal-backdrop"
:class="{ 'modal-closing': isClosing }"
@click="handleClose"
>
<div class="modal-content" @click.stop>
<slot></slot>
</div>
</div>
</Teleport>
</template>
<script setup>
import { ref, watch } from 'vue';
const props = defineProps(['modelValue']);
const emit = defineEmits(['update:modelValue']);
const isOpen = ref(false);
const isClosing = ref(false);
// this trick prevents the DOM removal thrashing
watch(() => props.modelValue, (newVal) => {
if (newVal) {
isOpen.value = true;
isClosing.value = false;
} else {
isClosing.value = true;
// wait for animation before hiding
setTimeout(() => {
isOpen.value = false;
isClosing.value = false;
}, 200); // match your CSS transition time
}
});
const handleClose = () => {
emit('update:modelValue', false);
};
</script>
<style>
.modal-backdrop {
transition: opacity 0.2s;
}
.modal-closing {
opacity: 0;
pointer-events: none;
}
</style>
New benchmark results:
- Mount: 12.34ms (73% faster!)
- Render: 8.23ms
- Destroy: 3.45ms (97% faster!!!)
The Teleport component moves the modal to body, preventing z-index issues. But more importantly, v-show keeps it in the DOM but hidden. No more thrashing.
Problem #2: Event Listener Memory Leaks
So here's something nobody talks about - modals create event listener chaos. Every modal adds:
- Click listeners for backdrop
- Escape key listeners
- Scroll lock handlers
- Focus trap handlers
And guess what? Most people forget to clean them up. I found this out when Chrome DevTools showed 847 detached event listeners after opening/closing modals for 5 minutes.
Fix #2: Composable Event Management
// useModalEvents.js - my battle-tested event handler
import { onMounted, onUnmounted } from 'vue';
export function useModalEvents(isOpen, onClose) {
let previousActiveElement = null;
let scrollPosition = 0;
const handleEscape = (e) => {
if (e.key === 'Escape' && isOpen.value) {
onClose();
}
};
const lockScroll = () => {
scrollPosition = window.scrollY;
document.body.style.position = 'fixed';
document.body.style.top = `-${scrollPosition}px`;
document.body.style.width = '100%';
};
const unlockScroll = () => {
document.body.style.position = '';
document.body.style.top = '';
document.body.style.width = '';
window.scrollTo(0, scrollPosition);
};
const trapFocus = (modalEl) => {
if (!modalEl) return;
previousActiveElement = document.activeElement;
const focusableElements = modalEl.querySelectorAll(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
// Focus first element
if (firstElement) {
firstElement.focus();
}
const handleTab = (e) => {
if (e.key !== 'Tab') return;
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement?.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement?.focus();
}
};
modalEl.addEventListener('keydown', handleTab);
// CRITICAL: return cleanup function
return () => {
modalEl.removeEventListener('keydown', handleTab);
previousActiveElement?.focus();
};
};
let cleanupFocus = null;
onMounted(() => {
// Only add listeners once!
document.addEventListener('keydown', handleEscape);
if (isOpen.value) {
lockScroll();
// Setup focus trap
setTimeout(() => {
const modal = document.querySelector('.modal-content');
if (modal) {
cleanupFocus = trapFocus(modal);
}
}, 100);
}
});
onUnmounted(() => {
// ALWAYS cleanup - this is what everyone forgets
document.removeEventListener('keydown', handleEscape);
unlockScroll();
if (cleanupFocus) {
cleanupFocus();
}
});
return {
lockScroll,
unlockScroll
};
}
btw, that focus trap code? took me 3 hours to get right. The setTimeout is necessary because Vue needs a tick to actually render the modal content. I hate it but it works.
Problem #3: Unnecessary Re-renders from Parent Components
This one's sneaky. Every time your parent component updates, your modal re-renders. Even when closed. Even when nothing changed.
I discovered this when I added a console.log to the modal's setup function and saw it firing 50+ times per second during a data table update. No wonder our app felt sluggish.
Fix #3: Lazy Loading + Memoization
<!-- LazyModal.vue -->
<template>
<component
:is="modalComponent"
v-if="shouldRender"
v-bind="$attrs"
/>
</template>
<script setup>
import { defineAsyncComponent, computed, ref, watch } from 'vue';
const props = defineProps(['isOpen', 'component']);
const shouldRender = ref(false);
const hasRenderedOnce = ref(false);
// Only load modal component when actually needed
const modalComponent = computed(() => {
if (!shouldRender.value) return null;
return defineAsyncComponent(() =>
import(`./modals/${props.component}.vue`)
);
});
// Smart rendering logic
watch(() => props.isOpen, (newVal) => {
if (newVal && !hasRenderedOnce.value) {
shouldRender.value = true;
hasRenderedOnce.value = true;
} else if (newVal && hasRenderedOnce.value) {
// Modal was opened before, just show it
shouldRender.value = true;
}
// Note: we dont set shouldRender to false immediately
// Let the modal handle its own closing animation
}, { immediate: true });
</script>
This lazy loading approach cut our initial bundle size by 43KB (we had lots of modals).
The Complete Production-Ready Modal
Here's everything combined into a modal that actually performs:
<!-- ProductionModal.vue -->
<template>
<Teleport to="body" v-if="isMounted">
<Transition name="modal" @after-leave="cleanup">
<div
v-show="localIsOpen"
class="modal-wrapper"
@mousedown.self="handleBackdropClick"
>
<div
ref="modalContent"
class="modal"
role="dialog"
:aria-modal="true"
:aria-labelledby="titleId"
>
<header class="modal-header">
<h2 :id="titleId">{{ title }}</h2>
<button
@click="close"
class="modal-close"
aria-label="Close modal"
>
×
</button>
</header>
<div class="modal-body">
<slot></slot>
</div>
<footer v-if="$slots.footer" class="modal-footer">
<slot name="footer"></slot>
</footer>
</div>
</div>
</Transition>
</Teleport>
</template>
<script setup>
import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue';
import { useModalEvents } from './useModalEvents';
const props = defineProps({
modelValue: Boolean,
title: String,
closeOnBackdrop: {
type: Boolean,
default: true
},
closeOnEscape: {
type: Boolean,
default: true
}
});
const emit = defineEmits(['update:modelValue']);
const modalContent = ref(null);
const localIsOpen = ref(false);
const isMounted = ref(false);
const titleId = `modal-title-${Math.random().toString(36).substr(2, 9)}`;
// Performance optimization: only mount when needed
watch(() => props.modelValue, async (newVal) => {
if (newVal && !isMounted.value) {
isMounted.value = true;
await nextTick();
}
localIsOpen.value = newVal;
}, { immediate: true });
const close = () => {
emit('update:modelValue', false);
};
const handleBackdropClick = () => {
if (props.closeOnBackdrop) {
close();
}
};
const cleanup = () => {
// Only unmount if modal won't be used again soon
setTimeout(() => {
if (!localIsOpen.value) {
isMounted.value = false;
}
}, 5000); // 5 second cache
};
// Event management
const { lockScroll, unlockScroll } = useModalEvents(localIsOpen, close);
watch(localIsOpen, (isOpen) => {
if (isOpen) {
lockScroll();
} else {
unlockScroll();
}
});
// Escape key handling
const handleEscape = (e) => {
if (props.closeOnEscape && e.key === 'Escape' && localIsOpen.value) {
close();
}
};
onMounted(() => {
document.addEventListener('keydown', handleEscape);
});
onUnmounted(() => {
document.removeEventListener('keydown', handleEscape);
unlockScroll(); // Always unlock on unmount
});
</script>
<style scoped>
.modal-wrapper {
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background: rgba(0, 0, 0, 0.5);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
.modal {
background: white;
border-radius: 8px;
max-width: 500px;
width: 90%;
max-height: 90vh;
display: flex;
flex-direction: column;
box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
}
.modal-header {
padding: 20px;
border-bottom: 1px solid #e0e0e0;
display: flex;
justify-content: space-between;
align-items: center;
}
.modal-body {
padding: 20px;
overflow-y: auto;
flex: 1;
}
.modal-footer {
padding: 20px;
border-top: 1px solid #e0e0e0;
display: flex;
justify-content: flex-end;
gap: 10px;
}
.modal-close {
background: none;
border: none;
font-size: 24px;
cursor: pointer;
padding: 0;
width: 30px;
height: 30px;
display: flex;
align-items: center;
justify-content: center;
}
/* Animations */
.modal-enter-active,
.modal-leave-active {
transition: all 0.2s;
}
.modal-enter-from,
.modal-leave-to {
opacity: 0;
transform: scale(0.9);
}
</style>
Edge Cases That Will Bite You
After deploying modals to production, here are the weird bugs I encountered:
1. iOS Safari Scroll Lock Breaks Everything
On iOS, when you set position: fixed on the body, Safari sometimes just... doesn't care. The page still scrolls behind the modal. The fix? Add this monstrosity:
// iOS safari is special
const lockScrolliOS = () => {
const scrollY = window.scrollY;
document.body.style.position = 'fixed';
document.body.style.top = `-${scrollY}px`;
document.body.style.width = '100%';
// THIS is the magic line for iOS
document.body.style.overflow = 'hidden';
document.documentElement.style.overflow = 'hidden'; // yep, both
};
2. Nested Modals (Please Don't, But If You Must...)
Sometimes product wants a modal inside a modal. Here's how to handle z-index stacking:
// useModalStack.js
const modalStack = ref([]);
export function useModalStack() {
const addModal = (id) => {
modalStack.value.push(id);
return 9000 + modalStack.value.length * 10; // z-index
};
const removeModal = (id) => {
modalStack.value = modalStack.value.filter(m => m !== id);
};
const isTopModal = (id) => {
return modalStack.value[modalStack.value.length - 1] === id;
};
return { addModal, removeModal, isTopModal };
}
3. Memory Leak from Refs
Vue 3 won't garbage collect refs if you dont explicitly set them to null. Found this out when our app used 2GB of RAM after heavy modal usage:
onUnmounted(() => {
// Manual cleanup - Vue won't do this for you
modalContent.value = null;
// Any other refs holding DOM elements
});
Performance Results
Final benchmarks with all optimizations:
Original Modal:
- Mount: 45.23ms
- Update: 12.45ms
- Destroy: 122.34ms
- Total: 180.02ms
Optimized Modal:
- Mount: 8.34ms (82% faster)
- Update: 4.23ms (66% faster)
- Destroy: 2.45ms (98% faster)
- Total: 15.02ms (91% faster!)
On mobile (iPhone 12, Chrome):
- Before: 310ms total lifecycle
- After: 72ms total lifecycle
- User perception: "instant" vs "sluggish"
The One Thing Nobody Mentions
Here's what really blew my mind - Vue DevTools was causing half my performance problems. When DevTools is open, Vue tracks EVERYTHING for the component inspector. Turn it off when benchmarking. Seriously. My modals went from 45ms to 20ms just by closing DevTools.
Quick Implementation Checklist
If you're fixing existing modals, here's your priority order:
- Replace v-if with v-show (biggest impact, easiest change)
- Add Teleport to body (fixes z-index issues)
- Implement proper event cleanup (prevents memory leaks)
- Add lazy loading for heavy modals (reduces bundle size)
- Cache modal instances (faster subsequent opens)
So that's it. Three main problems, three solutions, and your modals go from sluggish to snappy. The best part? These optimizations work for any component that mounts/unmounts frequently - not just modals.
One last thing - dont optimize prematurely. If you have 2 modals in your app, the basic version is fine. But once you hit 10+ modals, or modals with complex content, these optimizations become critical.
Now go check your modal performance. I bet you'll find at least one of these issues.