Modal Focus Trap
Modal dialog with proper focus trap, Esc to dismiss, backdrop click to dismiss, scroll lock, focus saved + restored to opener. Compatible without <dialog> element.
$ prime install @impeccable/template-modal-focus-trap Projection
Always in _index.xml · the agent never has to ask for this.
ModalFocusTrap [template] v1.0.0
Modal dialog with proper focus trap, Esc to dismiss, backdrop click to dismiss, scroll lock, focus saved + restored to opener. Compatible without
Loaded when retrieval picks the atom as adjacent / supporting.
ModalFocusTrap [template] v1.0.0
Modal dialog with proper focus trap, Esc to dismiss, backdrop click to dismiss, scroll lock, focus saved + restored to opener. Compatible without
Language
html-css-js
Body
<style>
.modal {
position: fixed; inset: 0;
display: none;
align-items: center;
justify-content: center;
background: oklch(20% 0.02 250 / 0.55);
z-index: 1000;
padding: 16px;
}
.modal[data-open="true"] { display: flex; }
.modal__panel {
background: white;
border-radius: 12px;
max-width: {MAX_WIDTH};
width: 100%;
padding: 24px 28px;
box-shadow: 0 20px 60px oklch(20% 0.02 250 / 0.3);
animation: modal-in 180ms ease-out;
}
@keyframes modal-in {
from { transform: translateY(8px) scale(0.98); opacity: 0; }
to { transform: translateY(0) scale(1); opacity: 1; }
}
@media (prefers-reduced-motion: reduce) {
.modal__panel { animation: none; }
}
.modal__title { margin: 0 0 8px; font-size: 1.125rem; }
.modal__body { color: oklch(40% 0.02 250); line-height: 1.5; }
.modal__actions {
display: flex;
gap: 8px;
justify-content: flex-end;
margin-top: 20px;
}
.modal__btn {
padding: 8px 16px;
border-radius: 6px;
font: inherit;
cursor: pointer;
border: 1px solid oklch(85% 0.02 250);
background: white;
}
.modal__btn--primary {
background: {ACCENT_COLOR};
color: white;
border-color: transparent;
}
.modal__btn:focus-visible {
outline: 2px solid {ACCENT_COLOR};
outline-offset: 2px;
}
</style>
<button type="button" data-modal-open="confirm-modal">Open modal</button>
<div class="modal"
id="confirm-modal"
data-open="false"
role="dialog"
aria-modal="true"
aria-labelledby="confirm-title"
aria-describedby="confirm-desc"
hidden>
<div class="modal__panel" tabindex="-1">
<h2 id="confirm-title" class="modal__title">{TITLE}</h2>
<p id="confirm-desc" class="modal__body">
This action cannot be undone. Continue?
</p>
<div class="modal__actions">
<button class="modal__btn" type="button" data-modal-close>Cancel</button>
<button class="modal__btn modal__btn--primary" type="button" data-modal-confirm>Confirm</button>
</div>
</div>
</div>
<script>
(function() {
var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
document.querySelectorAll('[data-modal-open]').forEach(function(opener) {
opener.addEventListener('click', function() {
openModal(document.getElementById(opener.getAttribute('data-modal-open')), opener);
});
});
function openModal(modal, opener) {
if (!modal) return;
modal.removeAttribute('hidden');
modal.setAttribute('data-open', 'true');
modal._lastFocus = opener || document.activeElement;
document.documentElement.style.overflow = 'hidden';
var focusables = modal.querySelectorAll(FOCUSABLE);
var first = focusables[0];
var last = focusables[focusables.length - 1];
(first || modal.querySelector('.modal__panel')).focus();
modal._handler = function(e) {
if (e.key === 'Escape') {
e.preventDefault();
closeModal(modal);
} else if (e.key === 'Tab' && focusables.length > 0) {
if (e.shiftKey && document.activeElement === first) {
e.preventDefault(); last.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault(); first.focus();
}
}
};
modal.addEventListener('keydown', modal._handler);
modal._backdrop = function(e) {
if (e.target === modal) closeModal(modal);
};
modal.addEventListener('click', modal._backdrop);
modal.querySelectorAll('[data-modal-close]').forEach(function(btn) {
btn.addEventListener('click', function() { closeModal(modal); }, { once: true });
});
}
function closeModal(modal) {
modal.setAttribute('data-open', 'false');
modal.setAttribute('hidden', '');
document.documentElement.style.overflow = '';
if (modal._handler) modal.removeEventListener('keydown', modal._handler);
if (modal._backdrop) modal.removeEventListener('click', modal._backdrop);
if (modal._lastFocus && modal._lastFocus.focus) modal._lastFocus.focus();
}
window.openModal = openModal;
window.closeModal = closeModal;
})();
</script>
Usage Notes
- Always wire aria-labelledby AND aria-describedby — title + description both announced.
- Save opener element before showing modal; restore focus to it on close.
- Tab/Shift+Tab cycle within the modal — never let focus escape to the page below.
- Backdrop click closes only when target === modal (not bubbled from panel).
- Use prefers-reduced-motion to disable enter animation.
Tested In
- Chrome 120+
- Firefox 121
- Safari 17
Accessibility
- role=dialog + aria-modal=true + labelled + described.
- Focus trap via Tab handler.
- Esc + backdrop click + close button all dismiss.
- Body scroll locked while open; focus restored on close.
Loaded when retrieval picks the atom as a focal / direct hit.
ModalFocusTrap [template] v1.0.0
Modal dialog with proper focus trap, Esc to dismiss, backdrop click to dismiss, scroll lock, focus saved + restored to opener. Compatible without
Language
html-css-js
Body
<style>
.modal {
position: fixed; inset: 0;
display: none;
align-items: center;
justify-content: center;
background: oklch(20% 0.02 250 / 0.55);
z-index: 1000;
padding: 16px;
}
.modal[data-open="true"] { display: flex; }
.modal__panel {
background: white;
border-radius: 12px;
max-width: {MAX_WIDTH};
width: 100%;
padding: 24px 28px;
box-shadow: 0 20px 60px oklch(20% 0.02 250 / 0.3);
animation: modal-in 180ms ease-out;
}
@keyframes modal-in {
from { transform: translateY(8px) scale(0.98); opacity: 0; }
to { transform: translateY(0) scale(1); opacity: 1; }
}
@media (prefers-reduced-motion: reduce) {
.modal__panel { animation: none; }
}
.modal__title { margin: 0 0 8px; font-size: 1.125rem; }
.modal__body { color: oklch(40% 0.02 250); line-height: 1.5; }
.modal__actions {
display: flex;
gap: 8px;
justify-content: flex-end;
margin-top: 20px;
}
.modal__btn {
padding: 8px 16px;
border-radius: 6px;
font: inherit;
cursor: pointer;
border: 1px solid oklch(85% 0.02 250);
background: white;
}
.modal__btn--primary {
background: {ACCENT_COLOR};
color: white;
border-color: transparent;
}
.modal__btn:focus-visible {
outline: 2px solid {ACCENT_COLOR};
outline-offset: 2px;
}
</style>
<button type="button" data-modal-open="confirm-modal">Open modal</button>
<div class="modal"
id="confirm-modal"
data-open="false"
role="dialog"
aria-modal="true"
aria-labelledby="confirm-title"
aria-describedby="confirm-desc"
hidden>
<div class="modal__panel" tabindex="-1">
<h2 id="confirm-title" class="modal__title">{TITLE}</h2>
<p id="confirm-desc" class="modal__body">
This action cannot be undone. Continue?
</p>
<div class="modal__actions">
<button class="modal__btn" type="button" data-modal-close>Cancel</button>
<button class="modal__btn modal__btn--primary" type="button" data-modal-confirm>Confirm</button>
</div>
</div>
</div>
<script>
(function() {
var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
document.querySelectorAll('[data-modal-open]').forEach(function(opener) {
opener.addEventListener('click', function() {
openModal(document.getElementById(opener.getAttribute('data-modal-open')), opener);
});
});
function openModal(modal, opener) {
if (!modal) return;
modal.removeAttribute('hidden');
modal.setAttribute('data-open', 'true');
modal._lastFocus = opener || document.activeElement;
document.documentElement.style.overflow = 'hidden';
var focusables = modal.querySelectorAll(FOCUSABLE);
var first = focusables[0];
var last = focusables[focusables.length - 1];
(first || modal.querySelector('.modal__panel')).focus();
modal._handler = function(e) {
if (e.key === 'Escape') {
e.preventDefault();
closeModal(modal);
} else if (e.key === 'Tab' && focusables.length > 0) {
if (e.shiftKey && document.activeElement === first) {
e.preventDefault(); last.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault(); first.focus();
}
}
};
modal.addEventListener('keydown', modal._handler);
modal._backdrop = function(e) {
if (e.target === modal) closeModal(modal);
};
modal.addEventListener('click', modal._backdrop);
modal.querySelectorAll('[data-modal-close]').forEach(function(btn) {
btn.addEventListener('click', function() { closeModal(modal); }, { once: true });
});
}
function closeModal(modal) {
modal.setAttribute('data-open', 'false');
modal.setAttribute('hidden', '');
document.documentElement.style.overflow = '';
if (modal._handler) modal.removeEventListener('keydown', modal._handler);
if (modal._backdrop) modal.removeEventListener('click', modal._backdrop);
if (modal._lastFocus && modal._lastFocus.focus) modal._lastFocus.focus();
}
window.openModal = openModal;
window.closeModal = closeModal;
})();
</script>
Usage Notes
- Always wire aria-labelledby AND aria-describedby — title + description both announced.
- Save opener element before showing modal; restore focus to it on close.
- Tab/Shift+Tab cycle within the modal — never let focus escape to the page below.
- Backdrop click closes only when target === modal (not bubbled from panel).
- Use prefers-reduced-motion to disable enter animation.
Tested In
- Chrome 120+
- Firefox 121
- Safari 17
Accessibility
- role=dialog + aria-modal=true + labelled + described.
- Focus trap via Tab handler.
- Esc + backdrop click + close button all dismiss.
- Body scroll locked while open; focus restored on close.
Source
prime-system/examples/frontend-design/primes/compiled/@impeccable/template-modal-focus-trap/atom.yaml