Better docs for table-responsive classes (#24438)

1 files changed, 77 insertions, 22 deletions

diff --git a/docs/4.0/content/tables.md b/docs/4.0/content/tables.md
index 59bdb6373c..d4506c2c9f 100644
--- a/docs/4.0/content/tables.md
+++ b/docs/4.0/content/tables.md
@@ -579,11 +579,48 @@ Regular table background variants are not available with the dark table, however
 {% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %}
 {{ callout-include | markdownify }}
 
-## Responsive tables
 
-Create responsive tables by adding `.table-responsive{-sm|-md|-lg|-xl}` to any `.table` to make them scroll horizontally at each `max-width` breakpoint 575px, 767px, 991px, and 1199px, respectively.
+## Captions
 
-For responsive tables that always scroll horizontally when the table is wider than its container, add the `.table-responsive` class on `.table`.
+A `<caption>` functions like a heading for a table. It helps users with screen readers to find a table and understand what it’s about and decide if they want to read it.
+
+{% example html %}
+<table class="table">
+  <caption>List of users</caption>
+  <thead>
+    <tr>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">1</th>
+      <td>Mark</td>
+      <td>Otto</td>
+      <td>@mdo</td>
+    </tr>
+    <tr>
+      <th scope="row">2</th>
+      <td>Jacob</td>
+      <td>Thornton</td>
+      <td>@fat</td>
+    </tr>
+    <tr>
+      <th scope="row">3</th>
+      <td>Larry</td>
+      <td>the Bird</td>
+      <td>@twitter</td>
+    </tr>
+  </tbody>
+</table>
+{% endexample %}
+
+## Responsive tables
+
+Responsive tables allow tables to be scrolled horizontally with ease. Make any table responsive across all viewports by adding `.table-responsive` class on `.table`. Or, pick a maximum breakpoint with which to have a responsive table up to by adding `.table-responsive{-sm|-md|-lg|-xl}`.
 
 {% callout warning %}
 #### Vertical clipping/truncation
@@ -591,6 +628,8 @@ For responsive tables that always scroll horizontally when the table is wider th
 Responsive tables make use of `overflow-y: hidden`, which clips off any content that goes beyond the bottom or top edges of the table. In particular, this can clip off dropdown menus and other third-party widgets.
 {% endcallout %}
 
+### Always responsive
+
 <div class="bd-example">
   <table class="table table-responsive">
     <thead>
@@ -697,41 +736,57 @@ Responsive tables make use of `overflow-y: hidden`, which clips off any content
 </table>
 {% endhighlight %}
 
+### Breakpoint specific
 
-## Captions
+Use `.table-responsive{-sm|-md|-lg|-xl}` as needed to create responsive tables up to a particular breakpoint. From that breakpoint and up, the table will behave normally and not scroll horizontally.
 
-A `<caption>` functions like a heading for a table. It helps users with screen readers to find a table and understand what it’s about and decide if they want to read it.
-
-{% example html %}
-<table class="table">
-  <caption>List of users</caption>
+<div class="bd-example">
+{% for bp in site.data.breakpoints %}{% unless bp.breakpoint == "xs" %}
+<table class="table table-responsive{{ bp.abbr }}">
   <thead>
     <tr>
       <th scope="col">#</th>
-      <th scope="col">First Name</th>
-      <th scope="col">Last Name</th>
-      <th scope="col">Username</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
+      <th scope="col">Table heading</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <th scope="row">1</th>
-      <td>Mark</td>
-      <td>Otto</td>
-      <td>@mdo</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
     <tr>
       <th scope="row">2</th>
-      <td>Jacob</td>
-      <td>Thornton</td>
-      <td>@fat</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
     <tr>
       <th scope="row">3</th>
-      <td>Larry</td>
-      <td>the Bird</td>
-      <td>@twitter</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
+      <td>Table cell</td>
     </tr>
   </tbody>
 </table>
-{% endexample %}
+{% endunless %}{% endfor %}
+</div>
+
+{% highlight html %}
+{% for bp in site.data.breakpoints %}{% unless bp.breakpoint == "xs" %}
+<table class="table table-responsive{{ bp.abbr }}">
+  ...
+</table>
+{% endunless %}{% endfor %}
+{% endhighlight %}