SiteLint documentation and guidelines

ID attribute must be unique within the document.

Description

This rule detects elements that share the same HTML id attribute value within a single page. The id attribute is defined as a document-wide identifier, meaning every value must be unique across the entire HTML document. When two or more elements use the same id, assistive technologies, fragment identifiers, and JavaScript selectors cannot reliably target the intended element. The rule selects all elements with an [id] attribute, normalizes whitespace within the value, and skips empty or space-containing IDs. It then reports every duplicated id once, referencing the first element found with that value, along with the total number of occurrences.

This check is based on the W3C HTML5 Working Draft definition of the id datatype, which states that The id attribute must have a value that is not a space character (referred to as non-empty). Duplicated IDs violate WCAG Success Criterion 4.1.1 (Parsing, now deprecated in WCAG 2.2 but still relevant as a best practice) and the WHATWG HTML Specification, which requires that The value must be unique among all the ids in the tree scope.

Disabilities impacted

  • Blindness and low vision (screen reader users) – Screen readers use id values to build the accessibility tree and to associate labels with controls via for, aria-labelledby, aria-describedby. Duplicate IDs cause these associations to resolve to the wrong element, making labels, descriptions, and landmarks unreliable for users who depend on auditory feedback.
  • Cognitive disabilities – When id duplication breaks ARIA relationships, form labels or descriptions may appear disconnected from their inputs. Users with cognitive impairments who rely on clear, predictable labeling must spend extra effort deciphering which label belongs to which control, increasing cognitive load and error rates.
  • Motor disabilities – Users who navigate via keyboard or assistive technology depend on programmatic relationships between controls and their associated elements. Duplicate IDs can cause focus to move to an unexpected element or skip a target entirely, making keyboard navigation unreliable for users with limited motor control.
  • Deaf and hard of hearing – In pages that use id duplication in combination with aria-live regions or caption references, duplicated IDs can cause screen readers or captioning systems to read content from the wrong source, making multimedia information incomprehensible for users who rely on assistive text alternatives.

Why it matters

Unique id attributes are a fundamental requirement of valid HTML and are essential for correct behavior of fragment identifiers, CSS selectors, JavaScript DOM queries, and ARIA relationship attributes. When IDs are duplicated, document.getElementById() returns only the first matching element, silently ignoring all subsequent elements with the same ID. This causes CSS styles, JavaScript behavior, and ARIA label/description associations to target the wrong element, producing hard-to-diagnose bugs that disproportionately affect assistive technology users.

Beyond accessibility, duplicate IDs break deep-linking, break automated testing frameworks that rely on id-based selectors, and invalidate HTML validation. For sites subject to ADA, Section 508, or the European Accessibility Act (EAA), duplicate IDs represent a concrete compliance risk that can be flagged during audits and litigation. The issue is especially prevalent in pages assembled from multiple components, templates, or third-party widgets, where different parts of the codebase inadvertently define the same id value.

Coding problems and solutions

Common coding problems

  • Copied HTML blocks with unchanged IDs – A component (e.g., an accordion, modal, or form) is duplicated on the same page without generating unique IDs for each instance. All copies share the same id values for their inner elements.
  • Third-party widgets injecting fixed IDs – Embedded widgets (chat, analytics, payment forms, social feeds) use hardcoded id values that collide with IDs already present on the host page.
  • Template loops without unique ID generation – A server-side or client-side loop renders the same template block multiple times (e.g., a list of product cards) but uses a static string for the id attribute instead of incorporating a unique identifier such as an index or data key.
  • JavaScript-generated elements with static IDs – A script that dynamically creates DOM elements assigns the same id to each new element, producing duplicates each time it runs.
  • ARIA attributes referencing duplicated IDs – Multiple elements use aria-labelledby, aria-describedby, or aria-controls with an id value that exists on more than one element, breaking the programmatic association.
  • IDs with leading/trailing whitespace – Whitespace around an id value (e.g., id=" section ") is normalized during parsing but may appear unique in the source code while actually duplicating a trimmed ID.

How to fix it

Generate unique IDs in loops and repeated templates

When rendering repeated blocks of HTML in a loop, incorporate a unique identifier such as the loop index, a data primary key, or a UUID into each id value. This ensures every rendered instance has a distinct ID even when the underlying template is identical.

Correct example
<!-- Server-side template with unique IDs per iteration -->
<li id="product-1" class="product-item">
  <img id="product-img-1" src="shoe.jpg" alt="Running shoe">
  <a href="/product/1" id="product-link-1">View details</a>
</li>
<li id="product-2" class="product-item">
  <img id="product-img-2" src="hat.jpg" alt="Sun hat">
  <a href="/product/2" id="product-link-2">View details</a>
</li>
Incorrect example
<!-- Same ID on every list item — duplicated IDs -->
<li id="product" class="product-item">
  <img id="product-img" src="shoe.jpg" alt="Running shoe">
  <a href="/product/1" id="product-link">View details</a>
</li>
<li id="product" class="product-item">
  <img id="product-img" src="hat.jpg" alt="Sun hat">
  <a href="/product/2" id="product-link">View details</a>
</li>

Use scoped or namespaced IDs for repeated components

When multiple instances of the same component appear on a page (e.g., two accordion widgets or two search forms), prefix each component’s internal IDs with a unique namespace derived from the component instance. This prevents cross-instance collisions while keeping IDs human-readable.

