Alert Methods

The Alert component exposes two public methods to be used via JavaScript:

Alert Events

The component's original events are same as with the original jQuery Plugin. The event.target of the events is the <div class="alert"> element, and not the initialization target with the data-bs-dismiss="alert" attribute.

Alert DATA API

The component will initialize all elements with proper DATA API found in the DOM. Note that the data-bs-dismiss="alert" attribute is required for the triggering button. Also note that, differently from the original version, the show class is required for its main method.

<!-- notice the <button> with the data-bs-dismiss="alert" attribute -->
<div class="alert alert-warning alert-dismissible fade show" role="alert">
  <button id="myButtonAlert" type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
  Some critical notice.
</div>

Alert JavaScript API

After inserting a new alert into the page, you can initialize it via JavaScript. Considering the above markup, you can do the following:

// initialize
var myWarningAlertInit = new BSN.Alert('.alert');

Also attach handlers to the original events:

// close.bs.alert
myAlert.addEventListener('close.bs.alert', function(event){
  // this event can be default prevented 
  // do something cool
  // event.target is <div class="alert">
}, false);

// closed.bs.alert
myAlert.addEventListener('closed.bs.alert', function(event){
  // do something cool
  // event.target is <div class="alert">
}, false);

Like all components of the library you can access the initialization object even if it was done via the DATA API:

// find an element initialized via DATA API
var myAlert = document.querySelector('.alert');

// reference the initialization object
var myAlertInit = myAlert.Alert;

// apply the public methods
myAlertInit.close();
// or 
myAlertInit.dispose();

Alert Examples

This alert has some handlers attached to close.bs.alert and closed.bs.alert events, so check your console.

This alert uses the closed.bs.alert event to show another alert.

Button Methods

Button DATA API

The component will initialize all elements with the data-bs-toggle="button" attribute on page load. The basic markup looks like this:

<!-- button tags -->
<button type="button" class="btn btn-primary" data-bs-toggle="button" autocomplete="off">Toggle button</button>
<button type="button" class="btn btn-primary active" data-bs-toggle="button" autocomplete="off" aria-pressed="true">Active toggle button</button>
<button type="button" class="btn btn-primary" disabled data-bs-toggle="button" autocomplete="off">Disabled toggle button</button>

<!-- anchor tags -->
<a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
<a href="#" class="btn btn-primary disabled" tabindex="-1" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>

Button JavaScript API

If the above markup is present in the DOM when the library is loaded, the component will initialize all targets via DATA API, however if inserted later into the DOM, here's how to initialize it:

// initialize
var myButtonINIT = new BSN.Button('#myButton');

The <button id="myButton"> element now stores the initialization object, just like the other components of the library:

// reference the initialization, even for DATA API initialized btn-group elements
var myButtonINIT = myButton.Button;

Button Examples

State Toggle

Toggle button Active toggle button Disabled toggle button

Toggle link Active toggle link Disabled toggle link

Checkboxes and Radio

The following examples are purely for demo and only require the proper markup, no script is required.

Checkbox 1 (pre-checked) Checkbox 2 Checkbox 3

Radio 1 (preselected) Radio 2 Radio 3

Radio 1 Radio 2 (preselected) Radio 3

Carousel Options

Carousel Methods

The previously featured instance method .getActiveIndex() has been deprecated in favor of custom event properties which provide much more information from the instance execution context.

Carousel Events

The Carousel component exposes two events that allow you to trigger custom functionality when the carousel slides.

These component specific events are triggered on the <div class="carousel"> element and both expose the following additional properties:

Carousel DATA API

The component covers most of the original implementation in regards to DATA API, except that you can ignore some of the attributes for the controls, but they must have at least their specific class in order to work. This is a basic template markup followed by a complete attribute breakdown:

<!-- the Carousel component -->
<div id="myCarousel" class="carousel slide" data-bs-ride="carousel" data-bs-interval="5000" data-bs-touch="true" data-bs-pause="hover">
  <!-- Indicators -->
  <div class="carousel-indicators">
    <button data-bs-target="#myCarousel" data-bs-slide-to="0" class="active"></button>
    <button data-bs-target="#myCarousel" data-bs-slide-to="1"></button>
    <button data-bs-target="#myCarousel" data-bs-slide-to="2"></button>
  </div>
  <!-- Wrapper for slides -->
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img class="img-fluid" src="..." alt="...">
      <div class="carousel-caption">
      <h3>This is a carousel caption</h3>
      </div>
    </div>
    <div class="carousel-item">
      <img class="img-fluid" src="..." alt="...">
      <div class="carousel-caption">
      <h3>This is a caption</h3>
      </div>
    </div>
    <div class="carousel-item">
      <img class="img-fluid" src="..." alt="...">
      <div class="carousel-caption">
      <h3>This is another caption</h3>
      </div>
    </div>
  </div>

  <!-- Controls -->
  <a class="carousel-control-prev" href="#myCarousel" role="button" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Prev</span>
  </a>
  <a class="carousel-control-next" href="#myCarousel" role="button" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </a>
</div>

A quick walk through the attributes:

