Skip to content

Technique ARIA14: Replacing “invisible label” with “accessible name” #4482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Technique ARIA14: Replacing “invisible label” with “accessible name” #4482

Changes from 5 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
05af16b
Formatting for easier editing
yatil Jul 3, 2025
e1df541
Replacing “invisible label” with “accessible name”
yatil Jul 3, 2025
b06d50d
Make it more XML compatible
yatil Jul 3, 2025
5591aeb
Typos
yatil Jul 3, 2025
e8b2c18
Update techniques/aria/ARIA14.html
patrickhlauke Jul 3, 2025
f02a31f
Merge branch 'main' into fix-aria14
patrickhlauke Jul 3, 2025
b07f06f
Changed working example
yatil Jul 4, 2025
4a3388b
Merge remote-tracking branch 'refs/remotes/yatil/fix-aria14'
yatil Jul 4, 2025
3028a14
Re-add dialog stuff after the merge into my branch overwrote my changes
yatil Jul 4, 2025
f9ecb0e
Update techniques/aria/ARIA14.html
yatil Jul 4, 2025
0c8ea5b
Merge branch 'main' into fix-aria14
patrickhlauke Jul 11, 2025
1fb4415
Merge branch 'main' into fix-aria14
patrickhlauke Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 81 additions & 48 deletions techniques/aria/ARIA14.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,96 @@
<!DOCTYPE html><html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"><head><title>Using aria-label to provide an invisible label where a visible label cannot be used</title><link rel="stylesheet" type="text/css" href="../../css/editors.css" class="remove"/></head><body><h1>Using aria-label to provide an invisible label where a visible label cannot be used</h1><section class="meta"><p class="id">ID: ARIA14</p><p class="technology">Technology: aria</p><p class="type">Type: Technique</p></section><section id="applicability"><h2>When to Use</h2>
<!DOCTYPE html>
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
<title>Using aria-label to provide an accessible name where a visible label cannot be used</title>
<link rel="stylesheet" type="text/css" href="../../css/editors.css" class="remove" />
</head>

<body>
<h1>Using aria-label to provide an accessible name where a visible label cannot be used</h1>
<section class="meta">
<p class="id">ID: ARIA14</p>
<p class="technology">Technology: aria</p>
<p class="type">Type: Technique</p>
</section>
<section id="applicability">
<h2>When to Use</h2>
<p>Technologies that support <a href="https://www.w3.org/TR/wai-aria/">Accessible Rich Internet Applications (WAI-ARIA)</a>. </p>
</section><section id="description"><h2>Description</h2>
<p>For sighted users, the context and visual appearance of an element can provide sufficient cues to determine the purpose. An example is the 'X' often used in the top right corner of pop-up <code class="language-html">div</code>s (light boxes) to indicate the control for closing the div.
</p>
<p>In some situations, elements can be given the attribute <code class="language-html">aria-label</code> to provide an accessible name for situations when there is no visible label due to a chosen design approach or layout but the context and visual appearance of the control make its purpose clear.</p>
</section>
<section id="description">
<h2>Description</h2>
<p>For sighted users, the context and visual appearance of an element can provide sufficient cues to determine the purpose. An example is the “&times;” often used in the top-right corner of dialogs to indicate the control for closing the dialog. While it might be visually clear that the “&times;” button closes the dialog, users with assistive technologies rely on accessible names that clearly communicate the purpose of components, in this case “Close”.
</p>
<p>When no clear visible text label is available due to design decisions, the accessible name can be set by using the <code class="language-html">aria-label</code> attribute instead.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't accurate; you can't always use aria-label any time you want to give an accessible name to any arbitrary element. Notably, in the exact example implied by the following paragraphs (<div aria-label="whatever" contenteditable></div>, aria-label would not be allowed unless the author also gave the div an explicit role (because WAI-ARIA prohibits the use of aria-label and aria-labelledby on elements with generic roles, like div is by default)).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dbjorge, would this help?

Suggested change
<p>When no clear visible text label is available due to design decisions, the accessible name can be set by using the <code class="language-html">aria-label</code> attribute instead.</p>
<p>When no clear visible text label is available due to design decisions, the accessible name of a user interface control can be set by using the <code class="language-html">aria-label</code> attribute instead.</p>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>When no clear visible text label is available due to design decisions, the accessible name can be set by using the <code class="language-html">aria-label</code> attribute instead.</p>
<p>When no clear visible text label is available due to design decisions, the accessible name can be set by using the <code class="language-html">aria-label</code> attribute instead, provided that the element has an implict or explicit <a href="https://www.w3.org/TR/wai-aria-1.2/#namefromauthor">role that supports naming</a>.</p>