Correct example
<!-- First accordion instance -->
<div class="accordion" id="faq-accordion">
  <h2 id="faq-accordion-heading-1">
    <button type="button" aria-expanded="true" aria-controls="faq-accordion-panel-1">What is your return policy?</button>
  </h2>
  <div id="faq-accordion-panel-1" role="region" aria-labelledby="faq-accordion-heading-1">
    <p>We accept returns within 30 days.</p>
  </div>
</div>

<!-- Second accordion instance — unique scoped IDs -->
<div class="accordion" id="returns-accordion">
  <h2 id="returns-accordion-heading-1">
    <button aria-expanded="false" aria-controls="returns-accordion-panel-1">How do I start a return?</button>
  </h2>
  <div id="returns-accordion-panel-1" role="region" aria-labelledby="returns-accordion-heading-1">
    <p>Contact support to initiate a return.</p>
  </div>
</div>
Incorrect example
<!-- Two accordions sharing the same IDs -->
<div class="accordion" id="accordion">
  <h2 id="heading-1">
    <button type="button" aria-expanded="true" aria-controls="panel-1">What is your return policy?</button>
  </h2>
  <div id="panel-1" role="region" aria-labelledby="heading-1">
    <p>We accept returns within 30 days.</p>
  </div>
</div>

<div class="accordion" id="accordion">
  <h2 id="heading-1">
    <button type="button" aria-expanded="false" aria-controls="panel-1">How do I start a return?</button>
  </h2>
  <div id="panel-1" role="region" aria-labelledby="heading-1">
    <p>Contact support to initiate a return.</p>
  </div>
</div>

Generate dynamic IDs in JavaScript for dynamically created elements

When JavaScript creates DOM elements dynamically, use a counter, UUID, or timestamp to assign unique id values. Never use a static string inside a loop or repeated function call.

Correct example
const container = document.getElementById('notifications');
let notificationCounter = 0;

const addNotification = (message) => {
  notificationCounter += 1;
  const id = `notification-${notificationCounter}`;
  const element = document.createElement('div');
  element.id = id;
  element.role = 'alert';
  element.textContent = message;
  container.appendChild(element);
};
Incorrect example
const container = document.getElementById('notifications');

const addNotification = (message) => {
  const element = document.createElement('div');
  element.id = 'notification'; // Every call creates a duplicate
  element.role = 'alert';
  element.textContent = message;
  container.appendChild(element);
};

Verify ARIA relationship attributes reference unique IDs

Before releasing, audit all aria-labelledby, aria-describedby, aria-controls, and aria-owns attributes to confirm their referenced id values exist exactly once in the document. Use browser DevTools or automated accessibility testing tools to catch mismatches early.

Correct example
<label for="email-input-1">Email address</label>
<input type="email" id="email-input-1" aria-describedby="email-hint-1">
<span id="email-hint-1">We will never share your email.</span>
Incorrect example
<!-- "email-hint" is duplicated across two form groups -->
<label for="email-input-1">Work email</label>
<input type="email" id="email-input-1" aria-describedby="email-hint">
<span id="email-hint">Used for billing.</span>

<label for="email-input-2">Personal email</label>
<input type="email" id="email-input-2" aria-describedby="email-hint">
<span id="email-hint">Used for newsletters.</span>

Use CSS classes instead of IDs for styling repeated elements

If an id attribute is used solely for CSS styling on elements that appear multiple times, replace it with a class attribute. CSS classes are explicitly designed to be reusable and do not require uniqueness. Reserve id for cases where a unique programmatic reference is genuinely needed.

Correct example
<!-- Use class for styling — no uniqueness requirement -->
<div class="card card--featured">
  <h3 class="card__title">Featured product</h3>
  <p class="card__description">Best seller this month.</p>
</div>
<div class="card">
  <h3 class="card__title">New arrival</h3>
  <p class="card__description">Just landed in store.</p>
</div>
Incorrect example
<!-- Using id for styling on repeated elements creates duplicates -->
<div id="card">
  <h3 id="card-title">Featured product</h3>
  <p id="card-description">Best seller this month.</p>
</div>
<div id="card">
  <h3 id="card-title">New arrival</h3>
  <p id="card-description">Just landed in store.</p>
</div>

Known Limitations

  • Single-page scope – The rule only analyzes elements present in the current document. It does not compare id values across different pages, routes, or dynamically loaded content that has not yet been inserted into the DOM.
  • Shadow DOM boundaries – Elements inside closed shadow roots are not reachable by the rule’s [id] selector. Open shadow roots may or may not be traversed depending on the browser and the auditor’s DOM traversal strategy, so duplicated IDs inside shadow DOM can go undetected.
  • Iframes and cross-origin documents – Each <iframe> has its own document scope. The rule does not traverse into iframes, so duplicate IDs that span the host document and an embedded document will not be flagged.
  • Single-page applications (SPAs) with client-side routing – In SPAs, the DOM is mutated by JavaScript without full page reloads. The rule captures the state of the DOM at scan time; elements added or removed by framework re-renders after the scan are invisible to it.
  • IDs containing whitespace – The rule intentionally skips id values that contain space characters, since these are invalid per the HTML specification. Such IDs are silently ignored rather than reported as duplicated, which could mask related issues.
  • Dynamically generated IDs at page load – If IDs are generated by JavaScript during initial page rendering and are not present in the static HTML source, they will only be caught if the rule runs after those scripts execute. Scripts that run after the audit scan completes will not be checked with exception when live observer option is used.

Resources

Rule

  • Audit: accessibility
  • Standard: SiteLint
  • Level: Best practices
  • Success Criteria: N/A
  • Rule ID: duplicated-id-attribute