Welcome to the demo page! Before you do anything, please make sure to check the Wiki pages, as they give you quick start with using the library and also provide a good set of valuable guides on how to get the best out of it.
A quick note on some of the similarities and differences with the original jQuery plugins. Nothing to worry about, but still good to know all the tricks on how to maximize your workflow.
An indepth guide on how to use it with stuff like npm
, RequireJS
or CDN links.
A short list of frequent asked questions regarding the use of the library.
A word on how to enable the library for legacy browsers.
Learn about the bootstrap.native
project inception, goals and motivations.
The Alert component covers the specific original events and public methods, but does not provide any option.
The component covers most essential JavaScript and DATA API, and does not require the class alert-dismissible
for the initialization to work.
The Alert component exposes two public methods to be used via JavaScript:
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-dismiss="alert"
attribute.
Event Type | Description |
---|---|
close.bs.alert |
This event is fired immediately when the close instance method has been called.This event can be default prevented. |
closed.bs.alert |
This event is fired when the alert has finished being hidden from the user. |
The component will initialize all elements with proper DATA API found in the DOM. Note that the
data-dismiss="alert"
attribute is required for the triggering button.
<!-- notice the <button> with the data-dismiss="alert" attribute -->
<div class="alert alert-warning alert-dismissible fade show" role="alert">
<button id="myButtonAlert" type="button" class="close" data-dismiss="alert" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
Some critical notice.
</div>
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('#myButtonAlert');
Also attach handlers to the original events:
// close.bs.alert
myButtonAlert.closest('.alert').addEventListener('close.bs.alert', function(event){
// do something cool
// event.target is <div class="alert">
}, false);
// closed.bs.alert
myButtonAlert.closest('.alert').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 myAlertButton = document.getElementById('myAlertButton');
// reference the initialization object
var myAlertInit = myAlertButton.Alert;
// apply the public methods
myAlertInit.close();
// or
myAlertInit.dispose();
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.
If you close this alert, your PC will start formatting your drive.
The Button component provides toggle functionality for checkboxes and radio buttons and a custom event for the button groups' toggling, not covered by the original jQuery plugin.
Button doesn't cover the single toggle functionality The supported toggle feature could very much fill the same purpose. The component covers accessibility features instead:
The Carousel component covers the original events, as well as a set of essential options and public methods.
In addition it also provides a solid DATA API, it adds a paused
class to the target element when in
paused state, and a solid event handling implementation.
Name | type | default | description |
---|---|---|---|
keyboard |
boolean | true | Option that allows yout to navigate the carousel with left and right arrows. If you want to
disable this feature, do that via JavaScript or the data-bs-keyboard="false" attribute. |
pause |
boolean or the text 'hover' |
'hover' | Option that makes possible to pause the carousel transition on mouse hover and touchdown. If you want to
disable pause on hover, do that via JavaScript or the data-pause="false" attribute. |
touch |
boolean | true | Option that enables support for touch events. This option is true by default, but you can
disable it via JavaScript or the data-touch="false" attribute. |
interval |
number | 5000 | Sets the component's delay between transitions in miliseconds. Can be set via JavaScript or the
data-interval="INTERVAL" attribute. If you want to disable the automatic transition, you can
set this option to false. The component will not automatically slide if the element is
not visible in the viewport. |
The Carousel component exposes two events that allow you to trigger custom functionality when the carousel slides.
All the component's events are triggered on the <div class="carousel">
element.
Both events have the following additional properties:
left
or right
.0
index).Event Type | Description |
---|---|
slide.bs.carousel |
This event fires immediately when the slideTo() instance method is called.This event can be default prevented. |
slid.bs.carousel |
This event is fired when transition has finished. |
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-ride="carousel" data-interval="5000" data-touch="true" data-pause="hover">
<!-- Indicators -->
<ol class="carousel-indicators">
<li data-target="#myCarousel" data-slide-to="0" class="active"></li>
<li data-target="#myCarousel" data-slide-to="1"></li>
<li data-target="#myCarousel" data-slide-to="2"></li>
</ol>
<!-- 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-slide="prev">
<span class="carousel-control-prev-icon" aria-hidden="true"></span>
<span class="sr-only">Prev</span>
</a>
<a class="carousel-control-next" href="#myCarousel" role="button" data-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="sr-only">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-ride="carousel"
is the attribute required if you want the Carousel component
to initialize your element on page load;data-keyboard="false"
(not shown in the sample markup) is the attribute that enables carousel
navigation via keyboard left and right arrow keys;data-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-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-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-slide-to="0"
is an attribute used by .carousel-indicators
elements, BSN
does not require this attribute in order to work, it will simply look into elements of the
.carousel-indicators
; when clicked will slide to the carousel item with the same index,
0 (zero) in this case;data-slide="prev"
/ data-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"
attribute is not required for the next and previous controls; we will see
in the example below why now 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.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:
// use getActiveIndex()
var currentActiveItem = myCarouselInit.getActiveIndex();
// jump to a certain item
myCarouselInit.slideTo(2);
// if the carousel was set with `interval: false`
// we can do this to go to the next item
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);
});
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.
These three independent buttons use some inline JavaScript to control the carousel:
<button class="btn btn-secondary"
onclick="myCarousel.Carousel.slideTo(0)">
START
</button>
<button
class="btn btn-secondary"
onclick="myCarousel.Carousel.slideTo(myCarousel.Carousel.getActiveIndex() - 1 )">
PREV
</button>
<button
class="btn btn-secondary"
onclick="myCarousel.Carousel.slideTo(myCarousel.Carousel.getActiveIndex() + 1 )">
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:
<button>
will slide to first slide<button>
will slide to PREVIOUS slide<button>
will slide to NEXT slideThe Collapse component covers the original events and methods of the jQuery plugin counterpart. This
component understands there is a triggering element that finds its target collapsible element via the
data-target="#collapse-id"
attribute or the href="#collapse-id"
attribute if it's a link.
The option below allow you to connect a collapse to a parent accordion.
Name | type | default | description |
---|---|---|---|
parent |
selector or reference |
Option to reference a parent to be used as an accordion. When a parent is set and found, it will enable
the functionality described in the show() method below. Can be set
via JavaScript or the data-parent="SELECTOR" attribute. |
Calling any of the public methods while animation is running, will produce no effect.
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.
Event Type | Description |
---|---|
show.bs.collapse |
This event fires immediately when the show instance method is called.This event can be default prevented. |
shown.bs.collapse |
This event is fired when a collapse element has been made visible to the user. |
hide.bs.collapse |
This event is fired immediately when the hide method has been called. This event can be default prevented. |
hidden.bs.collapse |
This event is fired when a collapse element has been hidden from the user. |
In the following markup, the component will initialize the two .btn
elements with the
data-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-toggle="collapse" href="#collapseExample"> <!-- required DATA API -->
Link with href
</a>
<!-- AND / OR toggle collapse via button with data-target attribute reference -->
<button id="collapseButton" class="btn btn-primary" type="button" aria-expanded="false" aria-controls="collapseExample"
data-toggle="collapse" data-target="#collapseExample"> <!-- required DATA API -->
Button with data-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="myAccordion">
<div class="card">
<div class="card-header" id="headingOne">
<h4>
<a role="button" data-toggle="collapse" data-parent="#myAccordion" href="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
Collapsible Group Item #1
</a>
</h4>
</div>
<div id="collapseOne" class="panel-collapse collapse show" aria-labelledby="headingOne">
<div class="card-body">
Collapse CONTENT 1
</div>
</div>
</div>
<div class="card">
<div class="card-header" id="headingTwo">
<h4>
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#myAccordion" href="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
Collapsible Group Item #2
</a>
</h4>
</div>
<div id="collapseTwo" class="panel-collapse collapse" aria-labelledby="headingTwo">
<div class="card-body">
Collapse CONTENT 2
</div>
</div>
</div>
<div class="card">
<div class="card-header" id="headingThree">
<h4>
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#myAccordion" href="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
Collapsible Group Item #3
</a>
</h4>
</div>
<div id="collapseThree" class="panel-collapse collapse" aria-labelledby="headingThree">
<div class="card-body">
Collapse CONTENT 3
</div>
</div>
</div>
</div>
If the above single collapse template have been inserted into the DOM, you need to initialize it via JavaScript.
// initialize the component for collapse trigger
var myCollapseInit = new BSN.Collapse('#collapseLink')
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 collapsible element
var myCollapseExample = document.getElementById(collapseLink.getAttribute('href').replace('#',''));
// attach a handler to the `show.bs.collapse` original event
myCollapseExample.addEventListener('show.bs.collapse', function(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 collapsible triggers for this accordion
var myAccordionTriggers = myAccordion.querySelectorAll('[data-toggle="collapse"]');
// initialize the component for each collapse trigger
Array.from(myAccordionTriggers).map(
collapseTrigger => new BSN.Collapse(
collapseTrigger,
{
parent: myAccordion
}
)
)
The component grants access to the initialization even for instances where the DATA API was used.
// grab the collapse trigger initialized via DATA API
var myCollapseTrigger = document.getElementById('myCollapseTrigger');
// reference the initialization
var myCollapseTriggerInit = myCollapseTrigger.Collapse;
Here's a quick demo with a single collapsible element, using the .well
as the container, exactly as
described in the Usage section. The demo also features the original events.
Here's an Accordion example, built with a set of Panels wrapped in a
<div class="panel-group">
element. 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-parent="selector"
and will hide any visible
collapsible element.
Remember that all triggering buttons must reference the accordion via data-parent="selector"
as
described above in order to collapse current opened collapsible element.
The Dropdown component covers most of the functionality from the original plugin and offers an additional option enabling the ability to handle click event in a way that you can toggle nested dropdowns and other uses.
The component supports accessibility features:
keyHandler
to support the above new features, in effect it will close the last open nested dropdown element;
Name | type | default | description |
---|---|---|---|
persist |
boolean | false | Option to keep the dropdown-menu open when click event targets a child element, useful for
forms or interactive content. Use data-persist="true" attribute to enable this functionality
via DATA-API. |
The Dropdown component covers original events. The target of all events is the
<div class="dropdown">
element, while the event.relatedTarget
can be either the
triggering element with the specific data-toggle="dropdown"
attribute or a child element
of the <div class="dropdown-menu">
element, depending on which one you click.
If you dismiss the dropdown via JavaScript, the Esc key
or by clicking outside the triggering button, the event.relatedTarget
is null.
Event Type | Description |
---|---|
show.bs.dropdown |
This event fires immediately when the show instance method is called. This event can be default prevented. |
shown.bs.dropdown |
This event is fired when the dropdown has been made visible to the user. |
hide.bs.dropdown |
This event is fired immediately when the hide instance method has been called. This event can be default prevented. |
hidden.bs.dropdown |
This event is fired when the dropdown has finished being hidden from the user. |
Notice we use same markup as the original example, the triggering element with the
data-toggle="dropdown"
attribute will initialize the Dropdown component.
<!-- basic dropdown template -->
<div class="dropdown">
<button id="myDropdown" type="button" data-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>
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 with it's 'persist' option
var myDropdownInit = new BSN.Dropdown( '#myDropdown', true );
// OR initialize component with no option
// the option is optional
var myDropdownInit = new BSN.Dropdown( '#myDropdown' );
All right, now we have an initialization reference, we can get to work with the component's methods:
// assuming the above, we can toggle
myDropdownInit.toggle();
// or we can simply re-initialize and toggle the dropdown right away
var newDropdownInitialization = 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){
// 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){
// do something when the event fires
// event.target is the PARENT of the triggering element
}, false);
// hidden.bs.dropdown
myDropdown.parentNode.addEventListener('hide.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
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.
Right out of the box, the above dropdown template is initialized via DATA-API right away.
Ok now let's insert a new dropdown-menu and initialize right after via JavaScript.
// let's do it via a click handler to the following element
var makeMeDropdown = document.getElementById('makeMeDropdown');
// let's say we have a dropdown template as the above
// you may also reference one that you created yourself
var myDropdownTemplate = '<div class="dropdown">a valid template</div>';
makeMeDropdown.addEventListener('click', function(e){
e.preventDefault();
// don't do this again
if ( !/\bdisabled/.test(makeMeDropdown.className) ){
// invalidate the makeMeDropdown
this.setAttribute('disabled',true);
this.className = 'btn btn-default disabled';
this.innerHTML = 'All done';
// we inject the dropdown
this.parentNode.innerHTML += myDropdownTemplate;
// or use appendChild when myDropdownTemplate is an Element instance
// this.parentNode.appendChild( myDropdownTemplate );
// get a reference to the new dropdown
var formDropdown = document.getElementById('formDropdown');
// initiate with option
var DropdownInit = new BSN.Dropdown(formDropdown, true);
// also attach Dropdown original events
formDropdown.parentNode.addEventListener('show.bs.dropdown', function(e){
console.log('Do something when the event fires');
}, false);
formDropdown.parentNode.addEventListener('shown.bs.dropdown', function(e){
console.log('Do something when the event fires');
}, false);
formDropdown.parentNode.addEventListener('hide.bs.dropdown', function(e){
console.log('Do something when the event fires');
}, false);
formDropdown.parentNode.addEventListener('hidden.bs.dropdown', function(e){
console.log('Do something when the event fires');
}, false);
}
}, false);
That's all there is to do with Dropdown initialization, let's check a quick demo.
A quick last example is with nested dropdown-menus, as the component will look for the child elements and will
prevent itself from closing if the click target is a child item with data-toggle
attribute.
Be sure to check the markup of the above examples and the original plugin documentation page.
The Modal component comes with small changes to options, events and public methods when compared to the original plugin. It provides an initialization option and a public method to write directly into your modal content.
In addition to adjusting the spacing (padding) of the <body>
, elements like
<nav class="navbar fixed-top">
are also adjusted in the same manner to get the smoothest possible
transition. Like all components of the library, the component grants access to the initialization object even if
your modal is automatically initialized via DATA API.
With native JavaScript we don't need the show
option because we can immediatelly access the component's
public methods right after initialiation, we'll have a look at an example in a minute.
Name | type | default | description |
---|---|---|---|
backdrop |
boolean or the string 'static' |
true | Includes a modal-backdrop element. Alternatively, specify 'static' for a backdrop which
doesn't close the modal on click. |
keyboard |
boolean | true | Option to dismiss the current modal via Esc key. |
content |
markup | The Modal component comes with a template system. This option can be used with JavaScript only. |
The default options' values are same as their jQuery plugin equivalents so you can expect same behavior.
When your modal title and/or content is in fact an HTML markup string, please make sure you sanitize the content of that markup string.
For full control the Modal component exposes a couple of public methods to be used via JavaScript :
<div class="modal-content">
element of your modal at any time, but you might want to avoid
using this method while the modal is animating. Make sure your content is sanitized..setContent()
method..dispose()
method that allow
you to remove the modal functionality from a target element. If the modal is shown, this method will
close it first by calling the .hide()
method before the removal of the functionality.All original events are triggered for the <div class="modal">
element and not the
initialization target with its usual data-toggle="modal"
attribute.
Event Type | Description |
---|---|
show.bs.modal |
This event fires immediately when the .show() method is called. If the called
came via click and the click target is a modal triggering element, that element is then marked
as the event.relatedTarget property of the event object.This event can be default prevented. |
shown.bs.modal |
This event is fired when the modal has been made visible to the user. The
event.relatedTarget is same as for the above. |
hide.bs.modal |
This event is fired immediately when the .hide() instance method has been called.This event can be default prevented. |
hidden.bs.modal |
This event is fired when the modal has finished being hidden from the user. |
If modal is opened via JavaScript methods, or by clicking on another element that is not a modal triggering
element, the relatedTarget
is null.
You can initialize Modal without writing any code as long as you have a modal and a trigger with
data-target
or a link with href
referencing that modal. The component
will initialize for all elements with data-toggle="modal"
found in the DOM.
<!-- provide a trigger button -->
<button id="myModalTrigger" type="button" data-toggle="modal" data-target="#myModal">Launch modal</button>
<!-- Alternatively provide a link -->
<a id="myModalTrigger" data-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="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">×</span></button>
</div>
<div class="modal-body">
Some content
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
<button type="button" class="btn btn-success">Save changes</button>
</div>
</div>
</div>
</div>
The DATA API is best suited for static content dialogs.
Generally you can initialize Modal for any instance of <div class="modal">
and immediately
get access to methods. Alternativelly you can initialize on a triggering element, similar to how the DATA API works,
in this case the data-toggle="modal"
is not required, but you need to specify a modal reference via a specific
attribute:
data-target="#modalId"
which is suitable for <button>
elements;href="#modalId"
which is specific for <a>
anchor link elements.The JavaScript API covers the only way to deal with dynamic content, the later added modals. 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">
<!-- the .setContent() method will update this element's HTML -->
</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
content: '<div class="modal-body">Some content to be set on init</div>', // sets modal content
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 if not specified on re-initialization AND lastly, if the modal
is open, on re-initialization the modal will be hidden via .hide()
, but you can still access the
.show()
method right away.
In other cases you can designate one or multiple triggering elements to open your modal, they will be the target of the constructor initialization and allow you to use same modal as a template to handle contents pushed by the triggering elements.
<!-- <button> referencing the modal -->
<button type="button" id="buttonID" class="btn btn-primary" data-target="#modalID">My Button</button>
<!-- <a> referencing the modal -->
<a id="anchorID" class="btn btn-primary" href="#modalID">My Link</a>
Now let's initialize one of them right away:
// initiate Modal on a triggering element
var myModalInstance = new BSN.Modal('#myButton',
{ // options object
content: '<div class="modal-body">Some content to be set on init</div>', // sets modal content
keyboard: false // we don't want to dismiss Modal on pressing Esc key
});
Now we have an initialization reference in myModalInstance
, regardless of which element is the
target of our constructor, 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();
// change the modal content
myModalInstance.setContent('<div class="modal-body">Some different content</div>');
// 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');
// also button trigger related (especially when modals are targeted by multiple triggering elements)
// a triggering element is a link
var myModal = document.getElementById(myModalTriggerButton.getAttribute('href').replace('#',''));
// OR triggering element is not a link
var myModal = document.getElementById(myModalTriggerButton.getAttribute('data-target').replace('#',''));
// 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 in the modal OR its triggering elements some references, for the internal
execution, hopefully would help you as well. For instance, when a modal is referenced by one or more triggering
elements, it will know which one was clicked last time to execute the .show()
instance method.
// for modals with multiple triggering elements, the value changes every time the triggering element was clicked
var lastModalTrigger = myModal.modalTrigger;
// for modals targeted directly by the component with no triggering element
// you can access the initialization object from the modal itself
var myModalInit = myModal.Modal;
Also each triggering element holds the initialization of the Modal component:
// when a modal was initialized via DATA API
// OR a triggering element is the target of the Modal constructor
var myModalInstance === document.getElementById('myModalTrigger').Modal;
These references are used internally to hide currently visible modals when showing another one. When the
component is used via JavaScript only without a triggering element, you need to manually hide (via
.hide()
instance method) any visible modal before showing another modal (via the .show()
instance method).
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.
The following examples are focused on everything the Modal component offers for JavaScript initialization and usage. Given a modal template and some buttons to open the modal on click, let's initialize it first:
// 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, as it has no reference to the above modal
// set a custom content
var firstModalContent = '<div class="modal-header">'
+'<h4 class="modal-title" id="myModalJSLabel">Modal title</h4>'
+'<button type="button" class="close" data-dismiss="modal" aria-label="Close">'
+'<span aria-hidden="true">×</span>'
+'</button>'
+'</div>'
+'<div class="modal-body">'
+'<p>This is where you fill up content you know, etc.</p>'
+'</div>'
+'<div class="modal-footer">'
+'<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>'
+'</div>';
// initialize Modal for this triggering element
var modalInitJS = new BSN.Modal(myModal, {
content: firstModalContent,
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;
Here is what the above code does:
Next we will initialize another triggering button, and attach a handler to it to change content of the modal when clicked.
// the triggering element
var btnModal2 = document.getElementById('openModalViaJS2');
// set some custom content or get if from external sources
var externalModalContent = {
title: 'A modal title',
content: 'Modal content to fill the modal-body.',
};
// set a custom modal-content template
var secondModalContent =
'<div class="modal-header">'
+'<h4 class="modal-title" id="gridModalLabel">' + externalModalContent.title + '</h4>'
+'<button type="button" class="close" data-dismiss="modal" aria-label="Close">'
+'<span aria-hidden="true">×</span>'
+'</button>'
+'</div>'
+'<div class="modal-body">'
+'<p>' + externalModalContent.content + '</p>'
+'</div>'
+'<div class="modal-footer">'
+'<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>'
+'</div>';
// initialize Modal for this triggering element
var modalInitJS2 = new BSN.Modal(btnModal2, { backdrop: 'static' });
// because we initialized the component for this button
// this becomes the triggering element to hold the initialization object
var modalInitJSInit2 = btnModal2.Modal;
// now when we click this modal triggering element, we change the modal content
btnModal2.addEventListener('click', function() {
modalInitJS2.setContent(secondModalContent);
}, false);
By changing the innerHTML
of the modal-header
, modal-body
or
modal-footer
with variables, you can achieve exactly the same as the
other
examples from the demo of the original plugin. So we use same modal, but with different content:
Now if you go back to the previous triggering button and click it, you will notice that the modal is still like it was set by the second triggering button. Let's reset the modal content:
// we grab the button by ID
var btnModalNotTrigger = document.getElementById('modalNotTriggerJS');
// simply attach a click handler to it
btnModalNotTrigger.addEventListener('click', function() {
modalInitJS.setContent(firstModalContent); // revert modal content back to previous
modalInitJS.show(); // also show the modal
}, false);
Back to the previous modal content:
Another example is using the .update()
method. Let's say we have a modal initialized via DATA API,
you might think we cannot access this instance's methods. Remember the trigger button
stores the initialization?
var modalUpdate = document.getElementById('modalUpdate'), // the trigger
anotherStaticModal = document.getElementById('anotherStaticModal'), // the modal
currentStaticModalBody = anotherStaticModal.querySelector('.modal-body'), // the body of the current modal
currentStaticModalBodyContent = currentStaticModalBody.innerHTML, // we cache the content of the body
modalUpdateInit = modalUpdate.Modal, // the initialization
changeModal1 = document.getElementById('changeModal1'), // the change buttons
changeModal2 = document.getElementById('changeModal2');
changeModal1.addEventListener('click', function(){
currentStaticModalBody.innerHTML = currentStaticModalBodyContent;
modalUpdateInit.update();
}, false);
changeModal2.addEventListener('click', function(){
currentStaticModalBody.innerHTML = '<h4>This modal changed via JavaScript</h4>';
currentStaticModalBody.innerHTML += '<p>Something you would want to be displayed in the body.</p>';
modalUpdateInit.update();
}, false);
A quick demo to showcase the above script:
The Popover component will initialize all elements with the data-toggle="popover"
attribute.
Unlike the original jQuery plugin, this component does not require
the Tooltip component and works just about the same except that Popover has the ability
to work with trigger options.
The component covers all needed options, including those for a template system:
Name | type | default | description |
---|---|---|---|
template |
string | Option to use a custom HTML template for your popover initialization. The contents from the
title or data-title will fill the template's .popover-header
element, while the contents of the data-content attribute will fill in the
.popover-body element.This option is JavaScript API only. |
|
content |
string | Option to set the content of the popover via JavaScript or the data-content="CONTENT"
attribute. |
|
title |
string | Option to set the title of the popover via JavaScript or the data-title="TITLE"
attribute. |
|
dismissible |
boolean | false | Option to make the popover dismissible. When true , it will also add an × button at
the top-right of the popover. You can enable this option via JavaScript API or the data-dismissible="true"
attribute. |
trigger |
string | hover | Option to change the component's action trigger event: hover , focus and click .
In some cases you may want to open a popover on focus for form elements or click for other buttons, you can specify that
via JavaScript or the data-trigger="EVENT" attribute. |
animation |
string | fade | Option to customize the component animation. If you are using a different animation other than
fade , you can specify that via the data-animation="ANIMATION"
attribute. This will add an additional CSS class to the popover to enable a custom transition. |
placement |
string | top | Option to set a specific placement to top , bottom , left or
right , relative to it's target. Can be set via both JavaScript and the
data-placement="POSITION" attribute. |
delay |
number | 200 | A short delay before hiding the popover. Can be set via JavaScript or the data-delay="DELAY" attribute. |
container |
selector or object |
<body> |
The container where your popovers get appended to. You can set the option via JavaScript or the
data-container="#elementID" attribute. |
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.
For full control the Popover component exposes a couple of public methods to be used via JavaScript:
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-toggle="popover"
attribute.
Event Type | Description |
---|---|
show.bs.popover |
This event fires immediately when the show instance method is called.This event can be default prevented. |
shown.bs.popover |
This event is fired when the popover has been made visible to the user. |
hide.bs.popover |
This event is fired immediately when the hide instance method has been called.This event can be default prevented. |
hidden.bs.popover |
This event is fired when the popover has finished being hidden from the user. |
Our component will initialize any element found to have the data-toggle="popover"
attribute and at
least the data-content
attribute.
<!-- any regular link with data-toggle="popover" -->
<a href="https://google.com" data-title="Google" data-content="Google is cool" data-toggle="popover">Google</a>
<!-- any SVG shape with data-toggle="popover" -->
<svg viewBox="0 0 80 34" width="80" height="34" xmlns="http://www.w3.org/2000/svg">
<rect data-toggle="popover" data-placement="top" data-delay="150" data-content="Demo Title for SVG" rx="5"></rect>
</svg>
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-content attribute
var popoverTargets = document.querySelectorAll('[data-content]'); // also a certain class would go fine
// initialize Popover for each element
Array.from(popoverTargets).map(
popTarget => new BSN.Popover( popTarget, {
placement: 'top', //string
animation: 'slideNfade', // CSS class
delay: 100, // integer
dismissible: true, // boolean
})
);
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:
//define some variables or get their values from other scripts
var someTitleFromOtherCode = 'Sample title';
var someContentFromOuterSpace = '<p>Some sample message.</p>';
//initiate Popover with the template
var popover2 = new BSN.Popover('.popover-via-template', { // where .popover-via-template is the text input
trigger: 'focus',
template: '<div class="popover" role="tooltip">'
+ '<div class="arrow"></div>'
+ '<h3 class="popover-header">'+someTitleFromOtherCode+'</h3>'
+ '<div class="popover-body">'+someContentFromOuterSpace+'</div>'
+ '</div>'
});
First let's test all the placement positions, we start with inline links having the bottom placement, then left, and right.
Now we are going to test buttons with a popover with large contents. The last two examples below are using the template system and different trigger options. The popover generated for the last two examples can be dismissed on window resize or blur (focus out).
The ScrollSpy component inherits some of the layout and other requirements from the original jQuery plugin in some cases, while in other cases a special markup is required. The component offers public methods, the specific original event, and provides rich JavaScript and DATA APIs.
The component will initialize for each element with data-spy="scroll"
attribute, but will not work if
the above requirements are not met or the anchors don't reference the containers accordingly.
Name | type | default | description |
---|---|---|---|
target |
string or a reference |
element '#ID' or other reference |
The option to target the container with data-spy="scroll" attribute.EG: data-target="#myMenuID" |
offset |
number | 10 | Option to set a number of pixels as offset from top when calculating position of scroll. Can be set via
data-offset="NUMBER" attribute or simply offset via JavaScript invokation. |
The event.target
is the element we initialized the component via JavaScript or has the
data-spy="scroll"
attribute. The newly activated menu item is the event.relatedTarget
of the event object.
Event Type | Description |
---|---|
activate.bs.scrollspy |
This event fires whenever a new item was activated by the component. |
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 element we initialize ScrollSpy on -->
<div data-spy="scroll" data-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:
<!-- the element we initialize ScrollSpy on -->
<div data-spy="scroll" data-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>
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.
According to the above Usage Guide let's initialize an overflowing element via DATA API:
Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.
Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.
Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.
In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.
Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.
Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats.
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.
The Tab component covers all original jQuery plugin functionality and even comes with new features such as being able to work with any kind of navigation components in Bootstrap, or providing support for height animation as you can see in the example below.
The component can initialize both via JavaScript and the DATA API, covers the original events and exposes a specific public method, but in contrast to the original plugin it offers some options for you to play with.
Name | type | default | description |
---|---|---|---|
height |
boolean | true | Option to enable animation of the height of the .tab-content tabs container. Can be set via
JavaScript or the data-height="true" attribute. |
When you set the option to true
, this enables a custom functionality that assumes you are using the
styling of the Collapse component, and the transitions styling.
Please note that in certain layouts you may need to use the clearfix
class for your
<div class="tab-content">
element to avoid inconsistent transitions. The option has no effect
on legacy browsers.
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:
Event Type | Description |
---|---|
hide.bs.tab |
This event fires when a new tab is to be shown (and thus the previous active tab is to be hidden). The
event.target is the current active tab, while event.relatedTarget
is the new soon-to-be-active tab.This event can be default prevented. |
show.bs.tab |
This event fires on tab show, but before the new tab has been shown. The event.target is
the tab next to become active and event.relatedTarget is the current
active tab (if available).This event can be default prevented. |
hidden.bs.tab |
This event fires after a new tab is shown (and thus the previous active tab is hidden). The
event.target is the tab that just became inactive and event.relatedTarget
is the new active tab. |
shown.bs.tab |
This event fires on tab show after a tab has been shown. The event.target is the new active
tab and event.relatedTarget is the previous active tab (if available). |
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-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-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-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-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-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.
Since the component will target a single element with / or without data-toggle="tab"
attribute, but
at least it references a corresponding tab via href
or
data-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).map(
tab => new BSN.Tab( tab, {height: true} )
);
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.
OK now we're ready to put this component to the test. We'll use all Bootstrap .nav
components in the
pool.
Raw denim you probably haven't heard of them jean shorts Austin. Nesciunt tofu stumptown aliqua, retro synth master cleanse. Mustache cliche tempor, williamsburg carles vegan helvetica.
Reprehenderit butcher retro keffiyeh dreamcatcher synth. Cosby sweater eu banh mi, qui irure terry richardson ex squid. Aliquip placeat salvia cillum iphone. Seitan aliquip quis cardigan american apparel, butcher voluptate nisi qui.
Food truck fixie locavore, accusamus mcsweeney's marfa nulla single-origin coffee squid. Exercitation +1 labore velit, blog sartorial PBR leggings next level wes anderson artisan four loko farm-to-table craft beer twee. Qui photo booth letterpress, commodo enim craft beer mlkshk aliquip jean shorts ullamco ad vinyl cillum PBR.
Homo nostrud organic, assumenda labore aesthetic magna delectus mollit. Keytar helvetica VHS salvia yr, vero magna velit sapiente labore stumptown. Vegan fanny pack odio cillum wes anderson 8-bit, sustainable jean shorts beard ut DIY ethical culpa terry richardson biodiesel. Art party scenester stumptown, tumblr butcher vero sint qui sapiente accusamus tattooed echo park.
Etsy mixtape wayfarers, ethical wes anderson tofu before they sold out mcsweeney's organic lomo retro fanny pack lo-fi farm-to-table readymade. Messenger bag gentrify pitchfork tattooed craft beer, iphone skateboard locavore carles etsy salvia banksy hoodie helvetica. DIY synth PBR banksy irony. Leggings gentrify squid 8-bit cred pitchfork.
Williamsburg banh mi whatever gluten-free, carles pitchfork biodiesel fixie etsy retro mlkshk vice blog. Scenester cred you probably haven't heard of them, vinyl craft beer blog stumptown. Pitchfork sustainable tofu synth chambray yr.
This tab has all events attached. Trust fund seitan letterpress, keytar raw denim keffiyeh etsy art party before they sold out master cleanse gluten-free squid scenester freegan cosby sweater. Fanny pack portland seitan DIY, art party locavore wolf cliche high life echo park Austin. Cred vinyl keffiyeh DIY salvia PBR, banh mi before they sold out farm-to-table VHS viral locavore cosby sweater.
Wolf viral, mustache readymade thundercats keffiyeh craft beer marfa ethical. Wolf salvia freegan, sartorial keffiyeh echo park vegan.
The Toast component covers the original events and its specific instance methods as well as specific options.
The component does not require the alert-dismissible
class in order to work.
For design customization and accessibility guidelines please refer back to the original plugin.
Name | type | default | description |
---|---|---|---|
animation |
boolean | true | Option to customize the component animation. If you are using a different animation other than
fade , you can specify that via the data-animation="ANIMATION" attribute.
This will add an additional CSS class to the tooltip to enable a custom transition. |
autohide |
boolean | true | Option to set a hide your toast notification automatically after being shown to the used for a
certain amount of time set below. Can be set via both JavaScript and the data-autohide="true"
attribute. |
delay |
number | 500 | A short delay before hiding the tooltip. Can be set via JavaScript or the
data-delay="DELAY" attribute. |
The Toast component exposes two public methods to be used via JavaScript:
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-toggle="toast"
attribute.
Event Type | Description |
---|---|
show.bs.toast |
This event is fired immediately when the .show() instance method has been called.This event can be default prevented. |
shown.bs.toast |
This event is fired when the toast has finished being shown to the user. |
hide.bs.toast |
This event is fired immediately when the .close() instance method has been called.This event can be default prevented. |
hidden.bs.toast |
This event is fired when the toast has finished being hidden from the user. |
The component will initialize all elements with proper markup and the specific DATA API attributes found in
the DOM. Note that the data-dismiss="toast"
attribute is required for the triggering button.
<!-- notice the <button> with the data-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 close" data-dismiss="toast" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
<div class="toast-body">
Hello, world! This is a toast message.
</div>
</div>
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();
This toast has some handlers attached to all its original events, so check your console.
Unlike the original jQuery plugin, our Tooltip component will initialize right away all elements with the
data-toggle="tooltip"
attribute. Additionally the component can do automatic placement without any
options required. At half the size of the original plugin, our component covers essential options, methods
and original events.
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.
Name | type | default | description |
---|---|---|---|
template |
string | Allows you to set a custom template for your tooltips and is not set by default. The
title="" or data-title="" attribute will fill in for the
.tooltip-inner element.This option is JavaScript API only. |
|
animation |
string | fade | Option to customize the component animation. If you are using a different animation other than
fade , you can specify that via the data-animation="ANIMATION" attribute.
This will add an additional CSS class to the tooltip to enable a custom transition. |
placement |
string | top | Option to set a specific placement to top , bottom , left or
right , relative to it's target. Can be set via both JavaScript and the
data-placement="POSITION" attribute. |
delay |
number | 200 | A short delay before hiding the tooltip. Can be set via JavaScript or the
data-delay="DELAY" attribute. |
container |
selector or object |
<body> |
The container where your tooltips get appended to. You can set the option via JavaScript or the
data-container="#elementID" attribute. |
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.
For full control the Tooltip component exposes a couple of public methods to be used via JavaScript:
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-toggle="tooltip"
attribute.
Event Type | Description |
---|---|
show.bs.tooltip |
This event fires immediately when the show instance method is called.This event can be default prevented. |
shown.bs.tooltip |
This event is fired when the tooltip has been made visible to the user. |
hide.bs.tooltip |
This event is fired immediately when the hide instance method has been called.This event can be default prevented. |
hidden.bs.tooltip |
This event is fired when the tooltip has finished being hidden from the user. |
As mentioned before the component will initialize any element found to have the
data-toggle="tooltip"
attribute and a title
or a data-title
attribute for SVG elements.
<!-- any regular link with data-toggle="tooltip" -->
<a href="https://google.com" title="Google" data-toggle="tooltip">Google</a>
<!-- any SVG shape with data-toggle="tooltip" -->
<svg viewBox="0 0 80 34" width="80" height="34" xmlns="http://www.w3.org/2000/svg">
<rect data-toggle="tooltip" data-placement="top" data-delay="150" data-title="Demo Title for SVG" rx="5"></rect>
</svg>
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).map(
tip => new BSN.Tooltip( tip, {
placement: 'top', //string
animation: 'slideNfade', // CSS class
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 or to just call the
.show()
method.
// re-initialize Tooltip and call .show()
new BSN.Tooltip('#selector',options).show();
Now let's test all the other placement positions, we start with inline links having the bottom placement, then left, and right. Let's put it to the test! Some heavy testing on the automatic repositioning with very very long tooltips.