Gatsby route changes focus the router wrapper instead of main content, breaking skip-link expectations

Explanation

Gatsby’s internal focus manager (from @reach/router) moves keyboard focus to the first element it renders that has tabindex="-1" – usually a wrapper div – after each client‑side route change. This is intended to announce the navigation to screen readers, but it conflicts with a skip‑link that targets <main> because focus ends up on the wrapper instead of the main landmark.

Confirmed facts

• The focus‑management API (onRouteUpdate, wrapPageElement, and the disable flag window.___focusManagementDisabled) is stable from Gatsby v2 through v5.
• Changing the skip‑link target to the router wrapper defeats the purpose of a “skip to main content” link and is not recommended.

Steps to make focus land on <main>

1. Ensure the <main> element can receive focus. Add tabindex="-1" to it (or make sure it already has a negative tabindex).
2. Create or edit gatsby-browser.js in the site root and export an onRouteUpdate function:

export const onRouteUpdate = ({ location }) => {
  const main = document.querySelector('main');
  if (main) {
    main.focus();
  }
};

1. If you prefer to disable Gatsby’s default focus manager and handle focus yourself, set the flag before any route change:

// gatsby-browser.js
window.___focusManagementDisabled = true;

export const onRouteUpdate = ({ location }) => {
  const main = document.querySelector('main');
  if (main) {
    main.focus();
  }
};

Either approach makes the router’s focus jump to <main> after navigation, keeping the skip‑link and the automatic focus in sync.

Verification

• After a client‑side navigation (e.g., clicking a <Link> or using gatsby-link), open Chrome DevTools and run document.activeElement in the console; it should return the <main> element.
• Activate the skip link with a screen reader (NVDA or VoiceOver); the reader should announce the main heading and the next Tab should move to the first focusable item inside <main>.
• To confirm the Gatsby version, run gatsby --version in the project directory; the focus‑customization steps work the same from v2 to v5.