Skip to content

Commit

Permalink
Disabled link cleanup (#34886)
Browse files Browse the repository at this point in the history
* Disabled link cleanup

per https://www.w3.org/TR/html-aria/#docconformance

> It is NOT RECOMMENDED to use `aria-disabled="true"` on an `a` element with an `href` attribute.
>
>NOTE
>If a link needs to be "disabled", remove the `href` attribute.

This PR removes the unnecessary `href="#"`, `tabindex="-1"`, and `aria-disabled="true"` from disabled links in both docs pages and examples. `aria-disabled="true"` *is* kept for disabled link-based buttons (that have `role="button"`) as there it's appropriate to use (you *want* to convey to assistive technologies that this thing you're claiming is a button is also disabled at the moment)

Further, the PR extends the "Link functionality caveat" to show the "proper" way (removing `href` and adding `.disabled` class only) to disable a link, but then explains what to do if that's not possible (and then keeps an example with all the traditional `href="#" tabindex="-1" aria-disabled="true"`, but explains clearly that it's not ideal). Same sort of explanation is also added to the pointer event utilities page

* Turn big note into actual normal doc text

Co-authored-by: Mark Otto <markd.otto@gmail.com>

Co-authored-by: Mark Otto <markd.otto@gmail.com>
Co-authored-by: XhmikosR <xhmikosr@gmail.com>
  • Loading branch information
3 people authored Sep 6, 2021
1 parent 16aab88 commit aa06dff
Show file tree
Hide file tree
Showing 19 changed files with 76 additions and 69 deletions.
20 changes: 12 additions & 8 deletions site/content/docs/5.1/components/buttons.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,18 +85,22 @@ Disabled buttons using the `<a>` element behave a bit different:

- `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled.
- Some future-friendly styles are included to disable all `pointer-events` on anchor buttons.
- Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
- Disabled buttons using `<a>` should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
- Disabled buttons using `<a>` *should not* include the `href` attribute.

{{< example >}}
<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
<a class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a>
<a class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a>
{{< /example >}}

{{< callout warning >}}
##### Link functionality caveat
### Link functionality caveat

The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether.
{{< /callout >}}
To cover cases where you have to keep the `href` attribute on a disabled link, the `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s. Note that this CSS property is not yet standardized for HTML, but all modern browsers support it. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether.

{{< example >}}
<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
{{< /example >}}

## Block buttons

Expand Down Expand Up @@ -157,7 +161,7 @@ Add `data-bs-toggle="button"` to toggle a button's `active` state. If you're pre
{{< example >}}
<a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
<a href="#" class="btn btn-primary disabled" tabindex="-1" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>
<a class="btn btn-primary disabled" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>
{{< /example >}}

