Convert popovers to CSS variables

2 files changed, 56 insertions, 15 deletions

diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index d29fefa7d6..31a5063a7c 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -243,6 +243,17 @@
   --bs-tooltip-bg: var(--bs-primary);
 }
 
+// scss-docs-start custom-popovers
+.custom-popover {
+  --bs-popover-max-width: 200px;
+  --bs-popover-border-color: var(--bs-primary);
+  --bs-popover-header-bg: var(--bs-primary);
+  --bs-popover-header-color: var(--bs-white);
+  --bs-popover-body-padding-x: 1rem;
+  --bs-popover-body-padding-y: .5rem;
+}
+// scss-docs-end custom-popovers
+
 // Scrollspy demo on fixed height div
 .scrollspy-example {
   position: relative;
diff --git a/site/content/docs/5.1/components/popovers.md b/site/content/docs/5.1/components/popovers.md
index 0acc76a0a2..90132cf199 100644
--- a/site/content/docs/5.1/components/popovers.md
+++ b/site/content/docs/5.1/components/popovers.md
@@ -10,7 +10,7 @@ toc: true
 
 Things to know when using the popover plugin:
 
-- Popovers rely on the 3rd party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before bootstrap.js or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper in order for popovers to work!
+- Popovers rely on the third party library [Popper](https://popper.js.org/) for positioning. You must include [popper.min.js]({{< param "cdn.popper" >}}) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper.
 - Popovers require the [tooltip plugin]({{< docsref "/components/tooltips" >}}) as a dependency.
 - Popovers are opt-in for performance reasons, so **you must initialize them yourself**.
 - Zero-length `title` and `content` values will never show a popover.
@@ -31,9 +31,11 @@ Things to know when using the popover plugin:
 
 Keep reading to see how popovers work with some examples.
 
-## Example: Enable popovers everywhere
+## Examples
 
-One way to initialize all popovers on a page would be to select them by their `data-bs-toggle` attribute:
+### Enable popovers
+
+As mentioned above, you must initialize popovers before they can be used. One way to initialize all popovers on a page would be to select them by their `data-bs-toggle` attribute, like so:
 
 ```js
 var popoverTriggerList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
@@ -42,17 +44,9 @@ var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
 })
 ```
 
-## Example: Using the `container` option
-
-When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead.
-
-```js
-var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
-  container: 'body'
-})
-```
+### Live demo
 
-## Example
+We use JavaScript similar to the snippet above to render the following live popover. Titles are set via `title` attribute and body content is set via `data-bs-content`.
 
 {{< example >}}
 <button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
@@ -60,7 +54,7 @@ var popover = new bootstrap.Popover(document.querySelector('.example-popover'),
 
 ### Four directions
 
-Four options are available: top, right, bottom, and left aligned. Directions are mirrored when using Bootstrap in RTL.
+Four options are available: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL. Set `data-bs-placement` to change the direction.
 
 {{< example >}}
 <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
@@ -77,6 +71,34 @@ Four options are available: top, right, bottom, and left aligned. Directions are
 </button>
 {{< /example >}}
 
+### Custom `container`
+
+When you have some styles on a parent element that interfere with a popover, you'll want to specify a custom `container` so that the popover's HTML appears within that element instead. This is common in responsive tables, input groups, and the like.
+
+```js
+var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
+  container: 'body'
+})
+```
+
+### Custom popovers
+
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+You can customize the appearance of popovers using [CSS variables](#variables). We set a custom class with `data-bs-custom-class="custom-popover"` to scope our custom appearance and use it to override some of the local CSS variables.
+
+{{< scss-docs name="custom-popovers" file="site/assets/scss/_component-examples.scss" >}}
+
+{{< example class="custom-popover-demo" >}}
+<button type="button" class="btn btn-secondary"
+        data-bs-toggle="popover" data-bs-placement="right"
+        data-bs-custom-class="custom-popover"
+        title="Custom popover"
+        data-bs-content="This popover is themed via CSS variables.">
+  Custom popover
+</button>
+{{< /example >}}
+
 ### Dismiss on next click
 
 Use the `focus` trigger to dismiss popovers on the user's next click of a different element than the toggle element.
@@ -109,10 +131,18 @@ For disabled popover triggers, you may also prefer `data-bs-trigger="hover focus
 </span>
 {{< /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, popovers now use local CSS variables on `.popover` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
+
+{{< scss-docs name="popover-css-vars" file="scss/_popover.scss" >}}
+
+### Sass variables
+
 {{< scss-docs name="popover-variables" file="scss/_variables.scss" >}}
 
 ## Usage