• id="myCarousel" is not required for any of the component's functionality, except cases when you need to interact with it and attach additional functionality;
• data-bs-ride="carousel" is the attribute required if you want the Carousel component to initialize your element automatically;
• data-bs-keyboard="false" (not shown in the sample markup) is the attribute that enables carousel navigation via keyboard left and right arrow keys;
• data-bs-interval="5000" sets the automatic slide interval; the false value will disable automatic slide transition; the usage of this attribute for each item is not implemented in BSN;
• data-bs-pause="hover" is the attribute you can set to pause the carousel on mouse hover, but it also adds a paused class to your carousel; if the above is also false, this setting has no effect;
• data-bs-touch="true" is the attribute you can set to enable touch support for your carousel, however, you must have at least 3 .carousel-item elements in order to work;
• data-bs-slide-to="0" is an attribute used by .carousel-indicators elements; when clicked will slide to the carousel item with the same index, 0 (zero) in this case;
• data-bs-slide="prev" / data-bs-slide="next" when clicked, will slide to the next / previous carousel item; these attributes are optional, but the class carousel-control is required;
• href="#myCarousel" / data-bs-target="#myCarousel" attributes are not required for any of the Carousel controls; we will see in the example below why and how to do it with BSN;
• class="carousel-item active" / class="active" when active class is present for a carousel item or indicator, that indicates which carousel item is currently shown to the user, the above .getActiveIndex() method will look for it when needed.

Carousel JavaScript API

The component grants full access to the internal working via JavaScript; whether via the public methods or the original events, you can do a whole bunch of things. Assuming the above markup have been injected into the DOM, let's go ahead and initialize it:

// initialize with some options
var myCarouselInit = new BSN.Carousel('#myCarousel', {
  // these options values will override the ones set via DATA API
  interval: false,
  pause: false,
  keyboard: false
});

And now we can play with the methods:

// call next() to jump to the next item
myCarouselInit.next();

// jump to the item with index 2
myCarouselInit.to(2);

// if the carousel was set with `interval: NUMBER`
// call this method to pause the automatic cycle
myCarouselInit.pause();

// if the carousel was set with `interval: false`
// we can do this to go to the next item
// AND resume if `interval: NUMBER` is used
myCarouselInit.cycle();

// anytime you need to destroy
myCarouselInit.dispose();

As you probably expect by now, this component also stores the initialization in the element it targets on initialization, even for instances where the DATA API was used:

// get some carousel item and reference the initialization
var mySpecialCarouselInit = document.getElementById('mySpecialCarousel').Carousel;

// apply methods
mySpecialCarouselInit.cycle();

Also, additional interaction can be coded around the original events:

// this event handler function will run when the carousel begins to slide
document.querySelector('.carousel').addEventListener('slide.bs.carousel', event => {
  if (event.target.id !== '#myCarousel') {
    event.preventDefault(); // preventDefault for your special case
    return;
  }
  // or do something with the event specific properties
  console.log("The carousel is sliding " + event.direction);
  console.log("The carousel is sliding to index " + event.to);
  console.log("The carousel is sliding from index " + event.from);
});

Carousel Example

This is a test demonstrating the component capabilities and it's events, so open your console, and start clicking, you will be noticed before and after the animation. Also know that there was no active item set by default in the markup, proving the component can successfully manage this case by setting the first item as active on initialization.

This is another carousel

This is a caption

This is another caption

Previous Next

These three independent buttons use some inline JavaScript to control the carousel:

<button class="btn btn-secondary" 
  onclick="myCarousel.Carousel.to(0)">
  START
</button>

<button 
  class="btn btn-secondary"
  onclick="myCarousel.Carousel.prev()">
  PREV
</button>

<button 
  class="btn btn-secondary"
  onclick="myCarousel.Carousel.next()">
  NEXT
</button>

This highlights the fact that we don't need to use href="#myCarousel" attribute for the carousel controls, if the carousel itself has an ID, the above markup shows you how to do it, easily:

• when clicked, the first <button> will slide to first slide
• when clicked, the second <button> will slide to PREVIOUS slide
• when clicked, the third <button> will slide to NEXT slide

Collapse Options

The option below allow you to connect a collapse to a parent accordion.

Collapse Methods

Calling any of the public methods while animation is running, will produce no effect.

Collapse Events

All the component's events are attached to the collapsible element and not its targeting button / element, with other words, the event.target is the element with the class="collapse" attribute.

Collapse DATA API

In the following markup, the component will initialize the two .btn elements with the data-bs-toggle="collapse" attribute, both refferencing the same collapsible element via specific atttributes.

<!-- toggle collapse via link with HREF reference -->
<a id="collapseLink" class="btn btn-primary" role="button" aria-expanded="false" aria-controls="collapseExample"
  data-bs-toggle="collapse" href="#collapseExample"> <!-- required DATA API -->
  Link with href
</a>

<!-- AND / OR toggle collapse via button with data-bs-target attribute reference -->
<button id="collapseButton" class="btn btn-primary" type="button" aria-expanded="false" aria-controls="collapseExample"
  data-bs-toggle="collapse" data-bs-target="#collapseExample"> <!-- required DATA API -->
  Button with data-bs-target
</button>

<!-- and the basic collapsible template -->
<div class="collapse" id="collapseExample">
  <div class="card card-body">
    ...
  </div>
</div>

Now if we stack multiple collapsible elements and wrap them into one parent with an ID attribute and some helper CSS classes, we can easily create an accordion.

<!-- accordion template -->
<div class="accordion" id="accordionExample">
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingOne">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="false" aria-controls="collapseOne">
        Accordion Item #1
      </button>
    </h2>
    <div id="collapseOne" class="accordion-collapse collapse" aria-labelledby="headingOne" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        Accordion item 1 content.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingTwo">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
        Accordion Item #2
      </button>
    </h2>
    <div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        Accordion item 2 content.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="headingThree">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
        Accordion Item #3
      </button>
    </h2>
    <div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree" data-bs-parent="#accordionExample">
      <div class="accordion-body">
        Accordion item 3 content.
      </div>
    </div>
  </div>
</div>

Collapse JavaScript API

If the above single collapse template have been inserted into the DOM, you need to initialize it via JavaScript.

// initialize the component for collapse
var myCollapseInit = new BSN.Collapse('.collapse')

