Editable elements with contenteditable must expose the textbox role, declare whether they are single or multi-line, and provide an accessible name.
Description
This rule automatically checks that every element with a contenteditable attribute includes the role="textbox" attribute, declares whether it accepts single or multiple lines of input via aria-multiline, and provides an accessible name through aria-label or aria-labelledby. Without these attributes, assistive technologies such as screen readers cannot identify the element as an editable text control, determine its expected input format, or announce its purpose to users.
Ensuring that [contenteditable] elements expose the correct role, multiline state, and accessible name aligns with WCAG Success Criterion 4.1.2 (Name, Role, Value), which requires that all user interface components have their name and role programmatically determinable. The rule operates on any element bearing the contenteditable attribute, regardless of its tag name or the specific value of the attribute.
Disabilities impacted
- Blindness and low vision (screen reader users) – Screen readers rely on ARIA roles and properties to announce interactive controls. When a
[contenteditable]element lacksrole="textbox", it is announced as a generic element rather than an editable text field, depriving users of critical interaction cues. Missingaria-multilineleaves users unsure whether they can enter line breaks. Without an accessible name, the element is announced as an unlabeled textbox, forcing users to guess its purpose by reading surrounding content. - Cognitive disabilities – Users with cognitive impairments, memory challenges, or learning disabilities benefit from clear, consistent labeling of all interactive controls. When an editable region lacks an accessible name or presents an incorrect role, it creates ambiguity and increases cognitive load. The user must expend additional effort to determine what the control does and how to interact with it, which can lead to confusion, errors, and task abandonment.
- Motor disabilities – Individuals who rely on speech recognition software, switch devices, or eye-tracking systems depend on properly exposed roles and names to issue commands. For example, voice-command users may say
click edit description
orfocus textbox
. If the element does not exposerole="textbox"or lacks a programmatic accessible name, the speech engine cannot target it, rendering the control inaccessible via voice. Switch users navigating by role (e.g., jumping between textboxes) will skip over the element entirely. - Visual impairments with screen magnification – Users who magnify the screen see only a small portion of the page at a time. They rely on consistent role announcements and labels to locate and identify editable regions. Without proper ARIA attributes, they must manually scan the page to find and understand each
[contenteditable]element, a time-consuming and visually taxing process.
Why it matters
Contenteditable elements power rich text editors, inline-editable fields, comment boxes, and WYSIWYG components across the modern web. When implemented without the correct accessibility attributes, these elements become invisible to assistive technology – they appear as generic <div> or <span> elements instead of interactive text inputs. This directly violates the accessibility principle that all user interface components must be programmatically determinable. The result is that users who rely on screen readers, voice control, or switch devices cannot discover, understand, or operate contenteditable-based editing controls, excluding them from core content creation workflows.
Beyond the immediate usability impact, failing to properly expose contenteditable elements creates legal and compliance risks. Organizations subject to ADA Title III, Section 508 of the Rehabilitation Act, or the European Accessibility Act (EAA) may be found non-compliant if interactive editing controls are inaccessible. From a product perspective, a fully accessible editing experience benefits all users: it improves the reliability of automation scripts, increases the robustness of test suites, and demonstrates a commitment to inclusive design that builds trust with a diverse user base.
Coding problems and solutions
Common coding problems
- Missing role=”textbox” – A
[contenteditable]element withoutrole="textbox"is exposed to assistive technology as a generic element (e.g.,<div>), not as an editable text control. Screen readers and voice command software do not recognize it as an input field. - Missing aria-multiline – Without
aria-multiline, assistive technology has no information about whether the editor supports single or multiple lines. Users may expect single-line behavior when multi-line input is permitted, or vice versa, leading to confusion and input errors. - Missing accessible name (aria-label or aria-labelledby) – When neither
aria-labelnoraria-labelledbyis present, the element has no programmatic accessible name. Screen readers may fall back to announcingtextbox
without any label, or worse, announce a genericeditable
without context, forcing users to guess the element’s purpose. - Relying on the title attribute for naming – Some developers use
titleto label contenteditable elements. However,titleis not part of the accessible name computation for textbox roles in all browser and screen-reader combinations, making it an unreliable naming strategy. - Applying contenteditable to structural elements without ARIA – Making a
<table>,<article>, or<section>contenteditable without adding the required ARIA attributes creates interactive regions that assistive technology cannot properly interpret. Even if the element is technically usable by sighted users, it remains inaccessible to screen reader and voice-control users.
How to fix it
Add role=”textbox” to every contenteditable element
The role="textbox" explicitly informs assistive technology that the element is an editable text input control. Without it, screen readers treat [contenteditable] elements as plain text nodes or generic containers, preventing users from interacting with them as form controls.
<div contenteditable="true" role="textbox" aria-multiline="true" aria-label="Edit description">
Enter description here...
</div><!-- Missing role="textbox" - announced as a generic container -->
<div contenteditable="true">
Enter description here...
</div>
<!-- Using a non-textbox role - incorrectly identified -->
<div contenteditable="true" role="region">
Enter description here...
</div>Declare single or multi-line behavior with aria-multiline
The aria-multiline attribute tells assistive technology whether the textbox accepts line breaks ("true") or expects input on a single line ("false"). When omitted, screen readers may assume single-line behavior by default, which can prevent users from discovering that multi-line editing is available.
<!-- Multi-line editor -->
<div contenteditable="true" role="textbox" aria-multiline="true"
aria-label="Edit article body">
Article content goes here...
</div>
<!-- Single-line inline editor -->
<span contenteditable="true" role="textbox" aria-multiline="false"
aria-label="Edit title">
Page title
</span><!-- Missing aria-multiline - assistive technology cannot
determine whether line breaks are accepted -->
<div contenteditable="true" role="textbox"
aria-label="Edit description">
Enter description here...
</div>Provide an accessible name with aria-label
Use aria-label to supply an accessible name when the contenteditable element does not have a visible label element to reference. The label should concisely describe what the editable field represents. The title attribute is not a reliable fallback for accessible naming and should not be used as the sole naming mechanism.
<!-- Accessible name provided via aria-label -->
<div contenteditable="true" role="textbox" aria-multiline="true"
aria-label="Comment text">
Write your comment here...
</div><!-- No aria-label or aria-labelledby - no accessible name -->
<div contenteditable="true" role="textbox" aria-multiline="true">
Write your comment here...
</div>
<!-- title attribute alone is insufficient for naming -->
<div contenteditable="true" role="textbox" aria-multiline="true"
title="Comment text">
Write your comment here...
</div>Provide an accessible name with aria-labelledby
When a visible label already exists on the page (e.g., a heading, paragraph, or adjacent <label> element), use aria-labelledby to reference its id. This associates the contenteditable element with its visible label, ensuring the accessible name matches what sighted users see.
<!-- Visible label referenced via aria-labelledby -->
<h3 id="bio-heading">Biography</h3>
<div contenteditable="true" role="textbox" aria-multiline="true"
aria-labelledby="bio-heading">
Write your biography here...
</div><!-- Visible heading exists but no association is made -->
<h3 id="bio-heading">Biography</h3>
<div contenteditable="true" role="textbox" aria-multiline="true">
Write your biography here...
</div>Known Limitations
- Dynamic DOM mutations – Contenteditable elements added to the DOM after the initial page scan (e.g., via client-side rendering in SPAs, lazy-loaded modules, or user-triggered interactions) are not evaluated by this rule. Audit results reflect only the DOM state at the time the rule runs.
- Shadow DOM – Elements with
contenteditablerendered inside closed shadow roots are not traversed by the rule’s selector. Open shadow roots are included, but closed encapsulation prevents the rule from accessing those nodes. - Cross-origin iframes – Contenteditable elements nested within cross-origin iframes are outside the rule’s reach due to browser security restrictions. Inline frames from the same origin are assessed.
- Presence-only validation for aria-multiline – The rule checks only that the
aria-multilineattribute is present on the element, not whether its value is semantically appropriate (e.g.,"true"for multi-line editors versus"false"for single-line fields). A human reviewer should confirm the value matches the intended behavior. - No accessible name content validation – The rule verifies that
aria-labeloraria-labelledbyis present, but it does not validate the content or quality of the accessible name. An emptyaria-label=""or a reference to a non-existent element viaaria-labelledbywill still pass the check. Manual review is required to ensure the name is meaningful and correctly resolved.
Resources
- WAI-ARIA 1.2: textbox role specification
- MDN Web Docs: contenteditable global attribute
- WCAG 2.2 Success Criterion 4.1.2 – Name, Role, Value
- WAI-ARIA Authoring Practices: Textbox pattern
- Technique ARIA7: Using aria-labelledby for link, landmark, and textbox naming
Rule
- Audit: accessibility
- Standard: SiteLint
- Level: Best practices
- Success Criteria: N/A
- Rule ID:
content-editable-missing-attributes