### Methods
Expand Down
4 changes: 2 additions & 2 deletions site/content/docs/5.1/components/card.md
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ Add some navigation to a card's header (or block) with Bootstrap's [nav componen
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
</div>
Expand All @@ -332,7 +332,7 @@ Add some navigation to a card's header (or block) with Bootstrap's [nav componen
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
</div>
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/components/dropdowns.md
Original file line number Diff line number Diff line change
Expand Up @@ -628,7 +628,7 @@ Add `.disabled` to items in the dropdown to **style them as disabled**.
{{< example >}}
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Regular link</a></li>
<li><a class="dropdown-item disabled" href="#" tabindex="-1" aria-disabled="true">Disabled link</a></li>
<li><a class="dropdown-item disabled">Disabled link</a></li>
<li><a class="dropdown-item" href="#">Another link</a></li>
</ul>
{{< /example >}}
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/components/list-group.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ Be sure to **not use the standard `.btn` classes here**.
<a href="#" class="list-group-item list-group-item-action">A second link item</a>
<a href="#" class="list-group-item list-group-item-action">A third link item</a>
<a href="#" class="list-group-item list-group-item-action">A fourth link item</a>
<a href="#" class="list-group-item list-group-item-action disabled" tabindex="-1" aria-disabled="true">A disabled link item</a>
<a class="list-group-item list-group-item-action disabled">A disabled link item</a>
</div>
{{< /example >}}

Expand Down
14 changes: 7 additions & 7 deletions site/content/docs/5.1/components/navbar.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ Here's an example of all the sub-components included in a responsive light-theme
</ul>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -156,7 +156,7 @@ Please note that you should also add the `aria-current` attribute on the active
<a class="nav-link" href="#">Pricing</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
</div>
Expand All @@ -178,7 +178,7 @@ And because we use classes for our navs, you can avoid the list-based approach e
<a class="nav-link active" aria-current="page" href="#">Home</a>
<a class="nav-link" href="#">Features</a>
<a class="nav-link" href="#">Pricing</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</div>
</div>
</div>
Expand Down Expand Up @@ -521,7 +521,7 @@ Here's an example navbar using `.navbar-nav-scroll` with `style="--bs-scroll-hei
</ul>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Link</a>
<a class="nav-link disabled">Link</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -561,7 +561,7 @@ With no `.navbar-brand` shown at the smallest breakpoint:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -591,7 +591,7 @@ With a brand name shown on the left and toggler on the right:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -621,7 +621,7 @@ With a toggler on the left and brand name on the right:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
<form class="d-flex">
Expand Down
30 changes: 15 additions & 15 deletions site/content/docs/5.1/components/navs-tabs.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ To convey the active state to assistive technologies, use the `aria-current` att
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -43,7 +43,7 @@ Classes are used throughout, so your markup can be super flexible. Use `<ul>`s l
<a class="nav-link active" aria-current="page" href="#">Active</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</nav>
{{< /example >}}

Expand All @@ -69,7 +69,7 @@ Centered with `.justify-content-center`:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -88,7 +88,7 @@ Right-aligned with `.justify-content-end`:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -109,7 +109,7 @@ Stack your navigation by changing the flex item direction with the `.flex-column
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -121,7 +121,7 @@ As always, vertical navigation is possible without `<ul>`s, too.
<a class="nav-link active" aria-current="page" href="#">Active</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</nav>
{{< /example >}}

Expand All @@ -141,7 +141,7 @@ Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabb
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -162,7 +162,7 @@ Take that same HTML, but use `.nav-pills` instead:
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -183,7 +183,7 @@ Force your `.nav`'s contents to extend the full available width one of two modif
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -195,7 +195,7 @@ When using a `<nav>`-based navigation, you can safely omit `.nav-item` as only `
<a class="nav-link active" aria-current="page" href="#">Active</a>
<a class="nav-link" href="#">Much longer nav link</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</nav>
{{< /example >}}

Expand All @@ -213,7 +213,7 @@ For equal-width elements, use `.nav-justified`. All horizontal space will be occ
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -225,7 +225,7 @@ Similar to the `.nav-fill` example using a `<nav>`-based navigation.
<a class="nav-link active" aria-current="page" href="#">Active</a>
<a class="nav-link" href="#">Much longer nav link</a>
<a class="nav-link" href="#">Link</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</nav>

{{< /example >}}
Expand All @@ -238,7 +238,7 @@ If you need responsive nav variations, consider using a series of [flexbox utili
<a class="flex-sm-fill text-sm-center nav-link active" aria-current="page" href="#">Active</a>
<a class="flex-sm-fill text-sm-center nav-link" href="#">Longer nav link</a>
<a class="flex-sm-fill text-sm-center nav-link" href="#">Link</a>
<a class="flex-sm-fill text-sm-center nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="flex-sm-fill text-sm-center nav-link disabled">Disabled</a>
</nav>
{{< /example >}}

Expand Down Expand Up @@ -273,7 +273,7 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand All @@ -299,7 +299,7 @@ Add dropdown menus with a little extra HTML and the [dropdowns JavaScript plugin
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
{{< /example >}}
Expand Down
6 changes: 3 additions & 3 deletions site/content/docs/5.1/components/pagination.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ While the `.disabled` class uses `pointer-events: none` to _try_ to disable the
<nav aria-label="...">
<ul class="pagination">
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">Previous</a>
<a class="page-link">Previous</a>
</li>
<li class="page-item"><a class="page-link" href="#">1</a></li>
<li class="page-item active" aria-current="page">
Expand Down Expand Up @@ -128,7 +128,7 @@ Change the alignment of pagination components with [flexbox utilities]({{< docsr
<nav aria-label="Page navigation example">
<ul class="pagination justify-content-center">
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">Previous</a>
<a class="page-link">Previous</a>
</li>
<li class="page-item"><a class="page-link" href="#">1</a></li>
<li class="page-item"><a class="page-link" href="#">2</a></li>
Expand All @@ -144,7 +144,7 @@ Change the alignment of pagination components with [flexbox utilities]({{< docsr
<nav aria-label="Page navigation example">
<ul class="pagination justify-content-end">
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">Previous</a>
<a class="page-link">Previous</a>
</li>
<li class="page-item"><a class="page-link" href="#">1</a></li>
<li class="page-item"><a class="page-link" href="#">2</a></li>
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/examples/blog-rtl/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ <h2 class="blog-post-title">ميزة جديدة</h2>

<nav class="blog-pagination" aria-label="Pagination">
<a class="btn btn-outline-primary" href="#">تدوينات أقدم</a>
<a class="btn btn-outline-secondary disabled" href="#" tabindex="-1" aria-disabled="true">تدوينات أحدث</a>
<a class="btn btn-outline-secondary disabled">تدوينات أحدث</a>
</nav>

</div>
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/examples/blog/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ <h2 class="blog-post-title">New feature</h2>

<nav class="blog-pagination" aria-label="Pagination">
<a class="btn btn-outline-primary" href="#">Older</a>
<a class="btn btn-outline-secondary disabled" href="#" tabindex="-1" aria-disabled="true">Newer</a>
<a class="btn btn-outline-secondary disabled">Newer</a>
</nav>

</div>
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/examples/carousel-rtl/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
<a class="nav-link" href="#">حلقة الوصل</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">رابط غير مفعل</a>
<a class="nav-link disabled">رابط غير مفعل</a>
</li>
</ul>
<form class="d-flex">
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/5.1/examples/carousel/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
<a class="nav-link" href="#">Link</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">Disabled</a>
<a class="nav-link disabled">Disabled</a>
</li>
</ul>
<form class="d-flex">
Expand Down
10 changes: 5 additions & 5 deletions site/content/docs/5.1/examples/cheatsheet-rtl/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -1157,7 +1157,7 @@ <h3>التنقل</h3>
<a class="nav-link active" aria-current="page" href="#">نشط</a>
<a class="nav-link" href="#">رابط</a>
<a class="nav-link" href="#">رابط</a>
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">معطل</a>
<a class="nav-link disabled">معطل</a>
</nav>
{{< /example >}}

Expand Down Expand Up @@ -1194,7 +1194,7 @@ <h3>التنقل</h3>
<a class="nav-link" href="#">رابط</a>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">معطل</a>
<a class="nav-link disabled">معطل</a>
</li>
</ul>
{{< /example >}}
Expand Down Expand Up @@ -1237,7 +1237,7 @@ <h3>شريط التنقل</h3>
</ul>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">معطل</a>
<a class="nav-link disabled">معطل</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -1276,7 +1276,7 @@ <h3>شريط التنقل</h3>
</ul>
</li>
<li class="nav-item">
<a class="nav-link disabled" href="#" tabindex="-1" aria-disabled="true">معطل</a>
<a class="nav-link disabled">معطل</a>
</li>
</ul>
<form class="d-flex">
Expand Down Expand Up @@ -1332,7 +1332,7 @@ <h3>ترقيم الصفحات</h3>
<nav aria-label="مثال آخر لترقيم الصفحات">
<ul class="pagination pagination-lg flex-wrap">
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">السابق</a>
<a class="page-link">السابق</a>
</li>
<li class="page-item"><a class="page-link" href="#">1</a></li>
<li class="page-item active" aria-current="page">
Expand Down
Loading

0 comments on commit aa06dff

Please sign in to comment.