This now enables you to work with the public methods.

// call the show() right away
myCollapseInit.show();

// call the hide() later
myCollapseInit.hide();

// OR call toggle() some other time
myCollapseInit.toggle();

// lastly, destroy when needed
myCollapseInit.dispose();

Also we can attach some handlers to the original events:

// first, we need to reference the collapse element
var myCollapseExample = document.getElementById('#myCollapseExample');

// attach a handler to the `show.bs.collapse` original event
myCollapseExample.addEventListener('show.bs.collapse', (event) => {
  // do something cool when .show() method is called
  // event.target is myCollapseExample
}, false);

Alright, now let's say the above accordion template have been inserted into the DOM, you need to initialize its collapsible elements right away via JavaScript.

// grab the accordion by its ID
var myAccordion = document.getElementById('myAccordion');

// grab the collapse elements of this accordion
var myAccordionCollapses = myAccordion.querySelectorAll('.collapse');

// initialize the component for each collapse trigger
Array.from(myAccordionCollapses).forEach((collapse) => 
  new BSN.Collapse(
    collapse,
    {
      parent: myAccordion
    }
  )
)

The component grants access to the initialization object.

// grab the collapse initialized via DATA API
var myCollapse = document.getElementById('myCollapse');

// reference the initialization
var myCollapseInit = myCollapse.Collapse;

// call any public method
myCollapseInit.toggle();

Collapse Examples

Single collapsible element

Here's a quick demo with a single collapsible element, using the .card as the container, exactly as described in the DATA API section. The demo also features the original events.

Accordion / Multiple Collapsible Elements

Here's an Accordion example, built with a dedicated markup from the original plugin. When the toggle links are clicked, our Collapse component will look for the closest <div class="accordion-className"> or <div id="accordion-id"> via data-bs-parent="selector" and will hide any visible collapsible element.

Remember that all triggering buttons must reference the accordion via data-bs-parent="selector" as described above in order to collapse current opened collapsible element.

Dropdown Options

The previously featured persist options has been deprecated. The .dropdown-menu can be or contain a <form> element, in which case the component will not dismiss when clicking or focusing inside and enables the user to interact with it.

Dropdown Methods

Dropdown Events

The Dropdown component covers the original events and the target of all events is the <div class="dropdown"> element.

If clicked, the triggering element with the specific data-bs-toggle="dropdown" attribute will be the event.relatedTarget. However, if you dismiss the dropdown via JavaScript, the Esc key or by clicking outside the triggering button, the event.relatedTarget is null.

Dropdown DATA API

Notice we use same markup as the original example, the triggering element with the data-bs-toggle="dropdown" attribute will initialize the Dropdown component.

<!-- basic dropdown template -->
<div class="dropdown">
  <button id="myDropdown" type="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu" aria-labelledby="myDropdown">
    <a class="dropdown-item" href="#">Action 1</a>
    <a class="dropdown-item" href="#">Action 2</a>
  </div>
</div>

Dropdown JavaScript API

When you want full control or you need a way to handle dynamically generated dropdown-menus, you can do it via JavaScript. Considering the above HTML was inserted into the DOM, let's initialize it real quick:

// initialize component
var myDropdownInit = new BSN.Dropdown( '#myDropdown' );

// OR initialize component and access public method right away
var myDropdownInit = new BSN.Dropdown( '#myDropdown' ).toggle();

Also assuming the above HTML was used for your dropdown-menu, we can also attach the original events to the parent of the triggering element, which is the <div class="dropdown"> element:

// show.bs.dropdown
myDropdown.parentNode.addEventListener('show.bs.dropdown', function(event){
  // this event can be default prevented
  // do something when the event fires
  // event.target is the PARENT of the triggering element
  // event.relatedTarget is the triggering element
}, false);

// shown.bs.dropdown
myDropdown.parentNode.addEventListener('shown.bs.dropdown', function(event){
  // do something when the event fires
  // event.target is the PARENT of the triggering element
  // event.relatedTarget is the triggering element
}, false);

// hide.bs.dropdown
myDropdown.parentNode.addEventListener('hide.bs.dropdown', function(event){
  // this event can be default prevented
  // do something when the event fires
  // event.target is the PARENT of the triggering element
}, false);

// hidden.bs.dropdown
myDropdown.parentNode.addEventListener('hidden.bs.dropdown', function(event){
  // do something when the event fires
  // event.target is the PARENT of the triggering element
}, false);

When your dropdown-menus have a different structure and the myDropdown.parentNode is NOT the <div class="dropdown"> element, you might consider a getClosest() function to find it so you can then attach the original events to it.

Now, the Dropdown component also stores the initialization object in the targeted elements, just as for the modal triggering buttons:

// reference the initialization
var myDropdownInit = document.getElementById('myDropdown').Dropdown;

// use the public Methods
myDropdownInit.toggle();

// or destroy
myDropdownInit.dispose();

Also you can do a simple check for the existence of 'Dropdown' in myDropdown element to make sure you don't go the wrong way.

Dropdown Examples

Right out of the box, the above dropdown template is initialized via DATA-API right away.

If you resize or scroll the window pushing the opened dropdown menus outside the viewport, the new automatic positioning kicks in. Notice it doesn't apply any CSS styling, the component will only use the right CSS classes to display the dropdown menu in the viewport, then revert to its original class if closed. The feature doesn't require Popper.js.

The original plugin doesn't support nesting nor recommend using it, and due to the implementation of automatic repositioning we decided to deprecate nesting functionality from our component.

Be sure to check the markup of the above examples and the original plugin documentation page.

Modal Options

The previously featured content option has been deprecated. We decided to allow you to use what ever manipulation method and / or sanitization you consider fit for your projects.