<p>In other situations, elements can be given the attribute <code class="language-html">aria-label</code> to provide an accessible name when the native HTML labeling element is not supported by the control - for example, when a <code class="language-html">div</code> set to <code class="language-html">contentEditable</code> is used instead of native form elements such as <code class="language-html">input type="text"</code> or <code class="language-html">textarea</code> in order to provide a richer text editing experience.</p>
<p>The <code class="language-html">aria-label</code> attribute can also be used to provide an accessible name for custom controls. Custom controls can’t use techniques for native HTML controls, like using a <code class="language-html">&lt;label&gt;</code> element with the <code class="language-html">for</code> attribute. When a <code class="language-html">&lt;div&gt;</code> element is made editable using the <code class="language-html">contentEditable</code> attribute, instead of native form elements such as <code class="language-html">&lt;input type="text"&gt;</code> or <code class="language-html">&lt;textarea&gt;</code>, in order to provide a richer text editing experience, it needs an accessible name provided by <code class="language-html">aria-label</code> or <code class="language-html">aria-labelledby</code>.</p>

</section><section id="examples"><h2>Examples</h2>
</section>
<section id="examples">
<h2>Examples</h2>
<section class="example">
<h3>A close button in a pop-up box</h3>
<p>On a page, a link displays a pop-up box (a <code class="language-html">div</code>) with additional information. The 'close' element is implemented as a <code class="language-html">button</code> containing merely the letter 'X'. The property <code class="language-html">aria-label="close"</code> is used to provide an accessible name to the <code class="language-html">button</code>.</p>
<pre xml:space="preserve"><code class="language-html">&lt;div id="box"&gt;
This is a pop-up box.
&lt;button aria-label="Close"&gt;X&lt;/button&gt;
<h3>A close button in a dialog</h3>

<p>On a page, a button displays a dialog (a <code class="language-html">&lt;div&gt;</code> element) with additional information. The “close” element is implemented as a <code class="language-html">&lt;button&gt;</code> containing merely the symbol “&times;”. The property <code class="language-html">aria-label="close"</code> is used to provide an accessible name to the button.</p>
<pre xml:space="preserve"><code class="language-html">&lt;div id="box"&gt;
This is a dialog.
&lt;button aria-label="Close"&gt;&times;&lt;/button&gt;
&lt;/div&gt;</code></pre>
<p class="working-example">Working example: <a href="../../working-examples/aria-label-invisible-label-box/">Close button example</a>.
</p>
<p class="working-example">Working example: <a href="../../working-examples/aria-label-invisible-label-box/">Close button example</a>.
</p>

</section>
<section class="example">
<h3>A phone number with multiple fields</h3>
<pre xml:space="preserve"><code class="language-html">&lt;div role="group" aria-labelledby="groupLabel"&gt;
<h3>A phone number with multiple fields</h3>

<pre xml:space="preserve"><code class="language-html">&lt;div role="group" aria-labelledby="groupLabel"&gt;
&lt;span id="groupLabel"&gt;Work Phone&lt;/span&gt;
+&lt;input autocomplete="tel-country-code" type="number" aria-label="country code"&gt;
&lt;input autocomplete="tel-area-code" type="number" aria-label="area code"&gt;
&lt;input autocomplete="tel-local" type="number" aria-label="subscriber number"&gt;
&lt;/div&gt;</code></pre>

</section>
</section><section id="tests"><h2>Tests</h2>
<section class="procedure"><h3>Procedure</h3>
<p>For elements that use <code class="language-html">aria-label</code>:
</p>
<ol>
<li>Check that the value of the <code class="language-html">aria-label</code> attribute properly describes the purpose of an element where user input is required
</li>
</ol>
</section>
<section id="tests">
<h2>Tests</h2>
<section class="procedure">
<h3>Procedure</h3>
<p>For elements that use the <code class="language-html">aria-label</code> attribute:
</p>
<ol>
<li>Check that the value of the <code class="language-html">aria-label</code> attribute properly describes the purpose of an element where user input is required
</li>
</ol>
</section>
<section class="results"><h3>Expected Results</h3>
<ul>
<li>#1 is true.</li>
</ul>
<section class="results">
<h3>Expected Results</h3>
<ul>
<li>#1 is true.</li>
</ul>
</section>
</section><section id="related"><h2>Related Techniques</h2><ul>
<li><a href="../aria/ARIA6">ARIA6</a></li>
<li><a href="../aria/ARIA16">ARIA16</a></li>
</ul></section><section id="resources"><h2>Resources</h2>

<ul>
<li>
<a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>
</li>
<li>
<a href="https://www.w3.org/TR/html-aam/">HTML Accessibility API Mappings</a>
</li>
</ul>

</section>
</body></html>
</section>
<section id="related">
<h2>Related Techniques</h2>
<ul>
<li><a href="../aria/ARIA6">ARIA6</a></li>
<li><a href="../aria/ARIA16">ARIA16</a></li>
</ul>
</section>
<section id="resources">
<h2>Resources</h2>

<ul>
<li>
<a href="https://www.w3.org/WAI/ARIA/apg/">WAI-ARIA Authoring Practices Guide</a>
</li>
<li>
<a href="https://www.w3.org/TR/html-aam/">HTML Accessibility API Mappings</a>
</li>
</ul>

</section>
</body>

</html>