Homepage cards should land on the right project or Field Note—not the top of a long index page. That means linking to /projects/#project-highline-real-estate or /journal/#journal-mock-first-handoff-before-mls-integration instead of bare route paths. In a client-rendered app, three things fight that intent on every navigation.
First, a global ScrollToTop helper runs on pathname change and snaps the viewport to zero. Second, the hash target often lives in a lazy below-fold section that has not mounted yet—so document.getElementById returns null on the first paint. Third, a sticky header covers the top of the scrolled element unless you reserve offset with CSS. Miss any one of those and the user clicks a card and lands nowhere useful.
I wired this on briancrabtree.me so homepage project and journal tiles scroll to the matching row on /projects/ and /journal/. The pattern is small, but every piece has to agree.
\n\nThe default SPA scroll reset is correct for normal route changes. It is wrong when the URL carries an anchor. If pathname changes and you always call window.scrollTo(0, 0), you erase the browser’s hash intent before your scroll hook runs.
The fix is one guard: if location.hash is non-empty, return early and let the hash handler own vertical position. Route changes without a hash still scroll to top. Deep links with #project-… or #journal-… skip the reset.
Hash fragments and DOM ids must match exactly. I centralize both in utils/journalUrl.ts: projectIndexHashPath(id) returns /projects/#project-{id}, and journalIndexHashPath(slug) returns /journal/#journal-{slug}. The portfolio and journal index pages render matching id attributes on each card row.
Homepage grids import those helpers—no string concatenation scattered across components. When the id scheme changes, one file updates and every link stays consistent.
\n\n- [ ] ScrollToTop skips when location.hash is set\n- [ ] hash path helpers match card id attributes\n- [ ] below-fold section gated until idle (requestIdleCallback)\n- [ ] scroll hook retries until getElementById succeeds\n- [ ] scroll-margin-top clears sticky header\n- [ ] journal hash selects correct archive page before scrollPortfolio and Field Notes index pages defer heavy below-fold markup until the shell paints. Featured hero, skeleton states, and API fetches finish first; the project grid and archive list mount after requestIdleCallback (with a timeout fallback). That keeps first paint fast—but it means the hash target does not exist on initial render.
A scroll hook gated on ready && !loading && data.length avoids firing into an empty DOM. When below-fold flips ready, the hook reads location.hash, strips the prefix (project- or journal-), finds the element, and calls scrollIntoView({ behavior: 'smooth', block: 'start' }).
Elements still miss on the first tick if React is mid-commit. I retry on a short backoff schedule—0 ms, 50 ms, 150 ms, up to 3 seconds—until the target mounts or the user navigates away. No infinite loops, no MutationObserver tax.
Field Notes archive paginates. A hash like #journal-some-slug might point at a post on page three. Before scrolling, parse the slug from the hash, find its index in the filtered list, compute the page number, and set current page if needed. Clear an active search filter so the target row is actually in the DOM.
Page changes normally scroll to top. When a journal hash is present, skip that reset—the hash hook will position the viewport once the correct page renders.
\n\nscrollIntoView aligns the element’s top edge with the viewport top. A fixed nav sits on that edge and hides the card title. scroll-margin-top: 120px on portfolio rows and journal cards reserves space so the scrolled target clears the header buffer. Pure CSS, no JavaScript offset math.
From the homepage, click a project card—you should land on the matching row on the portfolio page, not the featured block at the top. Try a direct load:
\n\nbriancrabtree.me/projects/#project-highline-real-estate
\n\nbriancrabtree.me/journal/#journal-mock-first-handoff-before-mls-integration
\n\nBoth should smooth-scroll to the anchored card with the title visible below the nav. If you still land at the top, walk the checklist: hash guard on ScrollToTop, ready gate, retry hook, scroll-margin, and—for journal—pagination sync.
\n\nNone of this blocks LCP. Below-fold content stays lazy. The scroll hook is a few timeouts and one DOM lookup—negligible next to fetch and render. You get deep links that behave like a multi-page site without surrendering the SPA shell or inflating the critical path.
\n\nHash deep links are not exotic. They are baseline UX for any index page with homepage teasers. The implementation is boring on purpose: guard the global scroll reset, centralize URL shape, wait for the target, retry, offset for sticky chrome. Ship that once and every card link on the site inherits correct behavior.
","tags":["react","react-router","spa","accessibility","scroll-behavior"],"views":19}