The default options' values are same as their vanilla equivalents so you can expect the same behavior.

Modal Methods

For full control the Modal component exposes a couple of public methods to be used via JavaScript :

The previously featured .setContent() method has been deprecated.

Modal Events

All original events are triggered for the <div class="modal"> element and not the initialization target with its usual data-bs-toggle="modal" attribute.

If modal is opened via JavaScript methods, or by clicking on another element that is not a modal triggering element, the event.relatedTarget is null.

Modal DATA API

You can initialize Modal without writing any code as long as you have a modal and a trigger button with the data-bs-target attribute or a link with href attribute referencing that modal. The component will initialize all <div class="modal"> elements found in the DOM.

<!-- provide a trigger button -->
<button data-bs-toggle="modal" data-bs-target="#myModal" type="button">Launch modal</button>

<!-- Alternatively provide a link -->
<a data-bs-toggle="modal" href="#myModal">Launch modal</a>

<!-- also the modal itself -->
<div id="myModal" class="modal fade" role="dialog" 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">
        Some content
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-success">Save changes</button>
      </div>
    </div>
  </div>
</div>

As shown in the above sample markup, Modal can work with multiple triggering elements as well as multiple dismiss elements, with minimal effort and no events overhead on the global object.

Modal JavaScript API

Generally you can initialize Modal for any instance of <div class="modal"> and immediately get access to methods.

Let's create a very basic modal template for this guide.

<!-- blank modal template -->
<div id="myModal" class="modal fade" tabindex="-1" role="dialog" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">Add your header here</div>
      <div class="modal-body">Add your body content here here</div>
      <div class="modal-footer">Add your footer content here here</div>
    </div>
  </div>
</div>

Next we can initialize this modal and get access to public methods right away:

// initialize on a <div class="modal"> with all options
// Note: options object is optional
var myModalInstance = new BSN.Modal(
  '#myModal', // target selector
  { // options object
    backdrop: 'static', // we don't want to dismiss Modal when Modal or backdrop is the click event target
    keyboard: false // we don't want to dismiss Modal on pressing [Esc] key
  }
);

Now you can re-initialize your target elements very much like the original plugin, but with native JavaScript syntax:

// re-initialize on a target with different options
// also call the .show() method right away
var myNewModalInstance = new BSN.Modal('#myModal', { backdrop: true }).show();

Keep in mind that re-initializing will make use of the .dispose() method to clear memory allocated for previous initialization, which involves two things: reseting the other options' values to the DATA API specified, or default values AND lastly, if the modal is open, on re-initialization the modal will be hidden via .hide(), you can instantly call the .show() method as written above.

Now we have an initialization reference in myModalInstance, we can start applying the component's public methods:

// show the modal at any time
myModalInstance.show();

// hide the modal
myModalInstance.hide();

// toggle the modal (show/hide)
myModalInstance.toggle();

// if the above method is used while modal was shown, you can then ask for a layout update
myModalInstance.update();

// when initialization is no longer needed, you can destroy it
myModalInstance.dispose();

Any element initialized via DATA API or JavaScript, automatically grants access to the component's original events.

// GET THE EVENT TARGET, THE MODAL
// when we are certain which modal ID to work with
var myModal = document.getElementById('modalID');

// ATTACH HANDLERS
// show.bs.modal event
myModal.addEventListener('show.bs.modal', function(event){
  // do something when this event triggers
  // event.target is the modal referenced in myModal
  // event.relatedTarget is the button referenced with myModalTriggerButton
}, false);

// shown.bs.modal event
myModal.addEventListener('shown.bs.modal', function(event){
  // do something when this event triggers
  // event.target is the modal referenced in myModal
  // event.relatedTarget is the button referenced with myModalTriggerButton
}, false);

// hide.bs.modal event
myModal.addEventListener('hide.bs.modal', function(event){
  // do something when this event triggers
  // event.target is the modal referenced in myModal
}, false);

// hidden.bs.modal event
myModal.addEventListener('hidden.bs.modal', function(event){
  // do something when this event triggers
  // event.target is the modal referenced in myModal
}, false);

Additionally the component will store the initialization object in the modal, for the internal execution, hopefully would help you as well.

// you can access the initialization object from the modal itself
var myModalInit = myModal.Modal;

Modal Examples

Modal Initialized via DATA API

The first example is a modal with static content initialized via DATA API, exactly as described in the above Use via DATA API section, and showcasing the ability to show another modal from a modal currently visible.

Launch simple modal

Modal Initialized via JavaScript API

The following example is focused on initialization via JavaScript, without a triggering button:

// we grab a modal by ID
var myModal = document.getElementById('myModal');

// we grab some button by ID, we will use it later
var btnModal = document.getElementById('openModalViaJS');
// this button IS NOT a triggering element, it has no reference to the above modal

// initialize Modal for this triggering element
var modalInitJS = new BSN.Modal(myModal, {
  backdrop: 'static'
});

// OR initialize with no options provided
// the options object is optional
var modalInitJS = new BSN.Modal(myModal);

// when we click btnModal, open the modal
btnModal.addEventListener('click', function(e){
  modalInitJS.show();
}, false)

// BONUS
// since there is no triggering element, you might need
// access to the initialization object from another application
var findModalInitJS = myModal.Modal;

Open Modal

As explained in the sample code above, this modal is completely independent from a triggering button which would usually have the data-bs-toggle="modal" and data-bs-target="#myModal" attributes necesary to connect with our modal via DATA API.

Offcanvas Options

Offcanvas Methods

For full control the Offcanvas component exposes a couple of public methods to be used via JavaScript :

Offcanvas Events

All original events are triggered for the <div class="offcanvas"> element.

