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 10-12Kb gZipped, 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.

TypeScript Definitions

While BSN comes with "strong" type definitions starting with V4.1, it doesn't enforce them like the original library does, the reason being that it would defeat the purpose of having a lighter version in the first place. The only error thrown is when selector doesn't match any element and as a result it prevents creating instances where events cannot be attached to non-existing elements.

Right To Left Languages

Starting with BSN version 4.1, our library comes with full RTL Languages support, based on the requirements of the original library. In this regard, our Carousel, Dropdown, Popover and Tooltip components have been updated to provide functionality on par with the original library.

Component Options

All 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 itself, 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!

In addition, the initialization callbacks will also look into CustomElement LightDOM to initialize any eligible elements, a feature showcased in the demo with Tooltip and Popover.

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.

Make use of tree-shaking to the max, so you can create de-duped bundles by importing only specific components into your application, 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 these components will try to use whatever you configure to fill in the title and / or content into the designated template. However, when initializing via JavaScript, you can set the title and/or content options of your tooltips/popovers as HTMLElement which is pretty neat.

Some features are even better

• How about having a paused class for Carousel when in paused state?
• The Dropdown will not be dismissed when interacting with a form inside the <div class="dropdown-menu"> (later added to the 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 50% 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;
}