Skip to content
5 changes: 5 additions & 0 deletions .changeset/mobile-menu-focus-trap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@astrojs/starlight': patch
---

Keeps keyboard focus inside the mobile menu while it is open by marking the rest of the page `inert`. Focus containment now covers all interactive elements (including sidebar group `<summary>` toggles and any custom components) and is released automatically if the viewport grows past the mobile breakpoint.
Comment thread
delucis marked this conversation as resolved.
Resolved
22 changes: 22 additions & 0 deletions packages/starlight/components/MobileMenuToggle.astro
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import Icon from '../user-components/Icon.astro';
<script>
class StarlightMenuButton extends HTMLElement {
btn = this.querySelector('button')!;
mobileMql = matchMedia('(min-width: 50em)');
Comment thread
delucis marked this conversation as resolved.
Resolved

constructor() {
super();
Expand All @@ -28,11 +29,21 @@ import Icon from '../user-components/Icon.astro';
if (parentNav) {
parentNav.addEventListener('keyup', (e) => this.closeOnEscape(e));
}

// Collapse the menu (which also clears `inert`) when the viewport
// grows past the mobile breakpoint so users on rotating or resizing
// devices are not locked out of the page content.
this.mobileMql.addEventListener('change', (e) => {
Comment thread
delucis marked this conversation as resolved.
Resolved
if (e.matches && this.getAttribute('aria-expanded') === 'true') {
this.setExpanded(false);
}
Comment thread
delucis marked this conversation as resolved.
Resolved
});
}

setExpanded(expanded: boolean) {
this.setAttribute('aria-expanded', String(expanded));
document.body.toggleAttribute('data-mobile-menu-expanded', expanded);
this.syncInert();
Comment thread
delucis marked this conversation as resolved.
Resolved
}

toggleExpanded() {
Expand All @@ -45,6 +56,17 @@ import Icon from '../user-components/Icon.astro';
this.btn.focus();
}
}

// Mark the main content and skip link `inert` while the mobile menu is
// expanded so the browser keeps keyboard focus inside the header and
// sidebar without relying on a hand-maintained list of focusable selectors.
syncInert() {
const active =
!this.mobileMql.matches && document.body.hasAttribute('data-mobile-menu-expanded');
Comment thread
delucis marked this conversation as resolved.
Resolved
for (const selector of ['.main-frame', '.sl-skip-link']) {
document.querySelector<HTMLElement>(selector)?.toggleAttribute('inert', active);
}
Comment thread
delucis marked this conversation as resolved.
Resolved
}
}

customElements.define('starlight-menu-button', StarlightMenuButton);
Expand Down
6 changes: 3 additions & 3 deletions packages/starlight/components/SkipLink.astro
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@
import { PAGE_TITLE_ID } from '../constants';
---

<a href={`#${PAGE_TITLE_ID}`}>{Astro.locals.t('skipLink.label')}</a>
<a class="sl-skip-link" href={`#${PAGE_TITLE_ID}`}>{Astro.locals.t('skipLink.label')}</a>

<style>
@layer starlight.core {
a {
.sl-skip-link {
clip: rect(0, 0, 0, 0);
position: fixed;
top: 0.75rem;
inset-inline-start: 0.75rem;
}
a:focus {
.sl-skip-link:focus {
Comment thread
delucis marked this conversation as resolved.
Resolved
clip: unset;
z-index: var(--sl-z-index-skiplink);
display: block;
Expand Down