If the offcanvas is opened/closed via JavaScript methods, or is dismissed by clicking on another element outside the offcanvas, the event.relatedTarget is null.

Offcanvas DATA API

You can initialize Offcanvas without writing any code as long as you have an offcanvas and a trigger button with the data-bs-target attribute or a link with href referencing that offcanvas. The component will initialize all elements with <div class="offcanvas"> found in the DOM.

<!-- provide a trigger button -->
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Button with data-bs-target
</button>

<!-- or an anchor link -->
<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Link with href
</a>

<!-- also the offcanvas itself -->
<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Some text here should work.</p>
  </div>
</div>

Offcanvas JavaScript API

Generally you can initialize Offcanvas for any instance of <div class="offcanvas"> and immediately get access to methods. Similar to our Modal, this component can also work with multiple triggering button elements having the data-bs-toggle="offcanvas" attribute.

Considering the sample markup showcased in the above section, we can now initialize this offcanvas and get access to public methods right away:

// initialize on a <div class="offcanvas"> with all options
var myOffcanvasInstance = new BSN.Offcanvas(
  '#myOffcanvas', // target selector
  { // options object
    backdrop: false, // we don't want to use the backdrop
    keyboard: false, // we don't want to dismiss Offcanvas on pressing [Esc] key
    scroll: true // we allow the user to scroll the page
  }
);

Now we have an initialization reference in myOffcanvasInstance, we can start calling the component's public methods:

// show the offcanvas at any time
myOffcanvasInstance.show();

// hide the offcanvas
myOffcanvasInstance.hide();

// toggle the offcanvas (show/hide)
myOffcanvasInstance.toggle();

// if the above method is used while offcanvas was shown, you can then ask for a layout update
myOffcanvasInstance.update();

// when initialization is no longer needed, you can destroy it
myOffcanvasInstance.dispose();

Any element initialized via DATA API or JavaScript, automatically grants access to the component's original events.

// GET THE EVENT TARGET
// when we are certain which modal ID to work with
var myOffcanvas = document.getElementById('offcanvasID');

// ATTACH HANDLERS
// show.bs.offcanvas event
myOffcanvas.addEventListener('show.bs.offcanvas', function(event){
  // do something when this event triggers
  // event.target is the offcanvas referenced in myOffcanvas
  // event.relatedTarget can be the triggering button or NULL
}, false);

// shown.bs.offcanvas event
myOffcanvas.addEventListener('shown.bs.offcanvas', function(event){
  // do something when this event triggers
  // event.target is the modal referenced in myOffcanvas
  // event.relatedTarget can be the triggering button or NULL
}, false);

// hide.bs.offcanvas event
myOffcanvas.addEventListener('hide.bs.offcanvas', function(event){
  // do something when this event triggers
  // event.target is the offcanvas referenced in myOffcanvas
  // event.relatedTarget can be the triggering/dismiss button or NULL
}, false);

// hidden.bs.offcanvas event
myOffcanvas.addEventListener('hidden.bs.offcanvas', function(event){
  // do something when this event triggers
  // event.target is the offcanvas referenced in myOffcanvas
  // event.relatedTarget can be the triggering/dismiss button or NULL
}, false);

Additionally the component will store the initialization object in the offcanvas, for the internal execution, hopefully would help you as well.

// you can access the initialization object from the offcanvas itself
var myOffcanvasInit = myModal.Offcanvas;

Offcanvas Examples

These examples are all initialized via DATA API, exactly as described in the above Use via DATA API section, and showcasing the ability to show another offcanvas from an offcanvas currently visible.

Popover Options

The component covers all needed options, including those for a template system:

If a popover is a child element of a <div class="modal">, a <nav class="navbar fixed-top"> or <nav class="navbar fixed-bottom"> element, the container option is set automatically to refference that specific parent.

If a proper template is not specified via JavaScript or the content option is not set in any way, the Popover will not be initialized for that specific element.

In addition to automatic repositioning, the component will try to make sure the popovers are always in the viewport as some Popper.js functionality have been implemented into our component.

When your popover title and/or content is an HTML markup string, please make sure you sanitize the content of the markup string.

Popover Methods

For full control the Popover component exposes a couple of public methods to be used via JavaScript:

Popover Events

The component's original events are same as with the original jQuery Plugin, except inserted.bs.popover, just as explained for the Tooltip component.

The event.target of the original events is the the initialization target with the data-bs-toggle="popover" attribute.

Popover DATA API

Our component will initialize any element found to have the data-bs-toggle="popover" attribute and at least the data-bs-content attribute.

<!-- any regular link with data-bs-toggle="popover" -->
<a href="https://google.com" data-bs-title="Google" data-bs-content="Google is cool" data-bs-toggle="popover">Google</a>

<!-- any SVG shape with data-bs-toggle="popover" -->
<svg viewBox="0 0 80 34" width="80" height="34" xmlns="http://www.w3.org/2000/svg">
  <rect data-bs-toggle="popover" data-bs-placement="top" data-bs-delay="150" data-bs-content="Demo Title for SVG" rx="5"></rect>
</svg>

Popover JavaScript API

After inserting new content into the page, you can initialize any element with Popover via JavaScript. You can also initialize for elements not having the specific DATA API. You can do the following:

// find all elements with data-bs-content attribute
var popoverTargets = document.querySelectorAll('[data-bs-content]'); // also a certain class would go fine

// initialize Popover for each element
Array.from(popoverTargets).forEach(
  popTarget => new BSN.Popover( popTarget, {
    placement: 'top', // string
    animation: true, // boolean
    customClass: 'my-special-class', // string
    delay: 100, // integer
    dismissible: true, // boolean
    sanitizeFn: function(dirty){ // use sanitizer of your choice here
      return DOMPurify.sanitize(dirty);
    }    
  })
);

