-
-
Notifications
You must be signed in to change notification settings - Fork 177
Acknowledgements
BSN stands for Bootstrap Native or Native JavaScript for Bootstrap and this project was started back in 2014 as an alternate version for the official Bootstrap plugins for jQuery, with a more simple design and much lighter footprint.
This library is not a perfect drop-in replacement of the original library, 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 42Kb (~15Kb gZipped), you can do most of the original Bootstrap 5 bundle (including Popper), 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.
The library tooling for code formatting and/or linting has been replaced with build-in Deno 2 tools for an easier long term maintenance.
In contrast with v4.x release when we used Typescript definitions in JSDoc, BSN V5.x comes with the entire source fully rewritten in Typescript and all the tooling has been reworked with Vite, Vitest and Typescript. While the components will allow you to initialize on Element targets, internally they are checked to make sure sure HTMLElement or any specific type is enforced for each specific case.
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.
All components that provide instance options use their default values 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 })
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 in the sense that event listeners are attached to HTMLElements for performance reasons. In essence, the more event listeners attached to the global objects, the more pronounced negative effect on performance.
Our implementation is focused on having the least possible overhead in event delegation and this is why we always attach event handlers to our component specific target elements. Further more, components like ScrollSpy, Tooltip, Modal or Dropdown make use of ResizeObserver or IntersectionObserver instead of the resize and/or scroll events on the window node to eliminate any potential JANKY performance.
Only components like Modal, Dropdown, Popover and Tooltip make use of event delegation for event handlers attached to the <DOCUMENT> node, and only for a short period of time. While for instance a <div class="dropdown-menu"> is shown to the user, an event listener is responsible for closing the dropdown menu, 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.
Starting with v5.1.x all interactive components like Button, Modal have event listeners that check if the targets are not disabled before anything else, to make sure the functionality is consistent.
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.
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.
The library exports ESNext modules, one for the entire bundle and one for each component. In short, you can import the default export of the bundle from "bootstrap.native" or any component from "bootstrap.native/component-name" (for instance "bootstrap.native/alert").
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.
Also we don't support 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.
- How about having a
pausedclass 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?
- 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?
If your application delivers content dynamically, you surely need to check this out.
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.
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.
Starting with V5.1.x no additional styling is required for Popover.
Was this helpful or you want to report an error?