SiteLint documentation and guidelines

Broken same page link

Description

A broken same-page link, also known as an anchor link, occurs when a hyperlink intended to navigate to a specific section within the same page does not function correctly. This can happen for various reasons, such as a missing or incorrect id attribute on the target element. Broken same-page links can lead to confusion and a poor user experience, particularly for users relying on assistive technologies.

Disabilities impacted

  • Visual impairments: users with visual impairments who rely on screen readers may be unable to navigate to the intended section, leading to confusion and frustration.
  • Cognitive disabilities: users with cognitive disabilities benefit from clear and functional navigation aids; broken links can disrupt their ability to follow content logically.
  • Motor impairments: users with motor impairments who rely on keyboard navigation may struggle to reach the intended section if the link is broken.

Why it matters

Same-page links provide a way to quickly navigate to different sections within a single page, enhancing the user experience by saving time and effort. Ensuring these links work correctly is crucial for accessibility and usability. Broken same-page links can disrupt the flow of navigation and make it difficult for users to access the content they need.

Coding problems and solutions

Common coding problems

  • Missing id attribute: the target element does not have an id attribute that matches the link’s href value.
  • Incorrect id value: the id value of the target element does not match the link’s href value.
  • Typographical errors: typos in the href attribute or the id attribute of the target element.

How to fix it

Add the correct id attribute

Ensure the target element has an id attribute that matches the href value of the same-page link.

Incorrect example
<a href="#section1">Go to Section 1</a>
<div>Content of Section 1</div>
Correct example
<a href="#section1">Go to Section 1</a>
<div id="section1">Content of Section 1</div>

Ensure matching id and href values

Verify that the id value of the target element exactly matches the href value of the same-page link.

Incorrect example
<a href="#contact">Contact Us</a>
<div id="contact-us">Contact Information</div>
Correct example
<a href="#contact">Contact Us</a>
<div id="contact">Contact Information</div>

Check for typographical errors

Ensure there are no typos in the href attribute of the link or the id attribute of the target element.

Incorrect example
<a href="#about">About Us</a>
<div id="abou">About Our Company</div>
Correct example
<a href="#about">About Us</a>
<div id="about">About Our Company</div>

Known limitations

  • Dynamic content: for dynamically generated content, ensure that id attributes are correctly assigned and match the href values of same-page links.
  • Complex documents: for complex documents with many sections, careful planning and testing are required to ensure all same-page links function correctly.
  • Testing across devices: test same-page links across different devices and screen readers to ensure they provide the necessary navigation functionality.

Resources