In addition, similar to any other component of this library, you can access the initialization and the public methods even for elements initialized via DATA API.

// find an element initialized with Popover
var myLinkWithPopover = document.getElementById('myLinkWithPopover');

// reference the initialization object
var myPopoverInit = myLinkWithPopover.Popover;

Just because you can, you can re-initialize any element on the fly, to change options or to just call the .show() method.

// re-initialize Popover and call .show()
new BSN.Popover('#selector',options).show();

Considering the just above element, let's go ahead and put the component's events to use:

// show.bs.popover
myLinkWithPopover.addEventListener('show.bs.popover', function(event){
  // do some cool stuff when .show() method is called
  // event.target is myLinkWithPopover
}, false);

// shown.bs.popover
myLinkWithPopover.addEventListener('shown.bs.popover', function(event){
  // do some cool stuff when .show() method completed
  // event.target is myLinkWithPopover
}, false);

// hide.bs.popover
myLinkWithPopover.addEventListener('hide.bs.popover', function(event){
  // do some cool stuff when .hide() method is called
  // event.target is myLinkWithPopover
}, false);

// hidden.bs.popover
myLinkWithPopover.addEventListener('hidden.bs.popover', function(event){
  // do some cool stuff when .hide() method completed
  // event.target is myLinkWithPopover
}, false);

To use the template system, you can do the following:

// initialize Popover with a custom template
var popover2 = new BSN.Popover('.popover-via-template', { // where .popover-via-template is the text input
  title: 'Sample title', // string
  content: '<p>Some sample message.</p>', // string
  trigger: 'focus', // string
  sanitizeFn: yourUtilityOfChoice, // function
  template: '<div class="popover custom-class" role="tooltip">'
  + '<div class="arrow"></div>'
  + '<h3 class="popover-header"></h3>'
  + '<div class="popover-body"></div>'
  + '</div>'
});

ScrollSpy Options

ScrollSpy Methods

ScrollSpy Events

The event.target is the element we initialized the component via JavaScript or has the data-bs-spy="scroll" attribute. The newly activated menu item is the event.relatedTarget of the event object.

ScrollSpy DATA API

To initialize ScrollSpy, remember the requirements from the original jQuery plugin. The component can initialize any element with overflow: auto|scroll and a fixed height, or the <body> or an immediate child element. For the second case we need some special HTML markup and appropriate styling for containers in order to initialize.

An overflowing element that has set overflow: auto|scroll style rule:

• The headings have the required IDs;
• Only the element requires some additional CSS;
• No special markup required.

<!-- the element we initialize ScrollSpy on -->
<div data-bs-spy="scroll" data-bs-target="#navbar-example" class="scrollspy-example">

  <!-- we look for the position of heading -->
  <h4 id="one">Title ONE</h4>
  <p>Valid TEXT goes here</p>

  <h4 id="twoOne">Title TWO</h4>
  <p>Valid TEXT goes here</p>

  <h4 id="three">Title THREE</h4>
  <p>Valid TEXT goes here</p>

</div>

<!-- we need a target, any of the below elements with an ID will do -->
<nav id="nav-example"> <!-- we can also target it's parent as well -->
  <ul id="navbar-example" class="nav flex-column"> <!-- this is our element's target -->
    <li class="nav-item"><a class="nav-link" href="#one">One</a></li>
    <li class="nav-item"><a class="nav-link" href="#two">Two</a></li>
    <li class="nav-item"><a class="nav-link" href="#three">Three</a></li>
  </ul>
</nav>

In this case we only need to set a fixed height for the element and change its overflow:

/* the element we initialize ScrollSpy on */
.scrollspy-example {
  position: relative; /* required */
  height: 150px; overflow: auto; /* required: height must be px based, and overflow: scroll/auto */
}

A non-overflowing element that wraps most of the content of your page:

• Special markup IS required;
• The element's child containers have the required IDs;
• Child containers require some additional styling.

<!-- the element we initialize ScrollSpy on -->
<div data-bs-spy="scroll" data-bs-target="#navbar-example" class="scrollspy-example">

<section id="one"> <!-- this is a ScrollSpy container -->
  Valid HTML goes here
</section>

<section id="two">
  <section id="twoone">
    One level nested containers also apply
  </section>

  <section id="twotwo">
    This is your second nested container
  </section>
</section>

</div>

<!-- we need a target, any of the below elements with an ID will do -->
<nav> <!-- we can also target it's parent as well -->
<ul id="myScrollSpyTarget" class="nav flex-column"> <!-- this is our element's target -->
  <li class="nav-item"><a href="#one">One</a></li>
  <li class="nav-item">
    <a class="nav-link" href="#two">Two</a>
    <ul class="nav flex-column">
      <li class="nav-item"><a class="nav-link" href="#twoone">Two One</a></li>
      <li class="nav-item"><a class="nav-link" href="#twotwo">Two Two</a></li>
    </ul>
  </li>
</ul>
</nav>

ScrollSpy JavaScript API

For full control and access to the component's features, coding the JavaScript part is a breeze. Assuming the above markup have been injected into the DOM and the CSS is set, let's initialize, apply the public method and attach handlers to the original event.

// the element we initialize ScrollSpy on
var myScrollSpyElement = document.getElementsByClassName('scrollspy-example')[0];

// let's give the initialization a JavaScript reference for the "target" option
var myScrollSpyTarget = document.getElementById('myScrollSpyTarget');

