From cc9da054bbc9aafacd86c16407a0b0da37bc8306 Mon Sep 17 00:00:00 2001 From: Pierluigi Lenoci Date: Fri, 24 Apr 2026 17:51:39 +0200 Subject: [PATCH] docs: explain why tooltips, popovers, toasts, and carousels are opt-in Expand the "opt-in for performance reasons" notes in the Tooltip, Popover, Toast, and Carousel docs to explain what those performance reasons actually are: each instance creates Popper positioning or event listeners that would add unnecessary overhead if auto-initialized on every page load. Fixes #29378 Signed-off-by: Pierluigi Lenoci --- site/src/content/docs/components/carousel.mdx | 2 +- site/src/content/docs/components/popovers.mdx | 2 +- site/src/content/docs/components/toasts.mdx | 2 +- site/src/content/docs/components/tooltips.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/site/src/content/docs/components/carousel.mdx b/site/src/content/docs/components/carousel.mdx index 397f7da876c9..a5338184ca2b 100644 --- a/site/src/content/docs/components/carousel.mdx +++ b/site/src/content/docs/components/carousel.mdx @@ -8,7 +8,7 @@ toc: true - The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. -- For performance reasons, **carousels must be manually initialized** using the [carousel constructor method](#methods). Without initialization, some of the event listeners (specifically, the events needed touch/swipe support) will not be registered until a user has explicitly activated a control or indicator. +- For performance reasons, **carousels must be manually initialized** using the [carousel constructor method](#methods). Auto-initializing every carousel on page load would register touch, swipe, scroll, and resize event listeners even for carousels that may not be visible or interactive yet. Without explicit initialization, some of these event listeners (specifically, the events needed for touch/swipe support) will not be registered until a user has explicitly activated a control or indicator. The only exception are [autoplaying carousels](#autoplaying-carousels) with the `data-bs-ride="carousel"` attribute as these are initialized automatically on page load. If you’re using autoplaying carousels with the data attribute, **don’t explicitly initialize the same carousels with the constructor method.** diff --git a/site/src/content/docs/components/popovers.mdx b/site/src/content/docs/components/popovers.mdx index d08f67b5dd0b..23523b3eaa2c 100644 --- a/site/src/content/docs/components/popovers.mdx +++ b/site/src/content/docs/components/popovers.mdx @@ -10,7 +10,7 @@ Things to know when using the popover plugin: - Popovers rely on the third party library [Popper](https://popper.js.org/docs/v2/) for positioning. You must include [popper.min.js]([[config:cdn.popper]]) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper. - Popovers require the [popover plugin]([[docsref:/components/popovers]]) as a dependency. -- Popovers are opt-in for performance reasons, so **you must initialize them yourself**. +- Popovers are opt-in for performance reasons, so **you must initialize them yourself**. Like tooltips, each popover creates a [Popper](https://popper.js.org/docs/v2/) instance that tracks scroll and resize events. Auto-initializing every popover on page load would add unnecessary overhead on pages where popovers are not used or where only a few elements need them. - Zero-length `title` and `content` values will never show a popover. - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). - Triggering popovers on hidden elements will not work. diff --git a/site/src/content/docs/components/toasts.mdx b/site/src/content/docs/components/toasts.mdx index cb6afb9d6f36..ec64e2a3954a 100644 --- a/site/src/content/docs/components/toasts.mdx +++ b/site/src/content/docs/components/toasts.mdx @@ -10,7 +10,7 @@ Toasts are lightweight notifications designed to mimic the push notifications th Things to know when using the toast plugin: -- Toasts are opt-in for performance reasons, so **you must initialize them yourself**. +- Toasts are opt-in for performance reasons, so **you must initialize them yourself**. Auto-initializing every toast on page load would register timers and event listeners even when no toasts are visible, adding unnecessary overhead on pages that create toasts dynamically or only in response to user actions. - Toasts will automatically hide if you do not specify `autohide: false`. diff --git a/site/src/content/docs/components/tooltips.mdx b/site/src/content/docs/components/tooltips.mdx index 32fa16d15e8a..1b62660ecf07 100644 --- a/site/src/content/docs/components/tooltips.mdx +++ b/site/src/content/docs/components/tooltips.mdx @@ -9,7 +9,7 @@ toc: true Things to know when using the tooltip plugin: - Tooltips rely on the third party library [Popper](https://popper.js.org/docs/v2/) for positioning. You must include [popper.min.js]([[config:cdn.popper]]) before `bootstrap.js`, or use one `bootstrap.bundle.min.js` which contains Popper. -- Tooltips are opt-in for performance reasons, so **you must initialize them yourself**. +- Tooltips are opt-in for performance reasons, so **you must initialize them yourself**. Unlike most other Bootstrap components, tooltips and popovers are not automatically initialized because each one creates a [Popper](https://popper.js.org/docs/v2/) instance that tracks scroll and resize events. Auto-initializing every tooltip on page load would add unnecessary overhead on pages where tooltips are not used or where only a few elements need them. - Tooltips with zero-length titles are never displayed. - Specify `container: 'body'` to avoid rendering problems in more complex components (like our input groups, button groups, etc). - Triggering tooltips on hidden elements will not work.