v4.1: Add .dropdown-item-text (#22965)

* Add .dropdown-item-text class

* Add example of plain text within a .dropdown-menu, too

* reorganize, simple/clearer headings

1 files changed, 62 insertions, 33 deletions

diff --git a/docs/4.0/components/dropdowns.md b/docs/4.0/components/dropdowns.md
index b4c70478e..926899d1d 100644
--- a/docs/4.0/components/dropdowns.md
+++ b/docs/4.0/components/dropdowns.md
@@ -26,7 +26,7 @@ However, Bootstrap does add built-in support for most standard keyboard menu int
 
 Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Dropdowns can be triggered from `<a>` or `<button>` elements to better fit your potential needs.
 
-### Single button dropdowns
+### Single button
 
 Any single `.btn` can be turned into a dropdown toggle with some markup changes. Here's how you can put them to work with either `<button>` elements:
 
@@ -140,7 +140,7 @@ The best part is you can do this with any button variant, too:
 </div>
 {% endhighlight %}
 
-### Split button dropdowns
+### Split button
 
 Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` for proper spacing around the dropdown caret.
 
@@ -349,7 +349,9 @@ Button dropdowns work with buttons of all sizes, including default and split dro
 </div>
 {% endhighlight %}
 
-## Dropup variation
+## Directions
+
+### Dropup
 
 Trigger dropdown menus above elements by adding `.dropup` to the parent element.
 
@@ -409,7 +411,7 @@ Trigger dropdown menus above elements by adding `.dropup` to the parent element.
 </div>
 {% endhighlight %}
 
-## Dropright variation
+### Dropright
 
 Trigger dropdown menus at the right of the elements by adding `.dropright` to the parent element.
 
@@ -469,7 +471,7 @@ Trigger dropdown menus at the right of the elements by adding `.dropright` to th
 </div>
 {% endhighlight %}
 
-## Dropleft variation
+### Dropleft
 
 Trigger dropdown menus at the left of the elements by adding `.dropleft` to the parent element.
 
@@ -533,7 +535,6 @@ Trigger dropdown menus at the left of the elements by adding `.dropleft` to the
 </div>
 {% endhighlight %}
 
-
 ## Menu items
 
 Historically dropdown menu contents *had* to be links, but that's no longer the case with v4. Now you can optionally use `<button>` elements in your dropdowns instead of just `<a>`s.
@@ -551,6 +552,41 @@ Historically dropdown menu contents *had* to be links, but that's no longer the
 </div>
 {% endexample %}
 
+You can also create non-interactive dropdown items with `.dropdown-item-text`. Feel free to style further with custom CSS or text utilities.
+
+{% example html %}
+<div class="dropdown-menu">
+  <span class="dropdown-item-text">Dropdown item text</span>
+  <a class="dropdown-item" href="#">Action</a>
+  <a class="dropdown-item" href="#">Another action</a>
+  <a class="dropdown-item" href="#">Something else here</a>
+</div>
+{% endexample %}
+
+### Active
+
+Add `.active` to items in the dropdown to **style them as active**.
+
+{% example html %}
+<div class="dropdown-menu">
+  <a class="dropdown-item" href="#">Regular link</a>
+  <a class="dropdown-item active" href="#">Active link</a>
+  <a class="dropdown-item" href="#">Another link</a>
+</div>
+{% endexample %}
+
+### Disabled
+
+Add `.disabled` to items in the dropdown to **style them as disabled**.
+
+{% example html %}
+<div class="dropdown-menu">
+  <a class="dropdown-item" href="#">Regular link</a>
+  <a class="dropdown-item disabled" href="#">Disabled link</a>
+  <a class="dropdown-item" href="#">Another link</a>
+</div>
+{% endexample %}
+
 ## Menu alignment
 
 By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. Add `.dropdown-menu-right` to a `.dropdown-menu` to right align the dropdown menu.
@@ -572,7 +608,9 @@ By default, a dropdown menu is automatically positioned 100% from the top and al
 </div>
 {% endexample %}
 
-## Menu headers
+## Menu content
+
+### Headers
 
 Add a header to label sections of actions in any dropdown menu.
 
@@ -584,7 +622,7 @@ Add a header to label sections of actions in any dropdown menu.
 </div>
 {% endexample %}
 
-## Menu dividers
+### Dividers
 
 Separate groups of related menu items with a divider.
 
@@ -598,7 +636,22 @@ Separate groups of related menu items with a divider.
 </div>
 {% endexample %}
 
-## Menu forms
+### Text
+
+Place any freeform text within a dropdown menu with text and use [spacing utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/). Note that you'll likely need additional sizing styles to constrain the menu width.
+
+{% example html %}
+<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
+  <p>
+    Some example text that's free-flowing within the dropdown menu.
+  </p>
+  <p class="mb-0">
+    And this is more example text.
+  </p>
+</div>
+{% endexample %}
+
+### Forms
 
 Put a form within a dropdown menu, or make it into a dropdown menu, and use [margin or padding utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/) to give it the negative space you require.
 
@@ -647,30 +700,6 @@ Put a form within a dropdown menu, or make it into a dropdown menu, and use [mar
 </form>
 {% endexample %}
 
-## Active menu items
-
-Add `.active` to items in the dropdown to **style them as active**.
-
-{% example html %}
-<div class="dropdown-menu">
-  <a class="dropdown-item" href="#">Regular link</a>
-  <a class="dropdown-item active" href="#">Active link</a>
-  <a class="dropdown-item" href="#">Another link</a>
-</div>
-{% endexample %}
-
-## Disabled menu items
-
-Add `.disabled` to items in the dropdown to **style them as disabled**.
-
-{% example html %}
-<div class="dropdown-menu">
-  <a class="dropdown-item" href="#">Regular link</a>
-  <a class="dropdown-item disabled" href="#">Disabled link</a>
-  <a class="dropdown-item" href="#">Another link</a>
-</div>
-{% endexample %}
-
 ## Dropdown options
 
 Use `data-offset` or `data-reference` to change the location of the dropdown.