// initialize the ScrollSpy for this element
var myScrollSpyInit = new BSN.ScrollSpy(myScrollSpyElement, {
  // set options
  target : myScrollSpyTarget,
  // alternativelly, provide a valid selector string
  // EG: ".my-unique-class-name" or "#my-unique-ID"

  // in some cases the offset option would help calculate
  // the correct boundaries of target containers
  offset: 15
})

If the initialization validates (the target option is valid and the component links the element with it's target), we have access to the methods and the original event.

// apply the public method after DOM changed
// a new element container and it's corresponding menu item have been injected into the DOM
myScrollSpyInit.refresh();

// attach an event handler
myScrollSpyElement.addEventListener('activate.bs.scrollspy', function(event){
  // do some cool stuff
  // event.target is myScrollSpyElement
  // event.relatedTarget is the menu item link that triggered the event
}, false);

// when no longer needed, destroy
myScrollSpyInit.dispose();

To get access to an initialization object regardless of how it was initialized, here's how to do it:

// grab an element we know it was initialized via DATA API
var myScrollSpy = document.getElementById('myScrollSpy');

// check if the element is already initialized
var myScrollSpyIsInitialized = 'ScrollSpy' in myScrollSpy;

// if the above is true
var myScrollSpyInit = myScrollSpy.ScrollSpy;

// call the public methods
myScrollSpyInit.refresh();
// or
myScrollSpyInit.dispose();

Now this makes alot more sense, especially when you expect full control and also want to make sure you don't attach event handlers multiple times for your elements.

ScrollSpy Examples

According to the above Usage Guide let's initialize an overflowing element via DATA API:

For this example the overflowing element itself is the target of the scroll event, and above it the .nav component as it's target, while for the other example in this page, the side navigation on the right side, the window is the target of the scroll event.

If the initialization element is hidden or its height is 0, the ScrollSpy component will attach the scroll listener to the window, basically an invalid instance. Be sure to check the original plugin for other guides or to compare implementations.

Tab Options

To optimize the component and simplify the script, the previously featured initialization option height has been deprecated. The component will always create a height transition for the <div class="tab-content"> element.

Tab Methods

Tab Events

The event.target for the component original events is either the current active tab or the next tab to be activated, depending on the specific event, as explained below. The events will fire in the exact order shown in table below:

Tab DATA API

Here is a sample markup to showcase the usage of the component with the above mentioned methods. As you can see, each of the elements with the data-bs-toggle="tab" attribute are subject to the Tab component initialization.

<!-- for better usage, wrap the tabs and contents -->
<div id="myTabsWrapper">

<!-- Nav tabs -->
<ul id="myTabs" class="nav nav-tabs" role="tablist">
  <li class="nav-item">
    <a class="nav-link active" id="home-tab" href="#home" data-bs-toggle="tab" data-height="true" aria-controls="home" aria-selected="true" role="tab">Home</a>
  </li>
  <li class="nav-item">
    <a class="nav-link" id="profile-tab" href="#profile" data-bs-toggle="tab" data-height="true" aria-controls="profile" aria-selected="false" role="tab">Profile</a>
  </li>
  <li class="nav-item">
    <a class="nav-link" id="messages-tab" href="#messages" data-bs-toggle="tab" data-height="true" aria-controls="messages" aria-selected="false" role="tab">Messages</a>
  </li>
  <li class="nav-item">
    <a class="nav-link" id="settings-tab" href="#settings" data-bs-toggle="tab" data-height="true" aria-controls="settings" aria-selected="false" role="tab">Settings</a>
  </li>
</ul>

<!-- Tab panes -->
<div class="tab-content">
  <div role="tabpanel" class="tab-pane fade active show" aria-labelledby="home-tab" id="home">...</div>
  <div role="tabpanel" class="tab-pane fade" aria-labelledby="profile-tab" id="profile">...</div>
  <div role="tabpanel" class="tab-pane fade" aria-labelledby="messages-tab" id="messages">...</div>
  <div role="tabpanel" class="tab-pane fade" aria-labelledby="settings-tab" id="settings">...</div>
</div>

</div>

Also don't forget that this functionality works on CSS3 enabled browsers with the Collapse styling in place.

Tab JavaScript API

Since the component will target a single element with / or without data-bs-toggle="tab" attribute, but at least it references a corresponding tab via href or data-bs-target, we will need to do a simple loop to initialize multiple elements. Assuming the above markup have been injected into the DOM, let's initialize, use the public method and attach handlers to the original events.

// first, we reference the .nav component that holds all tabs
var myTabs = document.getElementById('myTabs');

// let's give the initialization a JavaScript reference for the "target" option
var myTabsCollection = myTabs.getElementsByTagName('A');

// initialize the component for all items in the collection
Array.from(myTabsCollection).forEach(
  tab => new BSN.Tab( tab )
);

If each item in the collection meets the expected markup and the tab it referencing is found, the initialization will then validate and give you immediate access to method.

// get last item from collection and reference it's initialization
var myLastTab = myTabsCollection[myTabsCollection.length-1];
var myLastTabInit = myLastTab.Tab;

// assuming the last tab is not active, we can show it
myLastTabInit.show();

// attach an event handler as well
myLastTab.addEventListener('show.bs.tab', function(event){
  // do some cool stuff
  // event.target is myLastTab
  // event.relatedTarget is the previous active tab
}, false);

We could have also built an Object / Array with the initialization objects, but that depends very much on your needs.

Tab Examples

OK now we're ready to put this component to the test. We'll use all Bootstrap .nav components in the pool.

• Home
• Profile
• Dropdown
  Some tab Events

• Home
• Profile
• Dropdown
  Some tab Last Tab

Toast Options

Toast Methods

The Toast component exposes two public methods to be used via JavaScript:

Toast Events

The event.target for the component's original events is the one with the class="toast" attribute, which is also the parent of the initialization target, usually the element having the data-bs-toggle="toast" attribute.

Toast DATA API

The component will initialize all elements with proper markup and the specific DATA API attributes found in the DOM. Note that the data-bs-dismiss="toast" attribute is required for the triggering button.

<!-- notice the <button> with the data-bs-dismiss="toast" attribute -->
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded mr-2" alt="...">
    <strong class="mr-auto">Bootstrap</strong>
    <small>11 mins ago</small>
    <button id="myTastyToast" type="button" class="ml-2 mb-1 btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

Toast JavaScript API

After inserting a new toast notification into the page, you can initialize it via JavaScript. Considering the above markup, you can do the following:

// initialize
var myTastyToast = new BSN.Toast('#myTastyToast');

Also attach handlers to the original events:

// show.bs.toast
myTastyToast.closest('.toast').addEventListener('show.bs.toast', function(event){
  // do something cool
  // event.target is <div class="toast">
}, false);

// shown.bs.toast
myTastyToast.closest('.toast').addEventListener('shown.bs.toast', function(event){
  // do something cool
  // event.target is <div class="toast">
}, false);

// hide.bs.toast
myTastyToast.closest('.toast').addEventListener('hide.bs.toast', function(event){
  // do something cool
  // event.target is <div class="toast">
}, false);

// hidden.bs.toast
myTastyToast.closest('.toast').addEventListener('hidden.bs.toast', function(event){
  // do something cool
  // event.target is <div class="toast">
}, false);

Like all components of the library you can access the initialization object even if it was done via the DATA API:

// find an element initialized via DATA API
var myToastButton = document.getElementById('myToastButton');

// reference the initialization object
var myToastInit = myToastButton.Toast;

// call the public methods
myToastInit.show();
myToastInit.hide();
// or remove functionality
myToastInit.dispose();

Toast Example

This toast has some handlers attached to all its original events, so check your console.

Show Toast

Tooltip Options

The component covers most important options including a template option, and excluding some of the options featured in the original jQuery plugin such as a selector option for auto-initialization, or a trigger option. The component works different but has it's own advantages.

If your tooltip is a child element of a modal, a <nav class="navbar fixed-top"> or a <nav class="navbar fixed-bottom">, the container option is set automatically to target that specific parent.

The component also provides automatic repositioning, which means it will try to make sure the tooltips are always in the viewport, somewhat similar to the Popper.js functionality, check right here.

When your tooltip title is an HTML markup string, please make sure you sanitize the content of the markup string.

Tooltip Methods

For full control the Tooltip component exposes a couple of public methods to be used via JavaScript:

Tooltip Events

The component's original events are same as with the original jQuery Plugin, except inserted.bs.tooltip, the way the component works makes that this event is not needed, as it would fire on every instance of the .show() call.

The event.target of the original events is the target element of component, likelly your element with the data-bs-toggle="tooltip" attribute.

Tooltip DATA API

As mentioned before the component will initialize any element found to have the data-bs-toggle="tooltip" attribute and a title or a data-bs-title attribute for SVG elements.

<!-- any regular link with data-bs-toggle="tooltip" -->
<a href="https://google.com" title="Google" data-bs-toggle="tooltip">Google</a>

<!-- any SVG shape with data-bs-toggle="tooltip" -->
<svg viewBox="0 0 80 34" width="80" height="34" xmlns="http://www.w3.org/2000/svg">
  <rect data-bs-toggle="tooltip" data-bs-placement="top" data-bs-delay="150" data-bs-title="Demo Title for SVG" rx="5"></rect>
</svg>

Tooltip JavaScript API

When you insert new items in the page and want them to initialize the component or you want to have full control over your tooltips, the JavaScript way is the best one. You can also initialize for elements not having the specific DATA API, but at least have a title="Not null title" attribute. You can do the following:

// find all elements with title attribute
var elementsTooltip = document.querySelectorAll('[title]');

// attach a tooltip for each
Array.from(elementsTooltip).forEach(
  tip => new BSN.Tooltip( tip, {
    placement: 'top', // string
    animation: true, // boolean
    customClass: 'my-rocket-tooltips', // string
    sanitizeFn: function(dirty){  // use sanitizer of your choice here
      return DOMPurify.sanitize(dirty);
    }
    delay: 150, // integer
  })
)

In addition, similar to any other component of this library, you can access the initialization and the public methods even for elements initialized via DATA API.

// find an element initialized with Tooltip
var myLinkWithTooltip = document.getElementById('myLinkWithTooltip');

// reference the initialization object
var myTooltipInit = myLinkWithTooltip.Tooltip;

Considering the above element, let's go ahead and put the component's events to use:

// show.bs.tooltip
myLinkWithTooltip.addEventListener('show.bs.tooltip', function(event){
  // do some cool stuff when .show() method is called
  // event.target is myLinkWithTooltip
}, false);

// shown.bs.tooltip
myLinkWithTooltip.addEventListener('shown.bs.tooltip', function(event){
  // do some cool stuff when .show() method completed
  // event.target is myLinkWithTooltip
}, false);

// hide.bs.tooltip
myLinkWithTooltip.addEventListener('hide.bs.tooltip', function(event){
  // do some cool stuff when .hide() method is called
  // event.target is myLinkWithTooltip
}, false);

// hidden.bs.tooltip
myLinkWithTooltip.addEventListener('hidden.bs.tooltip', function(event){
  // do some cool stuff when .hide() method completed
  // event.target is myLinkWithTooltip
}, false);

Just because you can, you can re-initialize any element on the fly, to change options and / or content, or to just call the .show() method.

// re-initialize Tooltip and call .show()
new BSN.Tooltip('#selector',options).show();