Bootstrap

Common errors

• Uncaught TypeError: Cannot read properties of undefined (reading 'fn') at bootstrap.min.js

  cause This error typically indicates that jQuery is missing or not loaded before Bootstrap's JavaScript (common in Bootstrap 4 projects). For Bootstrap 5, it might mean an older version of Bootstrap is being used or there's a conflict with a legacy script expecting jQuery.
  fix For Bootstrap 5, ensure jQuery is *not* being used or loaded with Bootstrap's JavaScript. If migrating from Bootstrap 4, remove jQuery dependencies and update JavaScript initialization to Bootstrap 5's vanilla JS API.

• Error: Bootstrap's dropdowns require Popper (https://popper.js.org)

  cause Bootstrap's JavaScript components (Dropdown, Tooltip, Popover, Modal) rely on Popper.js for correct positioning and functionality, but `@popperjs/core` is either not installed or not correctly integrated into the build.
  fix Install the peer dependency: `npm install @popperjs/core`. Ensure your bundler includes it, or if using direct script tags, include `popper.min.js` before `bootstrap.min.js`.

• Error: Dart Sass 1.65.0 deprecated passing a percentage unit to the global `abs()` function. This will be an error in Dart Sass 2.0.0. Consider using `math.abs()` instead.

  cause Compiling Bootstrap's Sass files with Dart Sass v1.65.0 or higher triggers a deprecation warning related to the `abs()` function usage.
  fix While Bootstrap 5.3.2 and later addressed this internally for its own compilation, custom Sass code or older Bootstrap versions might still show this. Update to the latest Bootstrap 5.x.x, and ensure your custom Sass code adheres to modern Dart Sass practices, potentially using `math.abs()` if applicable.

• Bootstrap component (e.g., Modal, Dropdown) not working with `data-bs-*` attributes.

  cause The Bootstrap JavaScript bundle (or individual component JavaScript) was not loaded or initialized correctly on the page, or there's a conflict with other JavaScript.
  fix Verify that `bootstrap.min.js` (or `import 'bootstrap'`) is included and executed. Ensure your JavaScript is loaded *after* the DOM content is available (`DOMContentLoaded` event listener). Check the browser console for JavaScript errors that might prevent Bootstrap from initializing.

Warnings

• breaking Bootstrap 5 removed its dependency on jQuery. All JavaScript components now operate on pure JavaScript. Migrating from Bootstrap 4 requires rewriting any custom JavaScript that relied on jQuery for component initialization or manipulation.
  Fix: Review the official Bootstrap 5 migration guide. Update JavaScript to use native DOM methods and Bootstrap's new JavaScript API (e.g., `new Modal(element)` instead of `$(element).modal()`).
• gotcha Missing `@popperjs/core` peer dependency will cause Bootstrap JavaScript components like tooltips, popovers, dropdowns, and modals to fail or throw errors related to positioning.
  Fix: Install `@popperjs/core`: `npm install @popperjs/core` or `yarn add @popperjs/core`.
• deprecated Passing percentage units to the global `abs()` function in Sass is deprecated with Dart Sass v1.65.0 onwards, leading to deprecation warnings during compilation. Bootstrap internally addressed this, but custom Sass setups might still encounter it.
  Fix: Update Dart Sass to a newer version that correctly handles this or adjust custom Sass functions to avoid passing percentage units to `abs()` directly. Bootstrap v6 aims to drop `node-sass` support, favoring Dart Sass.
• gotcha The Bootstrap Sass variable `$color-mode-type` for managing dark mode compilation was re-evaluated. If you were manually importing `_variables-dark.scss`, keep doing so as this pattern is expected for v6. Bootstrap 5.3.3 fixed an issue where `_variables.scss` *wasn't* automatically importing `_variables-dark.scss`, which previously caused breaking changes in Sass builds.
  Fix: If experiencing color mode issues with custom Sass, ensure your Sass setup correctly handles `_variables.scss` and `_variables-dark.scss`. For future compatibility (v6), explicit import of `_variables-dark.scss` might be required for advanced custom dark mode setups.
• gotcha Changes to default dark mode colors (e.g., `$gray-500` replaced with `$gray-300` for body text) in v5.3.1 might affect existing custom dark mode themes, potentially requiring adjustments to maintain desired contrast and aesthetics.
  Fix: Review your custom dark mode styling and adjust Sass variables or CSS rules as needed to align with the new default color contrast ratios.

Install

• npm install bootstrap npm
• yarn add bootstrap yarn
• pnpm add bootstrap pnpm

Imports

• CSS

  import 'bootstrap/dist/css/bootstrap.min.css';

  For styling; import in your main JavaScript or TypeScript entry file, or link via HTML. For custom Sass builds, import `bootstrap/scss/bootstrap.scss`.
• Modal, Dropdown, Tooltip, Popover (JavaScript components)
  wrong:

  const { Modal } = require('bootstrap');

  correct:

  import { Modal, Dropdown, Tooltip, Popover } from 'bootstrap';

  Bootstrap 5 primarily uses ES Modules. Named imports are preferred for individual components. The CommonJS `require` syntax is generally discouraged in modern setups. Ensure `@popperjs/core` is installed for these components to work correctly.
• Full Bundle JavaScript
  wrong:

  import * as bootstrap from 'bootstrap';

  correct:

  import 'bootstrap';

  Imports the full Bootstrap JavaScript bundle, attaching components to the global `window.bootstrap` object. While convenient, it leads to larger bundle sizes. Prefer named imports for specific components to optimize.
• TypeScript Types

  import type { ModalOptions } from 'bootstrap';

  Bootstrap ships with its own TypeScript declaration files, allowing type-safe usage of component options and methods.

Quickstart

Demonstrates how to import and initialize Bootstrap's JavaScript components, specifically a Modal and a Tooltip, after the DOM has loaded.

import { Modal, Tooltip } from 'bootstrap';

// Ensure DOM is fully loaded before initializing components
document.addEventListener('DOMContentLoaded', () => {
  // Example: Initialize a Modal component
  const myModalElement = document.getElementById('myModal');
  if (myModalElement) {
    const myModal = new Modal(myModalElement, {
      backdrop: true, // Example option
      keyboard: true
    });
    // You might show the modal based on some event or initial state:
    // myModal.show();
  }

  // Example: Initialize all tooltips on the page
  const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
  const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new Tooltip(tooltipTriggerEl));

  console.log('Bootstrap Modal and Tooltip components initialized.');
});

/*
HTML Context for the above JavaScript:
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#myModal">
  Launch demo modal
</button>

<div class="modal fade" id="myModal" tabindex="-1" aria-labelledby="myModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="myModalLabel">Modal title</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        This is a Bootstrap modal.
      </div>
    </div>
  </div>
</div>

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
  Hover for Tooltip
</button>
*/