Acknowledgements

BSN General Information

This library is not a perfect drop-in replacement of the original jQuery Plugins, as some functionalities have been added over time into the official Bootstrap code base, we decided to skip them for lack of requests/interest. Still, with a library of only 10Kb gZiped, you can do most of Bootstrap 5 + Popper.js combined, which is something you should consider.

This library does not require the Popper library for Dropdown, Popover and Tooltip components like the original script and the additional features from Popper have been partially implemented first for Tooltip / Popover and later for Dropdown.

The demo page for BSN provides documentation for a general guidance on how to use the components and applies to the current stable Bootstrap version and the legacy or future version.

Component Options

All our components that provide instance options have their default values and are used when no option is provided on initialization. By default this is the default order of priority for instance options (from top - the highest to bottom - the lowest):

• JavaScript initialization options (EG: new BSN.Modal('#target',{backdrop: false }))
• DATA API options (EG: <button data-bs-backdrop="false" data-toggle="modal">)
• default options (EG: defaultModalOptions = { backdrop: true })

Event Delegation

The original plugins attach events to the <DOCUMENT> and/or window and delegate handlers for events like click to each component specific selector, very similar to how jQuery plugins traditionally work. Our implementation is different. For sure nothing can stop you from creating your own initialization script with your own builds to do exactly what original plugins do.

Our implementation is focused on having the least possible overhead in event delegation and that is why we always attach event handlers to our component specific target elements. Further more, only the ScrollSpy component makes use of the resize or scroll events on the window element for its functionality and only when the target of the scroll event is required for a specific instance. In fact the ScrollSpy component's scroll & resize event listeners are always attached to the global object and only those.

Other components like Modal, Dropdown, Popover and Tooltip also make use of event delegation for event handlers attached to the <DOCUMENT> or window elements, but only for a short period of time. While for instance a <div class="dropdown-menu"> is shown to the user, event handlers will reposition the visible element on both scroll and resize events, then when the <div class="dropdown-menu"> is hidden to the user, these event handlers are detached.

The Carousel component will attach an event listener for keydown to the global object for its keyboard navigation feature, but with no effect to performance, especially if no carousel element is visible in the viewport.

Content Sanitization

BSN doesn't include any sanitization utility, however both Tooltip and Popover components come with sanitizeFn option you can set to use yourself. You have the freedom to use your preferred solution specific to your context: PHP, JavaScript, Python, Ruby, etc.

All Components Can Be Initialized Automatically

If you include the library in your site and all elements use proper markup, everything including Tooltip and Popover are initialized on load via their DATA API specific attributes. To disable the automatic initialization, you can either create a custom build to exclude components initialization OR don't use the specific DATA API attributes in your markup. Totally up to you!

Use The Build Files

The library is ES6+ sourced which means that you might not use the files in the /src folder right away, except some modern browsers with ES6+ support. The library provides UMD and ESM bundles, minified and un-minified as well as individual components are ESM modules for the latest stable Bootstrap version, all in the /dist folder.

You can also create deduped bundles by importing only specific components into your application, again, totally up to you.

Some Features Have Been Slightly Altered

For instance we don't have a show option for Modal due to the flexibility nature of native JavaScript, Bootstrap 5 also deprecated this option; but that's fully explained for each component in the demo page.

Also we don't sport any options like html for Popover / Tooltip since we already use Element.innerHTML to fill in the title and / or content into the designated template.

Some features are even better

• How about access to instance object without a getInstance() method (EG: myModalElement.Modal)? Keep in mind that this only expose public methods and nothing else.
• Or having a paused class for Carousel when in paused state?
• Want an option to keep a Dropdown open as if you would have a form inside (later implemented in vanilla version too)?
• Dropdown, Tooltip and Popover automatic (re)positioning without any required option or third party scripts. Not good enough?
• Tooltip and Popover mousemove event listeners for Media elements, without Popper?
• Tab component can do a nice transition when tab contents have different heights, and now with the Bootstrap 5 version you don't even have to set any option for that. Neat?
• Did you know BSN is around 20-30% of the size of the original library?

Dynamic Content

If your application delivers content dynamically, you surely need to check this out.

Original Events

Most events like show, hide, slide or close can be default prevented, which means you can use event.preventDefault() with your conditional functions. Other events like shown, hidden or slid don't have this functionality as it might break the page functionality or other application.

Namespace

While the original events like show.bs.modal are inline with the original components exactly, some method names might not be the same with the original library. You should check the documentation provided in the demo page.

Additional Styling

The dismiss Popover close button would require some adjustments for perfect looks. Copy this code in your application CSS files.

/* styles the close button for the dismissible popovers */
/* Bootstrap 4 */
.popover .close {
  line-height: 0.75;
}

/* Bootstrap 5 */
.popover .btn-close {
  position: absolute;
  right: 0.75em;
}

As for our Dropdown component, since the original plugin requires Popper.js and relies completely on it for positioning, our Bootstrap 5 version might require additional style for the <div class="dropdown-menu"> alternative positioning.

/* DROPDOWN */
.dropdown-menu-end {
  right: 0;
  left: auto;
}

.dropup .dropdown-menu {
  top: auto;
  bottom: 100%;
}

.dropend .dropdown-menu {
  left: 100%;
  right: auto;
}

.dropstart .dropdown-menu {
  left: auto;
  right: 100%;
}