Convert dropdowns to CSS variables

3 files changed, 79 insertions, 65 deletions

diff --git a/scss/_dropdown.scss b/scss/_dropdown.scss
index adc114327d..7476acd85d 100644
--- a/scss/_dropdown.scss
+++ b/scss/_dropdown.scss
@@ -15,26 +15,51 @@
 
 // The dropdown menu
 .dropdown-menu {
+  // scss-docs-start dropdown-css-vars
+  --#{$variable-prefix}dropdown-min-width: #{$dropdown-min-width};
+  --#{$variable-prefix}dropdown-padding: #{$dropdown-padding-y $dropdown-padding-x};
+  --#{$variable-prefix}dropdown-spacer: #{$dropdown-spacer};
+  @include rfs($dropdown-font-size, --#{$variable-prefix}dropdown-font-size);
+  --#{$variable-prefix}dropdown-color: #{$dropdown-color}; // stylelint-disable-line custom-property-empty-line-before
+  --#{$variable-prefix}dropdown-bg: #{$dropdown-bg};
+  --#{$variable-prefix}dropdown-border-color: #{$dropdown-border-color};
+  --#{$variable-prefix}dropdown-border-radius: #{$dropdown-border-radius};
+  --#{$variable-prefix}dropdown-border-width: #{$dropdown-border-width};
+  --#{$variable-prefix}dropdown-inner-border: #{$dropdown-inner-border-radius};
+  --#{$variable-prefix}dropdown-divider-bg: #{$dropdown-divider-bg};
+  --#{$variable-prefix}dropdown-divider-margin-y: #{$dropdown-divider-margin-y};
+  --#{$variable-prefix}dropdown-shadow: #{$dropdown-box-shadow};
+  --#{$variable-prefix}dropdown-link-color: #{$dropdown-link-color};
+  --#{$variable-prefix}dropdown-link-hover-color: #{$dropdown-link-hover-color};
+  --#{$variable-prefix}dropdown-link-hover-bg: #{$dropdown-link-hover-bg};
+  --#{$variable-prefix}dropdown-link-active-color: #{$dropdown-link-active-color};
+  --#{$variable-prefix}dropdown-link-active-bg: #{$dropdown-link-active-bg};
+  --#{$variable-prefix}dropdown-link-disabled-color: #{$dropdown-link-disabled-color};
+  --#{$variable-prefix}dropdown-item-padding: #{$dropdown-item-padding-y $dropdown-item-padding-x};
+  --#{$variable-prefix}dropdown-header-color: #{$dropdown-header-color};
+  --#{$variable-prefix}dropdown-header-padding: #{$dropdown-header-padding};
+  // scss-docs-end dropdown-css-vars
+
   position: absolute;
   z-index: $zindex-dropdown;
   display: none; // none by default, but block on "open" of the menu
-  min-width: $dropdown-min-width;
-  padding: $dropdown-padding-y $dropdown-padding-x;
+  min-width: var(--#{$variable-prefix}dropdown-min-width);
+  padding: var(--#{$variable-prefix}dropdown-padding);
   margin: 0; // Override default margin of ul
   @include font-size($dropdown-font-size);
-  color: $dropdown-color;
+  color: var(--#{$variable-prefix}dropdown-color);
   text-align: left; // Ensures proper alignment if parent has it changed (e.g., modal footer)
   list-style: none;
-  background-color: $dropdown-bg;
+  background-color: var(--#{$variable-prefix}dropdown-bg);
   background-clip: padding-box;
-  border: $dropdown-border-width solid $dropdown-border-color;
-  @include border-radius($dropdown-border-radius);
-  @include box-shadow($dropdown-box-shadow);
+  border: var(--#{$variable-prefix}dropdown-border-width) solid var(--#{$variable-prefix}dropdown-border-color);
+  @include border-radius(var(--#{$variable-prefix}dropdown-border-radius));
+  @include box-shadow(var(--#{$variable-prefix}dropdown-shadow));
 
   &[data-bs-popper] {
     top: 100%;
     left: 0;
-    margin-top: $dropdown-spacer;
+    margin-top: var(--#{$variable-prefix}dropdown-spacer);
   }
 }
 
@@ -74,7 +99,7 @@
     top: auto;
     bottom: 100%;
     margin-top: 0;
-    margin-bottom: $dropdown-spacer;
+    margin-bottom: var(--#{$variable-prefix}dropdown-spacer);
   }
 
   .dropdown-toggle {
@@ -88,7 +113,7 @@
     right: auto;
     left: 100%;
     margin-top: 0;
-    margin-left: $dropdown-spacer;
+    margin-left: var(--#{$variable-prefix}dropdown-spacer);
   }
 
   .dropdown-toggle {
@@ -105,7 +130,7 @@
     right: 100%;
     left: auto;
     margin-top: 0;
-    margin-right: $dropdown-spacer;
+    margin-right: var(--#{$variable-prefix}dropdown-spacer);
   }
 
   .dropdown-toggle {
@@ -122,7 +147,7 @@
   height: 0;
   margin: $dropdown-divider-margin-y 0;
   overflow: hidden;
-  border-top: 1px solid $dropdown-divider-bg;
+  border-top: 1px solid var(--#{$variable-prefix}dropdown-divider-bg);
 }
 
 // Links, buttons, and more within the dropdown menu
@@ -131,10 +156,10 @@
 .dropdown-item {
   display: block;
   width: 100%; // For `<button>`s
-  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
+  padding: var(--#{$variable-prefix}dropdown-item-padding);
   clear: both;
   font-weight: $font-weight-normal;
-  color: $dropdown-link-color;
+  color: var(--#{$variable-prefix}dropdown-link-color);
   text-align: inherit; // For `<button>`s
   text-decoration: if($link-decoration == none, null, none);
   white-space: nowrap; // prevent links from randomly breaking onto new lines
@@ -155,21 +180,21 @@
 
   &:hover,
   &:focus {
-    color: $dropdown-link-hover-color;
+    color: var(--#{$variable-prefix}dropdown-link-hover-color);
     text-decoration: if($link-hover-decoration == underline, none, null);
-    @include gradient-bg($dropdown-link-hover-bg);
+    @include gradient-bg(var(--#{$variable-prefix}dropdown-link-hover-bg));
   }
 
   &.active,
   &:active {
-    color: $dropdown-link-active-color;
+    color: var(--#{$variable-prefix}dropdown-link-active-color);
     text-decoration: none;
-    @include gradient-bg($dropdown-link-active-bg);
+    @include gradient-bg(var(--#{$variable-prefix}dropdown-link-active-bg));
   }
 
   &.disabled,
   &:disabled {
-    color: $dropdown-link-disabled-color;
+    color: var(--#{$variable-prefix}dropdown-link-disabled-color);
     pointer-events: none;
     background-color: transparent;
     // Remove CSS gradients if they're enabled
@@ -184,57 +209,34 @@
 // Dropdown section headers
 .dropdown-header {
   display: block;
-  padding: $dropdown-header-padding;
+  padding: var(--#{$variable-prefix}dropdown-header-padding);
   margin-bottom: 0; // for use with heading elements
   @include font-size($font-size-sm);
-  color: $dropdown-header-color;
+  color: var(--#{$variable-prefix}dropdown-header-color);
   white-space: nowrap; // as with > li > a
 }
 
 // Dropdown text
 .dropdown-item-text {
   display: block;
-  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
-  color: $dropdown-link-color;
+  padding: var(--#{$variable-prefix}dropdown-item-padding);
+  color: var(--#{$variable-prefix}dropdown-link-color);
 }
 
 // Dark dropdowns
 .dropdown-menu-dark {
-  color: $dropdown-dark-color;
-  background-color: $dropdown-dark-bg;
-  border-color: $dropdown-dark-border-color;
-  @include box-shadow($dropdown-dark-box-shadow);
-
-  .dropdown-item {
-    color: $dropdown-dark-link-color;
-
-    &:hover,
-    &:focus {
-      color: $dropdown-dark-link-hover-color;
-      @include gradient-bg($dropdown-dark-link-hover-bg);
-    }
-
-    &.active,
-    &:active {
-      color: $dropdown-dark-link-active-color;
-      @include gradient-bg($dropdown-dark-link-active-bg);
-    }
-
-    &.disabled,
-    &:disabled {
-      color: $dropdown-dark-link-disabled-color;
-    }
-  }
-
-  .dropdown-divider {
-    border-color: $dropdown-dark-divider-bg;
-  }
-
-  .dropdown-item-text {
-    color: $dropdown-dark-link-color;
-  }
-
-  .dropdown-header {
-    color: $dropdown-dark-header-color;
-  }
+  // scss-docs-start dropdown-dark-css-vars
+  --#{$variable-prefix}dropdown-color: #{$dropdown-dark-color};
+  --#{$variable-prefix}dropdown-bg: #{$dropdown-dark-bg};
+  --#{$variable-prefix}dropdown-border-color: #{$dropdown-dark-border-color};
+  --#{$variable-prefix}dropdown-shadow: #{$dropdown-dark-box-shadow};
+  --#{$variable-prefix}dropdown-link-color: #{$dropdown-dark-link-color};
+  --#{$variable-prefix}dropdown-link-hover-color: #{$dropdown-dark-link-hover-color};
+  --#{$variable-prefix}dropdown-divider-bg: #{$dropdown-dark-divider-bg};
+  --#{$variable-prefix}dropdown-link-hover-bg: #{$dropdown-dark-link-hover-bg};
+  --#{$variable-prefix}dropdown-link-active-color: #{$dropdown-dark-link-active-color};
+  --#{$variable-prefix}dropdown-link-active-bg: #{$dropdown-dark-link-active-bg};
+  --#{$variable-prefix}dropdown-link-disabled-color: #{$dropdown-dark-link-disabled-color};
+  --#{$variable-prefix}dropdown-header-color: #{$dropdown-dark-header-color};
+  // scss-docs-end dropdown-dark-css-vars
 }
diff --git a/site/content/docs/5.1/components/dropdowns.md b/site/content/docs/5.1/components/dropdowns.md
index f5dcff4ccd..c98dd778e0 100644
--- a/site/content/docs/5.1/components/dropdowns.md
+++ b/site/content/docs/5.1/components/dropdowns.md
@@ -953,10 +953,22 @@ By default, the dropdown menu is closed when clicking inside or outside the drop
 </div>
 {{< /example >}}
 
-## Sass
+## CSS
 
 ### Variables
 
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+As part of Bootstrap's evolving CSS variables approach, dropdowns now use local CSS variables on `.dropdown-menu` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+{{< scss-docs name="dropdown-css-vars" file="scss/_dropdown.scss" >}}
+
+Customization through CSS variables can be seen on the `.dropdown-menu-dark` class where we override specific values without adding duplicate CSS selectors.
+
+{{< scss-docs name="dropdown-dark-css-vars" file="scss/_dropdown.scss" >}}
+
+### Sass variables
+
 Variables for all dropdowns:
 
 {{< scss-docs name="dropdown-variables" file="scss/_variables.scss" >}}
diff --git a/site/content/docs/5.1/examples/dropdowns/index.html b/site/content/docs/5.1/examples/dropdowns/index.html
index 861e816670..518adb568d 100644
--- a/site/content/docs/5.1/examples/dropdowns/index.html
+++ b/site/content/docs/5.1/examples/dropdowns/index.html
@@ -80,7 +80,7 @@ body_class: ""
   </symbol>
 </svg>
 
-<div class="d-flex gap-5 justify-content-center" id="dropdownMacos">
+<div class="d-flex gap-5 justify-content-center dropdown" id="dropdownMacos">
   <ul class="dropdown-menu dropdown-menu-macos mx-0 shadow" style="width: 220px;">
     <li><a class="dropdown-item active" href="#">Action</a></li>
     <li><a class="dropdown-item" href="#">Another action</a></li>
@@ -100,7 +100,7 @@ body_class: ""
 <div class="b-example-divider"></div>
 
 
-<div class="d-flex gap-5 justify-content-center" id="dropdownFilter">
+<div class="d-flex gap-5 justify-content-center dropdown" id="dropdownFilter">
   <div class="dropdown-menu pt-0 mx-0 rounded-3 shadow overflow-hidden" style="width: 280px;">
     <form class="p-2 mb-2 bg-light border-bottom">
       <input type="search" class="form-control" autocomplete="false" placeholder="Type to filter...">
@@ -152,7 +152,7 @@ body_class: ""
 
 <div class="b-example-divider"></div>
 
-<div class="d-flex gap-5 justify-content-center" id="dropdownIcons">
+<div class="d-flex gap-5 justify-content-center dropdown" id="dropdownIcons">
   <ul class="dropdown-menu mx-0 shadow" style="width: 220px;">
     <li>
       <a class="dropdown-item d-flex gap-2 align-items-center" href="#">
@@ -316,7 +316,7 @@ body_class: ""
 
 <div class="b-example-divider"></div>
 
-<div class="dropdown-menu d-flex align-items-stretch p-3 rounded-3 shadow-lg" style="width: 600px" id="dropdownMega">
+<div class="dropdown-menu d-flex align-items-stretch p-3 rounded-3 shadow-lg dropdown" style="width: 600px" id="dropdownMega">
   <nav class="d-grid gap-2 col-8">
     <a href="#" class="btn btn-hover-light d-flex align-items-center gap-3 py-2 px-3 lh-sm">
       <svg class="bi" width="32" height="32"><use xlink:href="#image-fill"/></svg>