Operational article · published
Ship Crawlable Internal Links in React Interfaces
Decide which navigation controls must be anchors with resolvable href values and which can remain stateful buttons. Includes a worked example and a release checklist.
Reviewed 2026-11-18 · National guidance, Austin proofThe task and the failure mode
Built for: React developers and SEO owners checking whether a person and a crawler can reach the same public pages.
For navigation to another public page, render an anchor with a real href. React Router’s Link can provide that anchor while keeping client navigation. A button with an onClick handler, or an anchor without href, can work after JavaScript runs but does not expose the same link for URL extraction. Keep buttons for actions such as opening a filter. Check the delivered HTML and the rendered DOM separately: a valid link added during rendering can still be discovered by Google, while putting important links in the initial response reduces that dependency.
Decision brief
Choose the destination first. A service, article or next results page needs a stable public URL. A dialog, disclosure or local filter can remain an action without pretending to be a new page.
Inspect the HTML that reaches the browser. A Link component’s name is not the test: its output needs an anchor with a resolvable href and useful link text. Check relative destinations against the actual page URL.
Direct loading and client navigation are separate checks. Follow the link, open the destination directly, reload it and use Back. A working click can conceal a missing server route or stale route metadata.
Compare the original HTML with the rendered links →
Questions to answer before changing the system
- 01Is this control navigation to a public URL, movement within the current document, or a local interface action?
- 02Does the initial response contain an anchor with the intended href, and does that anchor remain after rendering?
- 03If JavaScript creates the link, can rendering complete without a click, scroll, login or unresolved request?
- 04Does the href resolve to the intended route from this page, including any nested route or configured base path?
- 05Does the destination work as a direct document request with the expected status, answer and canonical?
Workflow
- 01Pick one important contextual link and write down its source page, visible text and exact intended destination. Use the same deployed version for all comparisons.
- 02Read the source page’s HTTP response before executing JavaScript. Locate the navigation markup and resolve its href against the final response URL. Record a missing href as missing, rather than inferring it from a click handler.
- 03Render the same page and inspect its anchors. Separate links that were present initially, links added by rendering and controls that never become anchors. Do not label a valid rendered link undiscoverable merely because it was absent from the response.
- 04For a route-changing button or anchor without href, use an ordinary anchor or the router’s Link with the intended destination. Preserve meaningful visible text; keep genuine interface actions as buttons.
- 05Follow the repaired link with JavaScript enabled. Check the new answer and route metadata, then use Back and Forward. Open and reload the exact destination directly to test the server route as well.
- 06Disable JavaScript and follow links that the application promises to deliver in the initial response. Check one phone and one desktop layout. If navigation relies on rendering, record that design choice and test its failure state.
- 07Check a representative sibling from the same component after the release. Review later crawl and search data on its own dates; an anchor correction alone does not establish indexing or a ranking gain.
Evidence to retain
- Source URL, intended destination, deployed version and capture time.
- The exact initial anchor or non-link markup and the corresponding rendered markup.
- A resolved destination URL rather than a component prop or a guessed click target.
- Direct-load status, visible answer and canonical, plus click/reload/Back results.
- Phone and desktop output showing readable descriptive text and a usable target.
- Whether each anchor arrived in the response or depended on a successful render.
- The navigation component and router version used for the exact comparison.
React button versus Link: the actual HTML difference
- The authored case
- We rendered four controls to static HTML with React and React Router using the same text, “Compare website options,” and the same intended destination, /services/website-development. These are local comparison cases, not a client crawl or a Google indexing experiment. The records below show the emitted element, attributes and text.
- Click-only button
- Element: button. Attributes: type="button"; no href. Text: “Compare website options”. React does not serialize the onClick handler into a crawlable destination. A click can work once the app attaches the handler, but that does not add a destination to the initial markup.
- Anchor without href
- Element: a. Attributes: no href. Text: “Compare website options”. The input had only an onClick handler. Its tag name alone does not supply a destination, and adding role="link" would not create an href.
- React Router Link
- Element: a. Attributes: href="/services/website-development", data-discover="true". Text: “Compare website options”. The input Link had to="/services/website-development". The emitted anchor and href supply the destination; the data attribute is router behavior in our installed version, not a replacement for href.
- Ordinary anchor
- Element: a. Attributes: href="/services/website-development". Text: “Compare website options”. Both valid anchors can be followed as document links when delivered in the response. The destination must still support a direct request.
Link semantics audit release checklist
- Every tested public navigation control produces an anchor with a real href.
- Visible anchor text identifies the destination or decision.
- The href resolves correctly from the actual source URL and base path.
- Important initial-response links survive hydration with the same destination.
- Direct load, click, reload and browser history reach the intended answer and metadata.
- Buttons remain usable for genuine local actions; they are not counted as incoming URL links.
- Rendering-dependent links and unresolved destination failures are recorded separately.
- A link generated by rendering appears without an extra interaction to reveal it.
- A same-document contents link is not counted as a separate public page.
- A representative sibling using the repaired component passes the same checks.
What to measure—and what it does not prove
- For the tested routes, count expected navigation destinations with valid initial anchors, valid rendered-only anchors and missing anchors separately.
- Track direct-request failures separately from missing link markup: either can interrupt the journey, but they require different fixes.
- Compare later dated crawl and search observations after release. This markup test measures navigation behavior, not Google’s selected index or a causal ranking effect.
- Group repeat failures by the owning navigation component to distinguish one faulty instance from a shared template defect.
Boundaries and caveats
Google can use valid anchors inserted by JavaScript. Initial HTML availability improves resilience; it is not a claim that every client-rendered link is invisible.
A same-document fragment can be a valid contents link. It does not stand in for a separate public article or service URL.
A sitemap can disclose a URL without supplying the contextual route or descriptive anchor tested here.
React Router output varies by version and configuration. Verify the emitted anchor and direct route in your own application.
Primary sources
- Google Search Central: Link best practicesdevelopers.google.com
- Google Search Central: JavaScript SEO basicsdevelopers.google.com
- React Router: Linkreactrouter.com
- React: renderToStaticMarkupreact.dev
Start with one bounded case
Choose one public route-changing control. Compare its initial HTML and rendered anchor, repair a missing href at the component that owns navigation, then follow and directly reload the destination. Keep the same test when that component ships again.