Plugins can be included individually (using Bootstrap's individual *.js files), or all at once (using bootstrap.js or the minified bootstrap.min.js).
Using the compiled JavaScript
Both bootstrap.js and bootstrap.min.js contain all plugins in a single file. Include only one.
Plugin dependencies
Some plugins and CSS components depend on other plugins. If you include plugins individually, make sure to check for these dependencies in the docs. Also note that all plugins depend on jQuery (this means jQuery must be included before the plugin files). Consult our bower.json to see which versions of jQuery are supported.
Data attributes
You can use all Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first-class API and should be your first consideration when using a plugin.
That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the document namespaced with data-api. This looks like this:
$(document).off('.data-api')
Alternatively, to target a specific plugin, just include the plugin's name as a namespace along with the data-api namespace like this:
$(document).off('.alert.data-api')
Only one plugin per element via data attributes
Don't use data attributes from multiple plugins on the same element. For example, a button cannot both have a tooltip and toggle a modal. To accomplish this, use a wrapping element.
Programmatic API
We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.
$('.btn.danger').button('toggle').addClass('fat')
All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):
$('#myModal').modal() // initialized with defaults
$('#myModal').modal({ keyboard: false }) // initialized with no keyboard
$('#myModal').modal('show') // initializes and invokes show immediately
Each plugin also exposes its raw constructor on a Constructor property: $.fn.popover.Constructor. If you'd like to get a particular plugin instance, retrieve it directly from an element: $('[rel="popover"]').data('popover').
Default settings
You can change the default settings for a plugin by modifying the plugin's Constructor.DEFAULTS object:
$.fn.modal.Constructor.DEFAULTS.keyboard = false // changes default for the modal plugin's `keyboard` option to false
No conflict
Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call .noConflict on the plugin you wish to revert the value of.
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
Events
Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. show) is triggered at the start of an event, and its past participle form (ex. shown) is triggered on the completion of an action.
As of 3.0.0, all Bootstrap events are namespaced.
All infinitive events provide preventDefault functionality. This provides the ability to stop the execution of an action before it starts.
$('#myModal').on('show.bs.modal', function (e) {
if (!data) return e.preventDefault() // stops modal from being shown
})
Version numbers
The version of each of Bootstrap's jQuery plugins can be accessed via the VERSION property of the plugin's constructor. For example, for the tooltip plugin:
Bootstrap's plugins don't fall back particularly gracefully when JavaScript is disabled. If you care about the user experience in this case, use <noscript> to explain the situation (and how to re-enable JavaScript) to your users, and/or add your own custom fallbacks.
Third-party libraries
Bootstrap does not officially support third-party JavaScript libraries like Prototype or jQuery UI. Despite .noConflict and namespaced events, there may be compatibility problems that you need to fix on your own.
The affix plugin toggles position: fixed; on and off, emulating the effect found with position: sticky;. The subnavigation on the right is a live demo of the affix plugin.
Usage
Use the affix plugin via data attributes or manually with your own JavaScript. In both situations, you must provide CSS for the positioning and width of your affixed content.
Note: Do not use the affix plugin on an element contained in a relatively positioned element, such as a pulled or pushed column, due to a Safari rendering bug.
Positioning via CSS
The affix plugin toggles between three classes, each representing a particular state: .affix, .affix-top, and .affix-bottom. You must provide the styles, with the exception of position: fixed; on .affix, for these classes yourself (independent of this plugin) to handle the actual positions.
Here's how the affix plugin works:
To start, the plugin adds .affix-top to indicate the element is in its top-most position. At this point no CSS positioning is required.
Scrolling past the element you want affixed should trigger the actual affixing. This is where .affix replaces .affix-top and sets position: fixed; (provided by Bootstrap's CSS).
If a bottom offset is defined, scrolling past it should replace .affix with .affix-bottom. Since offsets are optional, setting one requires you to set the appropriate CSS. In this case, add position: absolute; when necessary. The plugin uses the data attribute or JavaScript option to determine where to position the element from there.
Follow the above steps to set your CSS for either of the usage options below.
Via data attributes
To easily add affix behavior to any element, just add data-spy="affix" to the element you want to spy on. Use offsets to define when to toggle the pinning of an element.
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-offset-top="200".
Name
type
default
description
offset
number | function | object
10
Pixels to offset from screen when calculating position of scroll. If a single number is provided, the offset will be applied in both top and bottom directions. To provide a unique, bottom and top offset just provide an object offset: { top: 10 } or offset: { top: 10, bottom: 5 }. Use a function when you need to dynamically calculate an offset.
target
selector | node | jQuery element
the window object
Specifies the target element of the affix.
Methods
.affix(options)
Activates your content as affixed content. Accepts an optional options object.
$('#myAffix').affix({
offset: 15
})
.affix('checkPosition')
Recalculates the state of the affix based on the dimensions, position, and scroll position of the relevant elements. The .affix, .affix-top, and .affix-bottom classes are added to or removed from the affixed content according to the new state. This method needs to be called whenever the dimensions of the affixed content or the target element are changed, to ensure correct positioning of the affixed content.
$('#myAffix').affix('checkPosition')
Events
Bootstrap's affix plugin exposes a few events for hooking into affix functionality.
Event Type
Description
affix.bs.affix
This event fires immediately before the element has been affixed.
affixed.bs.affix
This event is fired after the element has been affixed.
affix-top.bs.affix
This event fires immediately before the element has been affixed-top.
affixed-top.bs.affix
This event is fired after the element has been affixed-top.
affix-bottom.bs.affix
This event fires immediately before the element has been affixed-bottom.
affixed-bottom.bs.affix
This event is fired after the element has been affixed-bottom.
Add dismiss functionality to all alert messages with this plugin.
When using a .close button, it must be the first child of the .alert-dismissible and no text content may come before it in the markup.
Holy guacamole! Best check yo self, you're not looking too good.
Oh snap! You got an error!
Change this and that and try again. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cras mattis consectetur purus sit amet fermentum.
Usage
Just add data-dismiss="alert" to your close button to automatically give an alert close functionality. Closing an alert removes it from the DOM.
To have your alerts use animation when closing, make sure they have the .fade and .in classes already applied to them.
Methods
$().alert()
Makes an alert listen for click events on descendant elements which have the data-dismiss="alert" attribute. (Not necessary when using the data-api's auto-initialization.)
$().alert('close')
Closes an alert by removing it from the DOM. If the .fade and .in classes are present on the element, the alert will fade out before it is removed.
Events
Bootstrap's alert plugin exposes a few events for hooking into alert functionality.
Event Type
Description
close.bs.alert
This event fires immediately when the close instance method is called.
closed.bs.alert
This event is fired when the alert has been closed (will wait for CSS transitions to complete).
$('#myAlert').on('closed.bs.alert', function () {
// do something…
})
<button class="btn btn-primary" id="myButton" data-loading-text="Loading..." type="button" autocomplete="off">
Loading state
</button>
<script>
$('#myButton').on('click', function () {
var $btn = $(this).button('loading')
// business logic...
$btn.button('reset')
})
</script>
Single toggle
Add data-toggle="button" to activate toggling on a single button.
Pre-toggled buttons need .active and aria-pressed="true"
For pre-toggled buttons, you must add the .active class and the aria-pressed="true" attribute to the button yourself.
<button class="btn btn-primary" data-toggle="button" type="button" aria-pressed="false" autocomplete="off">
Single toggle
</button>
Checkbox / Radio
Add data-toggle="buttons" to a .btn-group containing checkbox or radio inputs to enable toggling in their respective styles.
Preselected options need .active
For preselected options, you must add the .active class to the input's label yourself.
Visual checked state only updated on click
If the checked state of a checkbox button is updated without firing a click event on the button (e.g. via <input type="reset"> or via setting the checked property of the input), you will need to toggle the .active class on the input's label yourself.
The carousel component is generally not compliant with accessibility standards. If you need to be compliant, please consider other options for presenting your content.
Transition animations not supported in Internet Explorer 8 & 9
Bootstrap exclusively uses CSS3 for its animations, but Internet Explorer 8 & 9 don't support the necessary CSS properties. Thus, there are no slide transition animations when using these browsers. We have intentionally decided not to include jQuery-based fallbacks for the transitions.
Initial active element required
The .active class needs to be added to one of the slides. Otherwise, the carousel will not be visible.
Glyphicon icons not necessary
The .glyphicon .glyphicon-chevron-left and .glyphicon .glyphicon-chevron-right classes are not necessarily needed for the controls. Bootstrap provides .icon-prev and .icon-next as plain unicode alternatives.
Optional captions
Add captions to your slides easily with the .carousel-caption element within any .item. Place just about any optional HTML within there and it will be automatically aligned and formatted.
First slide label
Nulla vitae elit libero, a pharetra augue mollis interdum.
Second slide label
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Third slide label
Praesent commodo cursus magna, vel scelerisque nisl consectetur.
Carousels require the use of an id on the outermost container (the .carousel) for carousel controls to function properly. When adding multiple carousels, or when changing a carousel's id, be sure to update the relevant controls.
Via data attributes
Use data attributes to easily control the position of the carousel. data-slide accepts the keywords prev or next, which alters the slide position relative to its current position. Alternatively, use data-slide-to to pass a raw slide index to the carousel data-slide-to="2", which shifts the slide position to a particular index beginning with 0.
The data-ride="carousel" attribute is used to mark a carousel as animating starting at page load. It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.
Via JavaScript
Call carousel manually with:
$('.carousel').carousel()
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-interval="".
Name
type
default
description
interval
number
5000
The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
pause
string
"hover"
Pauses the cycling of the carousel on mouseenter and resumes the cycling of the carousel on mouseleave.
wrap
boolean
true
Whether the carousel should cycle continuously or have hard stops.
keyboard
boolean
true
Whether the carousel should react to keyboard events.
Methods
.carousel(options)
Initializes the carousel with an optional options object and starts cycling through items.
$('.carousel').carousel({
interval: 2000
})
.carousel('cycle')
Cycles through the carousel items from left to right.
.carousel('pause')
Stops the carousel from cycling through items.
.carousel(number)
Cycles the carousel to a particular frame (0 based, similar to an array).
.carousel('prev')
Cycles to the previous item.
.carousel('next')
Cycles to the next item.
Events
Bootstrap's carousel class exposes two events for hooking into carousel functionality.
Both events have the following additional properties:
direction: The direction in which the carousel is sliding (either "left" or "right").
relatedTarget: The DOM element that is being slid into place as the active item.
All carousel events are fired at the carousel itself (i.e. at the <div class="carousel">).
Event Type
Description
slide.bs.carousel
This event fires immediately when the slide instance method is invoked.
slid.bs.carousel
This event is fired when the carousel has completed its slide transition.
$('#myCarousel').on('slide.bs.carousel', function () {
// do something…
})
The checkbox control provides a customized look and feel that can be standardized across all browsers.
Usage
Via JavaScript
Initialize the checkbox control via JavaScript:
$('#myCheckbox').checkbox();
Via data-attributes
Checkbox input elements that exist when $.ready() executes that have data-initialize="checkbox" on their parent will be initialized immediately.
Checkbox input elements that are created with data-initialize="checkbox" after $.ready() executes will initialize when a mouseover event occurs on them.
Deprecated checkbox markup
Before v3.8.0, the checkbox control could be bound with $().checkbox(); or data-initialize="checkbox" to the div.checkbox or the input elements. This is no longer supported. Please update your markup and JavaScript to be bound to the label only.
Methods
Once your checkbox is initialized, you can execute any of the following methods on it:
.checkbox('check')
Ensures the checkbox is checked.
.checkbox('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup as close to it's pre-initialization state as possible.
.checkbox('disable')
Ensures the checkbox is disabled.
.checkbox('enable')
Ensures the checkbox is enabled.
.checkbox('isChecked')
Returns true or false indicating the checked state of the checkbox.
.checkbox('toggle')
Toggles the checkbox between checked/unchecked states.
.checkbox('uncheck')
Ensures the checkbox is unchecked.
Events
Event Type
Description
enabled.fu.checkbox
Event fires when checkbox is enabled
disabled.fu.checkbox
Event fires when checkbox is disabled
checked.fu.checkbox
Event fires when checkbox is checked
unchecked.fu.checkbox
Event fires when checkbox is unchecked
All checkbox events are fired on the .checkbox classed element. However, unlike the majority of Fuel UX controls, it is recommended to listen to and check the state of the checkbox control by listening to the native checkbox with the change event and check its status with the presence of the checked attribute. For the sample markup provided, this would be:
$('.checkbox input').on('change', function () {
console.log( $(this).is(':checked') );
});
Use the data-toggle="{{selector}}" to automatically show or hide elements matching the selector within the body upon check or uncheck. This control works with any jQuery selector.
Use the .highlight class to add a background highlight upon check.
<div class="checkbox highlight" id="myCheckbox10">
<label class="checkbox-custom highlight" data-initialize="checkbox">
<input class="sr-only" type="checkbox" value="option1">
This control highlights a block-level checkbox on check
</label>
</div>
<label class="checkbox-custom checkbox-inline highlight" id="myCheckbox11" data-initialize="checkbox">
<input class="sr-only" type="checkbox" value="option2">
This control highlights an inline checkbox on check
</label>
Events
Unlike the majority of Fuel UX controls, it is recommended to listen to and check the state of the checkbox control by listening to the native checkbox with the change event and check its status with the presence of the checked attribute. For the sample markup provided, this would be:
$('.checkbox input').on('change', function () {
console.log( $(this).is(':checked') );
});
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident.
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
<div class="panel-group" id="accordion" role="tablist" aria-multiselectable="true">
<div class="panel panel-default">
<div class="panel-heading" id="headingOne" role="tab">
<h4 class="panel-title">
<a data-toggle="collapse" data-parent="#accordion" role="button" href="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
Collapsible Group Item #1
</a>
</h4>
</div>
<div class="panel-collapse collapse in" id="collapseOne" role="tabpanel" aria-labelledby="headingOne">
<div class="panel-body">
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
</div>
</div>
</div>
<div class="panel panel-default">
<div class="panel-heading" id="headingTwo" role="tab">
<h4 class="panel-title">
<a class="collapsed" data-toggle="collapse" data-parent="#accordion" role="button" href="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
Collapsible Group Item #2
</a>
</h4>
</div>
<div class="panel-collapse collapse" id="collapseTwo" role="tabpanel" aria-labelledby="headingTwo">
<div class="panel-body">
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
</div>
</div>
</div>
<div class="panel panel-default">
<div class="panel-heading" id="headingThree" role="tab">
<h4 class="panel-title">
<a class="collapsed" data-toggle="collapse" data-parent="#accordion" role="button" href="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
Collapsible Group Item #3
</a>
</h4>
</div>
<div class="panel-collapse collapse" id="collapseThree" role="tabpanel" aria-labelledby="headingThree">
<div class="panel-body">
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
</div>
</div>
</div>
</div>
It's also possible to swap out .panel-bodys with .list-groups.
Be sure to add aria-expanded to the control element. This attribute explicitly defines the current state of the collapsible element to screen readers and similar assistive technologies. If the collapsible element is closed by default, it should have a value of aria-expanded="false". If you've set the collapsible element to be open by default using the in class, set aria-expanded="true" on the control instead. The plugin will automatically toggle this attribute based on whether or not the collapsible element has been opened or closed.
Additionally, if your control element is targetting a single collapsible element – i.e. the data-target attribute is pointing to an id selector – you may add an additional aria-controls attribute to the control element, containing the id of the collapsible element. Modern screen readers and similar assistive technologies make use of this attribute to provide users with additional shortcuts to navigate directly to the collapsible element itself.
Usage
The collapse plugin utilizes a few classes to handle the heavy lifting:
.collapse hides the content
.collapse.in shows the content
.collapsing is added when the transition starts, and removed when it finishes
These classes can be found in component-animations.less.
Via data attributes
Just add data-toggle="collapse" and a data-target to the element to automatically assign control of a collapsible element. The data-target attribute accepts a CSS selector to apply the collapse to. Be sure to add the class collapse to the collapsible element. If you'd like it to default open, add the additional class in.
To add accordion-like group management to a collapsible control, add the data attribute data-parent="#selector". Refer to the demo to see this in action.
Via JavaScript
Enable manually with:
$('.collapse').collapse()
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-parent="".
Name
type
default
description
parent
selector
false
If a selector is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this is dependent on the panel class)
toggle
boolean
true
Toggles the collapsible element on invocation
Methods
.collapse(options)
Activates your content as a collapsible element. Accepts an optional options object.
$('#myCollapsible').collapse({
toggle: false
})
.collapse('toggle')
Toggles a collapsible element to shown or hidden. Returns to the caller before the collapsible element has actually been shown or hidden (i.e. before the shown.bs.collapse or hidden.bs.collapse event occurs).
.collapse('show')
Shows a collapsible element. Returns to the caller before the collapsible element has actually been shown (i.e. before the shown.bs.collapse event occurs).
.collapse('hide')
Hides a collapsible element. Returns to the caller before the collapsible element has actually been hidden (i.e. before the hidden.bs.collapse event occurs).
Events
Bootstrap's collapse class exposes a few events for hooking into collapse functionality.
Event Type
Description
show.bs.collapse
This event fires immediately when the show instance method is called.
shown.bs.collapse
This event is fired when a collapse element has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.collapse
This event is fired immediately when the hide method has been called.
hidden.bs.collapse
This event is fired when a collapse element has been hidden from the user (will wait for CSS transitions to complete).
$('#myCollapsible').on('hidden.bs.collapse', function () {
// do something…
})
The combobox control combines an input and a drop-down for easy and flexible data selection. Combobox also offers many methods that allow you to programmatically manipulate it.
Add data-initialize="combobox" to the .combobox element that you wish to initialize on $.ready(). Any combobox that is programmatically generated after the initial page load will initialize when the mousedown event is fired on it if it has data-initialize="combobox".
Markup
A combobox consists of an input group containing a text input with a selectlist appended to it.
The following options are applicable to the li elements of the selectlist. Append the option name to data-, as in data-selected="true".
Name
type
default
description
selected
boolean
false
Indicates element should be selected by default.
Programmatic options
Should be passed in as an object (eg. {name: value}) on intialization. Javascript initialization is required (you can't initialize through data-attributes) if you would like to use this.
Name
type
default
description
autoResizeMenu
boolean
true
Resizes the drop-down menu to the width of the combobox
Methods
Once your combobox is initialized, you can execute any of the following methods on it:
.combobox('destroy')
Remove all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.combobox('disable')
Disable the combobox
.combobox('enable')
Enable the combobox
.combobox('selectedItem')
Returns an object containing a text property with the visible text of the selected item as well as the results of a jQuery .data() call on the selected item (which will map the contents of any data-* attributes into the returned object).
Set the selected item based on its value. Convenience method for .selectBySelector('data-value={value}') that requires the item to include a .data-value="{value}" attribute
$('#myCombobox').combobox('selectByValue', '1');
Events
Event Type
Description
changed.fu.combobox
This event fires when the value changes (either by selecting an item from the list or updating the input value directly). Arguments include event, data where data represents the same object structure returned by the selectedItem method.
All combobox event listeners should be attached to the element containing the combobox class; given the following HTML:
The dropdown-menu-right class on the ul in the example markup causes the drop-down menu to appear directly underneath the dropdown, its right side appearing flush with the right side of the triggering element. If you wish the dropdown menu's left side to align with the left side of the triggering button's left side, exclude the dropdown-menu-right class on the ul.
The datepicker() control provides the user with the ability to choose a date from a highly customizable calender. Datepicker also offers many methods that allow you to programmatically manipulate it.
Usage
Via JavaScript
Initialize the datepicker() via JavaScript (accepting default options):
$('#myDatepicker').datepicker();
Initialize the datepicker() via JavaScript specifying your own options:
Datepicker controls that exist when $().ready() executes that have data-initialize="datepicker" on them will be initialized immediately
Datepicker controls that are created with data-initialize="datepicker" after $.ready() executes will initialize when a mousedown event occurs on them.
Markup
The datepicker() markup is complex and specific. On initialization, the datepicker() plugin searches inside of the specified element for the components used to build the control. For your convenience, we have written the required markup for you. Writing custom datepicker() markup is not recommended; if you choose to do so, understanding the datepicker.js code will be necessary.
Dictates whether past dates can be input or selected by the user.
date
Date object, string, or falsy value ('', null, or false)
new Date()
Specifies the date that is set upon initialization. If using a string, the format must be a
valid date string as supported by the browser or by moment.js if available. Falsy values will result
in no date being set upon initialization.
formatDate
function or null
null
Function that is called for formatting a valid date object. Should only be overriden if the
datepicker's default formatDate method is not sufficient for your needs. The formatDate function takes
a date object as an argument, and should return a string.
momentConfig
object
{ culture: 'en', format: 'L' }
Settings used to configure moment.js, if available. Both culture and format
attributes must be present for moment features to be utilized. The culture attribute is a string
representing the desired datepicker() language. The format attribute is a string representing the
desired date format that appears in the input upon date selection. Consult the moment.js
docs for more information on supported cultures and formats.
parseDate
function or null
null
Function that is called for parsing date strings input by the user. Should only be overriden if the
datepicker's default parseDate method is not sufficient for your needs. The parseDate function takes a
date object, string, or falsy value as an argument, and should return either a valid date object representing
the successfully parsed value or invalid date object (new Date(NaN))
restricted
array
[]
Specifies dates that are restricted from user input and selection. Uses an array of objects to provide
the ranges. Each of the object must have the following format: { from: '03/31/2015', to: '03/31/2016' }, but multiple ranges are supported. The from attribute represents the start date of the restricted range, and the to attribute represents the end date of the range, inclusively. Both attributes can be set to either a valid date
string or a date object. -Infinity and Infinity are valid delimiters. View this gist to see how to set the datepicker to only allow dates from the past 365 days.
sameYearOnly
boolean
false
Prevents the user from selecting dates outside the current year if true.
twoDigitYearProtection
boolean
true
Attempts to accommodate for people entering two digit years. Only works if moment is being used to parse date. Otherwise browser parsing is used (which is inconsistent)
Date Parsing and MomentJS
MomentJS parsing is the same format for the API as the output within the input element. Datepicker's default MomentJS locale is regionalistic (American). If you are using MomentJS (and it is recommended that you do), option strings such as those within restricted date ranges expect the format that you provide within momentConfig. Locales and formats are available in the MomentJS documentation. The default locale configuration is momentConfig: { culture: 'en', format: 'L' }
Therefore if you do not specify your own locale and format, restricted will be expecting an array of objects of the'MM/DD/YYYY' format--that is the 'L' MomentJS format. An example of this would be restricted: [{ from: '08/10/2014', to: '08/15/2014' }]
Methods
.datepicker('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.datepicker('disable')
Ensures the component is disabled
.datepicker('enable')
Ensures the component is enabled
.datepicker('getDate')
Returns the selected date (not formatted)
.datepicker('getFormattedDate')
Returns the selected formatted date
.datepicker('setDate')
Sets datepicker() to date provided. Date provided must be a valid Date object or date string.
$('#myDatepicker').datepicker('setDate', new Date());
.datepicker('getCulture')
Returns the culture the datepicker() is currently using. Only available using moment.js with langs
.datepicker('setCulture')
Updates the culture the datepicker() uses. Only available using moment.js with langs
Returns the format the datepicker() is currently using. Only available using moment.js with langs
.datepicker('setFormat')
Updates the format the datepicker() uses. Only available using moment.js with langs
$('#myDatepicker').datepicker('setFormat', 'L');
Events
Event Type
Description
changed.fu.datepicker
This event is fired when the date value has been changed by the user inputing text into the input box. Choosing the date by clicking in the datepicker will not fire this event. Arguments include event, date where date is a JavaScript Date object.
dateClicked.fu.datepicker
This event is fired when a day has been selected on the calendar. Arguments include event, date where date is a JavaScript Date object.
inputParsingFailed.fu.datepicker
This event is fired when an invalid date is parsed on blur of the datepicker. Arguments include event, date where date is a JavaScript Date object.
inputRestrictedDate.fu.datepicker
This event is fired when an restricted date is parsed on blur of the datepicker. Arguments include event, date where date is a JavaScript Date object.
All datepicker() events are fired on the .datepicker classed element.
$('#myDatepicker').on('changed.fu.datepicker', function (evt, date) {
// do something…
});
To listen for changes on the Date() object, you will need to combine two listeners (as shown below). The reason for this is to keep double events firing when a date is clicked (previously when a date was clicked dateClicked and changed would both fire, which was confusing to many people.
$('#myDatepicker').on('changed.fu.datepicker dateClicked.fu.datepicker', function (evt, date) {
// do something…
});
To listen for all changes to the datepicker's input value, including setting the date to invalid values, you will need to combine two listeners:
$('#myDatepicker').on('change dateClicked.fu.datepicker', function (evt, date) {
// do something…
});
Examples
Choose a date from a calendar dropdown, with input parsing and formatting. Works with moment.js for extended functionality.
Additional functionality added to drop-down menus that enables dropup menus instead of drop-down menus based on screen position.
Examples
Add data-flip="auto" to a drop-down trigger data-toggle="drop-down". (You may need to scroll up to trigger this functionality.) Place this menu at the bottom of the screen to implement a drop-up menu.
By default, Fuel UX automatically positions the drop-down menu 100 percent from the top and along the right side of its parent. Remove .dropdown-menu-right to a .dropdown-menu to left align the drop-down menu.
Usage
The dropdown-autoflip add-on determines whether to show a drop-down menu or a dropup menu by calculating the position on the screen and the edge of the viewport. If the positioning requires a drop-up menu, add .dropup to the .dropdown-menu element.
Markup
Add data-flip="auto" to a drop-down menu within a class="fuelux" container.
Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the .open class on the parent list item.
On mobile devices, opening a dropdown adds a .dropdown-backdrop as a tap area for closing dropdown menus when tapping outside the menu, a requirement for proper iOS support. This means that switching from an open dropdown menu to a different dropdown menu requires an extra tap on mobile.
Note: The data-toggle="dropdown" attribute is relied on for closing dropdown menus at an application level, so it's a good idea to always use it.
Via data attributes
Add data-toggle="dropdown" to a link or button to toggle a dropdown.
Regardless of whether you call your dropdown via JavaScript or instead use the data-api, data-toggle="dropdown" is always required to be present on the dropdown's trigger element.
Options
None
Methods
$().dropdown('toggle')
Toggles the dropdown menu of a given navbar or tabbed navigation.
Events
All dropdown events are fired at the .dropdown-menu's parent element.
All dropdown events have a relatedTarget property, whose value is the toggling anchor element.
Event Type
Description
show.bs.dropdown
This event fires immediately when the show instance method is called.
shown.bs.dropdown
This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete).
hide.bs.dropdown
This event is fired immediately when the hide instance method has been called.
hidden.bs.dropdown
This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete).
$('#myDropdown').on('show.bs.dropdown', function () {
// do something…
})
Plugins can be included individually (using Jasny Bootstrap's individual *.js files), or all at once (using jasny-bootstrap.js or the minified jasny-bootstrap.min.js).
The Jasny Bootstrap plugins work with or without loading vanilla Bootstrap's bootstrap.js.
Do not attempt to include both.
Both jasny-bootstrap.js and jasny-bootstrap.min.js contain all plugins in a single file.
Data attributes
You can use all Jasny Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first-class API and should be your first consideration when using a plugin.
That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the document namespaced with data-api. This looks like this:
$(document).off('.data-api')
Alternatively, to target a specific plugin, just include the plugin's name as a namespace along with the data-api namespace like this:
$(document).off('.alert.data-api')
Programmatic API
We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.
$(".fileinput").fileinput().addClass("fat")
All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):
$("#myMenu").offcanvas() // initialized with defaults
$("#myMenu").offcanvas({ autohide: false }) // initialized with no autohide
$("#myMenu").offcanvas('show') // initializes and invokes show immediately
Each plugin also exposes its raw constructor on a Constructor property: $.fn.popover.Offcanvas. If you'd like to get a particular plugin instance, retrieve it directly from an element: $('.navmenu').data('offcanvas').
No conflict
Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call .noConflict on the plugin you wish to revert the value of.
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
Events
Bootstrap provides custom events for most plugin's unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. show) is triggered at the start of an event, and its past participle form (ex. shown) is trigger on the completion of an action.
As of 3.1.2, all Bootstrap events are namespaced.
All infinitive events provide preventDefault functionality. This provides the ability to stop the execution of an action before it starts.
$('#myMenu').on('show.bs.offcanvas', function (e) {
if (!data) return e.preventDefault() // stops menu from being shown
})
Off canvas offcanvas.js
Example
The offcanvas plugin allows you to hide an element from sight and than show it by moving either that or any other element. It's intended to be used for off canvas navigation, like push menus.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis in aliquet nisl. Praesent sed leo congue, fringilla eros eu, tempus metus. Nam mollis odio ipsum, non vehicula ipsum accumsan sodales. Morbi varius vitae elit euismod cursus. Donec a dapibus justo, in facilisis nisi. Suspendisse ut turpis dui. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque dui risus, tincidunt at odio ut, ultrices dignissim ipsum. Cras ultrices erat nec leo luctus varius. Nulla sollicitudin tincidunt nulla, ut porta mauris volutpat vitae. Suspendisse ornare dolor sit amet massa venenatis pulvinar.
Add .offcanvas to hide an element. Alternatively add .offcanvas-* to hide an element up to a specific viewport width. Adding the .offcanvas class is not required. You may also hide an element by any other means.
The effect works best for elements positioned to the top, bottom, left or right of the window, either with absolute or fixed positioning.
When shown, the plugin adds .canvas-slid to the element that has slid.
Via data attributes
Add data-toggle="offcanvas" and a data-target to control, assigning it to show and hide the target element. The data-target attribute accepts a CSS selector to apply the collapse to.
Optionally add a data-canvas attribute to slide a canvas instead of only the target element. For a push menu set data-canvas="body".
Via JavaScript
Call the input mask via javascript:
$('.navmenu').offcanvas()
Options
Name
type
default
description
canvas
string
false
If set, the canvas will be moved on show and hide instead of the target element. This creates alternative effects.
toggle
boolean
true
Toggles the off canvas element on invocation
placement
string
'auto'
Where to position the element at the start of the animation. For example, if placement is "left", the element will slide from left to right. The default option "auto" guesses the placement based on position and dimension.
autohide
boolean
true
Hide the off canvas element if clicked anywhere other that the element.
recalc
boolean
true
Calculate if off canvas should be disabled for this viewport width on window resize. If your elements always gets hidden on window resize, try setting this to false.
disableScrolling
boolean
true
Disable scrolling when the off canvas element is shown, by setting overflow to hidden for the body.
Graceful degradation
For browsers that don't support transform (mainly IE8), the target option is ignored. In that case, the plugin will always slide the target element. In that case .canvas-slid will be added to the target element instead.
Methods
.offcanvas(options)
Initializes the off canvas element with an optional options.
.offcanvas('toggle')
Toggles an off canvas element to shown or hidden.
.offcanvas('show')
Shows an off canvas element.
.offcanvas('hide')
Hides an off canvas element.
Events
Event Type
Description
show.bs.offcanvas
This event fires immediately when the show instance method is called.
shown.bs.offcanvas
This event is fired when the target has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.offcanvas
This event is fired immediately when the hide instance method has been called.
hidden.bs.offcanvas
This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).
Row link rowlink.js
Example
This plugin turns a table row into a clickable link.
This modal proves that JavaScript events are triggered correctly by rowlink.
<table class="table table-striped table-bordered table-hover">
<thead>
<tr><th>Name</th><th>Description</th><th>Actions</th></tr>
</thead>
<tbody class="rowlink" data-link="row">
<tr><td><a href="#inputmask">Input mask</a></td><td>Input masks can be used to force the user to enter data conform a specific format.</td><td class="rowlink-skip"><a href="#">Action</a></td></tr>
<tr><td><a href="http://www.jasny.net/" target="_blank">jasny.net</a></td><td>Shared knowledge of Arnold Daniels aka Jasny.</td><td class="rowlink-skip"><a href="#">Action</a></td></tr>
<tr><td><a data-toggle="modal" href="#rowlinkModal">Launch modal</a></td><td>Toggle a modal via JavaScript by clicking this row.</td><td class="rowlink-skip"><a href="#">Action</a></td></tr>
</tbody>
</table>
Usage
Via data attributes
Add class .rowlink and attribute data-link="row" to a <table> or <tbody> element. For other options append the name to data-, as in data-target="a.mainlink" A cell can be excluded by adding the .rowlink-skip class to the <td>.
Via JavaScript
Call the input mask via javascript:
$('tbody.rowlink').rowlink()
Options
Name
type
default
description
target
string
'a'
A jquery selector string, to select the link element within each row.
Methods
.rowlink(options)
Makes the rows of a table or tbody clickable.
Input mask inputmask.js
Example
Input masks can be used to force the user to enter data conform a specific format. Unlike validation, the user can't enter any other key than the ones specified by the mask.
Image preview only works in IE10+, FF3.6+, Safari6.0+, Chrome6.0+ and Opera11.1+. In older browsers the filename is shown instead.
Usage
Add .fileinput to the container. Elements inside the container with .fileinput-new and .fileinput-exists are shown or hidden based on the current state. A preview of the selected file is placed in .fileinput-preview. The text of .fileinput-filename gets set to the name of the selected file.
The file input widget should be placed in a regular <form> replacing a standard <input type="file">. The server side code should handle the file upload as normal.
Via data attributes
Add data-provides="fileinput" to the .fileinput element. Implement a button to clear the file with data-dismiss="fileinput". Add data-trigger="fileinput" to any element within the .fileinput widget to trigger the file dialog.
Via JavaScript
$('.fileinput').fileinput()
Layout
Using the given elements, you can layout the upload widget the way you want, either with a fixed width and height or with max-width and max-height.
Options
Name
type
description
name
string
Use this option instead of setting the name attribute on the <input> element to prevent it from being part of the post data when not changed.
Methods
.fileinput(options)
Initializes a file upload widget.
.fileinput('clear')
Clear the selected file.
.fileinput('reset')
Reset the form element to the original value.
Events
Event Type
Description
change.bs.fileinput
This event is fired after a file is selected.
clear.bs.fileinput
This event is fired when the file input is cleared.
You can pass options via JavaScript at initialization.
Name
type
default
description
dataSource
function
null
Called whenever the user scrolls the specified percentage towards the bottom. Arguments passed
include a helpers object and callback function. The helpers
object contains current percentage and scrollTop values. The
callback function appends more content to the element. Pass an object
back within the callback function structured as follows:
{ content: '...' }
If you append no additonal content, add the attribute end: true to that
object. This code will append ''
.infinitescroll('fetchData');
Tells the infinite scrolling region to make a call to its dataSource for additional content.
Animation for visual indication of waiting time that can be customized to have many appearances.
Usage
Via JavaScript
Call the loader control via JavaScript:
$('#myLoader').loader();
Via data-attributes
To enable the loader control without writing JavaScript, add data-initialize="loader" to the .loader element that you wish to initialize. Such elements that exist when $.ready() executes will be initialized.
Use the data-frame attribute to set the initial animation frame (defaults to 1). Additionally, this attribute can be modified at any time to set the current frame.
Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.
Multiple open modals not supported
Be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code.
Modal markup placement
Always try to place a modal's HTML code in a top-level position in your document to avoid other components affecting the modal's appearance and/or functionality.
Due to how HTML5 defines its semantics, the autofocus HTML attribute has no effect in Bootstrap modals. To achieve the same effect, use some custom JavaScript:
$('#myModal').on('shown.bs.modal', function () {
$('#myInput').focus()
})
Examples
Static example
A rendered modal with header, body, and set of actions in the footer.
Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.
Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.
Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.
Be sure to add role="dialog" and aria-labelledby="...", referencing the modal title, to .modal, and role="document" to the .modal-dialog itself.
Additionally, you may give a description of your modal dialog with aria-describedby on .modal.
Embedding YouTube videos
Embedding YouTube videos in modals requires additional JavaScript not in Bootstrap to automatically stop playback and more. See this helpful Stack Overflow post for more information.
Optional sizes
Modals have two optional sizes, available via modifier classes to be placed on a .modal-dialog.
Have a bunch of buttons that all trigger the same modal, just with slightly different contents? Use event.relatedTarget and HTML data-* attributes (possibly via jQuery) to vary the contents of the modal depending on which button was clicked. See the Modal Events docs for details on relatedTarget,
$('#exampleModal').on('show.bs.modal', function (event) {
var button = $(event.relatedTarget) // Button that triggered the modal
var recipient = button.data('whatever') // Extract info from data-* attributes
// If necessary, you could initiate an AJAX request here (and then do the updating in a callback).
// Update the modal's content. We'll use jQuery here, but you could use a data binding library or other methods instead.
var modal = $(this)
modal.find('.modal-title').text('New message to ' + recipient)
modal.find('.modal-body input').val(recipient)
})
Usage
The modal plugin toggles your hidden content on demand, via data attributes or JavaScript. It also adds .modal-open to the <body> to override default scrolling behavior and generates a .modal-backdrop to provide a click area for dismissing shown modals when clicking outside the modal.
Via data attributes
Activate a modal without writing JavaScript. Set data-toggle="modal" on a controller element, like a button, along with a data-target="#foo" or href="#foo" to target a specific modal to toggle.
Call a modal with id myModal with a single line of JavaScript:
$('#myModal').modal(options)
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-backdrop="".
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
Closes the modal when escape key is pressed
show
boolean
true
Shows the modal when initialized.
remote
path
false
This option is deprecated since v3.3.0 and has been removed in v4. We recommend instead using client-side templating or a data binding framework, or calling jQuery.load yourself.
If a remote URL is provided, content will be loaded one time via jQuery's load method and injected into the .modal-content div. If you're using the data-api, you may alternatively use the href attribute to specify the remote source. An example of this is shown below:
Activates your content as a modal. Accepts an optional options object.
$('#myModal').modal({
keyboard: false
})
.modal('toggle')
Manually toggles a modal. Returns to the caller before the modal has actually been shown or hidden (i.e. before the shown.bs.modal or hidden.bs.modal event occurs).
$('#myModal').modal('toggle')
.modal('show')
Manually opens a modal. Returns to the caller before the modal has actually been shown (i.e. before the shown.bs.modal event occurs).
$('#myModal').modal('show')
.modal('hide')
Manually hides a modal. Returns to the caller before the modal has actually been hidden (i.e. before the hidden.bs.modal event occurs).
$('#myModal').modal('hide')
.modal('handleUpdate')
Readjusts the modal's positioning to counter a scrollbar in case one should appear, which would make the modal jump to the left.
Only needed when the height of the modal changes while it is open.
$('#myModal').modal('handleUpdate')
Events
Bootstrap's modal class exposes a few events for hooking into modal functionality.
All modal events are fired at the modal itself (i.e. at the <div class="modal">).
Event Type
Description
show.bs.modal
This event fires immediately when the show instance method is called. If caused by a click, the clicked element is available as the relatedTarget property of the event.
shown.bs.modal
This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the relatedTarget property of the event.
hide.bs.modal
This event is fired immediately when the hide instance method has been called.
hidden.bs.modal
This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).
loaded.bs.modal
This event is fired when the modal has loaded content using the remote option.
$('#myModal').on('hidden.bs.modal', function (e) {
// do something...
})
A pillbox allows user tag management enabling features such as typeahead and tag editing.
Via JavaScript
Call the Pillbox via JavaScript:
$('#myPillbox').pillbox();
Via data-attributes
The pillbox will automatically instantiate any pillboxes with data-initialize="pillbox". If the control markup is added after page load with data-initialize="pillbox", this control will be initialized on mousedown.
Markup
Add class="pillbox" to a div within a class="fuelux" container.
The position where to start inserting pill(s). First pane is at position 1. If omitted, or if -1 is used, the item will be appended to end of the list of pills.
[item1, ..., itemX] item1, ..., itemX
An array or list of pill objects to be added at the index. See the following table for an overview of the pill object.
Pill object key
Type
Description
text
string
Required. Text of pillbox
value
string
A value stored in the data-value of the pill markup and returned with events
attr
object
Unless it is a reserved key in this table, child keys will be added as attributes to .pill.
attr.cssClass
string
CSS classes that will be added to .pill
data
object
An object of key/value pairs that can be stored in the jQuery data of a pill
.pillbox('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.pillbox('removeItems')
Removes all items from the pillbox.
$('#myPillbox').pillbox('removeItems');
Remove one or more items at a specific position in the pillbox by passing optional parameters. The first parameter is a 1 based index that represent the location of the first element to be removed. The second parameter is the number of items that will be removed.
Returns an array of objects, one per item, each containing the jQuery data() contents of the item which includes data-* attributes plus a text property with the label's visible text.
.pillbox('itemCount')
Returns an integer representing the current number of items.
.pillbox('readonly')
Enables or disables readonly mode for the pillbox.
Removes an item with value matching that of the provided value string parameter. The item has to have a .data-value="{value}" attribute
$('#myPillbox').pillbox('removeByValue', '1');
Options
Control options below can only be set via JavaScript. Values needed to identify which pill caused an event should be stored in data-attributes within the .pill element, as in data-value="".
Name
type
default
description
acceptKeyCodes
array
[13, 188]
Key codes for keys that trigger an add pill event. Default keys 13 (for enter) and 188 (for comma).
edit
boolean
false
Enables user edited pills.
onAdd
function
undefined
A callback function that executes when a pill is added. function(data,callback){}
The data parameter contains an array of the elements being added.
The callback parameter is a function that provides asynchronous support for the add functionality.
In order for items to be added, the callback must be run and provided an array of items to be added.
If you would like to not modify the list of items to be added, provide data as the parameter for the callback function, callback(data).
onRemove
function
undefined
Function that runs when a pill is removed.
function(data,callback){}
The data parameter contains an array of the elements being removed.
The callback parameter is a function that provides asynchronous support for the remove functionality.
In order for items to be removed, the callback must be run and provided an array of items to be removed.
If you would not like to modify the list of items to be removed, provide data as the parameter for the callback function, callback(data).
onKeyDown
function
undefined
Function that executes when a keydown event is triggered.
function(event,data,callback){}
The event parameter contains the event object.
The data parameter contains an array of the elements being removed.
The callback parameter is a function that provides asynchronous support for the typeahead functionality.
The callback function must be run in order for the typeahead dropdown with values. Provided the callback with an array of items to display in the typeahead dropdown.
callback({data:[
{
text: '',
value:''
}]
});
readonly
boolean or -1
-1
Specifies whether the control is in readonly mode. If set to true, the pillbox disables user
capacity to add / edit pills. A -1 value means it will check for the presence of the
data-readonly="readonly" attribute, and if found initialize in readonly mode.
truncate
boolean
false
When in readonly mode, this option will display only the number of pills that fit within the pillbox main
container, with a message indicating the number of hidden items. The message content that appears is found
inside the element with class pillbox-more.
Events
Event Type
Description
clicked.fu.pillbox
This event is triggered when a pill is clicked. A jQuery data() object with information about the clicked pill is returned.
added.fu.pillbox
This event is triggered when a pill is added. A jQuery data() object with information about the added pill is returned.
removed.fu.pillbox
This event is triggered when a pill is removed. A jQuery data() object with information about the removed pill is returned.
edited.fu.pillbox
This event is triggered when a pill is edited. A jQuery data() object with information about the edited pill is returned.
All pillbox events are fired on the .pillbox classed element.
$('#myPillbox').on('clicked.fu.pillbox', function (evt, item) {
// do something
});
Adds a pop-up element to inputs/textareas on focus with additional options for explicit accept/cancel actions.
Usage
Via JavaScript
Call the placard control via JavaScript:
$('#myPlacard').placard();
Via data-attributes
The placard will automatically instantiate any placard with data-initialize="placard". If you add the control markup after page load with data-initialize="placard", the control will initialize on focus.
Markup
Use the following markup for a simple input OR textarea OR contenteditable div placard:
Add data-ellipsis="true" to the placard element to enable ellipsis on the placard-field. Inputs and regular contenteditable divs use CSS.
JavaScript is used to enable ellipsis for textareas and contenteditable divs with data-textarea="true". Use the .('getValue'); and .('setValue'); methods to retrieve or set values for placards with ellipsis enabled to avoid incorrect values.
Be warned: performance drops with large fields for the JavaScript solution when ellipsis is enabled.
Add data-textarea="true" to the .placard-field element if using a contenteditable div to make that element look and behave more like a textarea.
Glass styling
Add the glass class to the input, textarea, or contenteditable div with class placard-field
for a field with minimalistic chrome unless hovered upon or clicked.
Options
You can pass options via JavaScript upon initialization.
Name
type
default
description
explicit
boolean
false
Requires the user explicitly select 'accept' or 'cancel' before the placard is dismissed.
externalClickAction
string
cancel
Specifies what action occurs on an external click (click outside the placard element).
externalClickExceptions
array
[ ]
Array of jQuery selector strings. Anything that matches the selector (searched
globally) will not count as an external click. Allows other items to be clicked without dismissing the placard.
onAccept
function
undefined
Call this function when the user indicates they want to 'accept' changes. Passes a
helpers object containing previousValue and current
value as an argument. The default accept behaviors will not occur, so you can determine what happens next. Useful for validation purposes.
onCancel
function
undefined
Call this function when the user indicates they want to 'cancel' changes. Passes a
helpers object containing previousValue and current
value as an argument. The default cancel behaviors will not occur, so you can determine what happens next. Useful for validation purposes.
revertOnCancel
boolean OR number
-1
Dictates whether the placard reverts the entered value when a 'cancel' action occurs. -1 checks
for a '.placard-accept' element on initialization, setting this value to true
if present. Also accepts true or false values.
Methods
.placard('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup
.placard('disable')
Ensures the placard is disabled, preventing users from manipulating the placard value.
.placard('enable')
Ensures the placard is enabled, allowing users to manipulate the placard value.
.placard('getValue');
Gets the current actual placard value
.placard('hide');
Hides the placard pop-up
.placard('setValue');
Sets the current actual placard value
$('#myPlacard').placard('setValue', 'foxen');
Parameter
description
value
Required. String or number used to set the placard value.
.placard('show');
Shows the placard pop-up.
Events
Event Type
Description
accepted.fu.placard
Fires when the user indicates the desire to 'accept' changes. This event fires after the onAccept function, if defined.
canceled.fu.placard
Fires when the user indicates the desire to 'cancel' changes. This event fires after the onCancel function, if defined.
hidden.fu.placard
Fires when you dismiss the placard and the popup disappears.
shown.fu.placard
Fires when the placard obtains focus and the popup appears.
All placard events are fired on the .placard classed element.
$('#myPlacard').on('accepted.fu.placard', function () {
// do something…
});
Examples
Adds a pop-up element to inputs/textareas/contenteditable-divs on focus with additional options for explicit accept/cancel actions.
Popovers in button groups, input groups, and tables require special setting
When using popovers on elements within a .btn-group or an .input-group, or on table-related elements (<td>, <th>, <tr>, <thead>, <tbody>, <tfoot>), you'll have to specify the option container: 'body' (documented below) to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the popover is triggered).
Don't try to show popovers on hidden elements
Invoking $(...).popover('show') when the target element is display: none; will cause the popover to be incorrectly positioned.
Popovers on disabled elements require wrapper elements
To add a popover to a disabled or .disabled element, put the element inside of a <div> and apply the popover to that <div> instead.
Multiple-line links
Sometimes you want to add a popover to a hyperlink that wraps multiple lines. The default behavior of the popover plugin is to center it horizontally and vertically. Add white-space: nowrap; to your anchors to avoid this.
Examples
Static popover
Four options are available: top, right, bottom, and left aligned.
Popover top
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
Popover right
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
Popover bottom
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
Popover left
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.
Live demo
<button class="btn btn-lg btn-danger" data-toggle="popover" type="button" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
Four directions
<button class="btn btn-default" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus." type="button">
Popover on left
</button>
<button class="btn btn-default" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus." type="button">
Popover on top
</button>
<button class="btn btn-default" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
sagittis lacus vel augue laoreet rutrum faucibus." type="button">
Popover on bottom
</button>
<button class="btn btn-default" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus." type="button">
Popover on right
</button>
Dismiss on next click
Use the focus trigger to dismiss popovers on the next click that the user makes.
Specific markup required for dismiss-on-next-click
For proper cross-browser and cross-platform behavior, you must use the <a> tag, not the <button> tag, and you also must include the role="button" and tabindex attributes.
<a class="btn btn-lg btn-danger" data-toggle="popover" data-trigger="focus" tabindex="0" role="button" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
Usage
Enable popovers via JavaScript:
$('#example').popover(options)
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-animation="".
Name
Type
Default
Description
animation
boolean
true
Apply a CSS fade transition to the popover
container
string | false
false
Appends the popover to a specific element. Example: container: 'body'. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.
content
string | function
''
Default content value if data-content attribute isn't present.
If a function is given, it will be called with its this reference set to the element that the popover is attached to.
delay
number | object
0
Delay showing and hiding the popover (ms) - does not apply to manual trigger type
If a number is supplied, delay is applied to both hide/show
Object structure is: delay: { "show": 500, "hide": 100 }
html
boolean
false
Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement
string | function
'right'
How to position the popover - top | bottom | left | right | auto. When "auto" is specified, it will dynamically reorient the popover. For example, if placement is "auto left", the popover will display to the left when possible, otherwise it will display right.
When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the popover instance.
selector
string
false
If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See this and an informative example.
The popover's title will be injected into the .popover-title.
The popover's content will be injected into the .popover-content.
.arrow will become the popover's arrow.
The outermost wrapper element should have the .popover class.
title
string | function
''
Default title value if title attribute isn't present.
If a function is given, it will be called with its this reference set to the element that the popover is attached to.
trigger
string
'click'
How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
viewport
string | object | function
{ selector: 'body', padding: 0 }
Keeps the popover within the bounds of this element. Example: viewport: '#viewport' or { "selector": "#viewport", "padding": 0 }
If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the popover instance.
Data attributes for individual popovers
Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.
Methods
$().popover(options)
Initializes popovers for an element collection.
.popover('show')
Reveals an element's popover. Returns to the caller before the popover has actually been shown (i.e. before the shown.bs.popover event occurs). This is considered a "manual" triggering of the popover. Popovers whose both title and content are zero-length are never displayed.
$('#element').popover('show')
.popover('hide')
Hides an element's popover. Returns to the caller before the popover has actually been hidden (i.e. before the hidden.bs.popover event occurs). This is considered a "manual" triggering of the popover.
$('#element').popover('hide')
.popover('toggle')
Toggles an element's popover. Returns to the caller before the popover has actually been shown or hidden (i.e. before the shown.bs.popover or hidden.bs.popover event occurs). This is considered a "manual" triggering of the popover.
$('#element').popover('toggle')
.popover('destroy')
Hides and destroys an element's popover. Popovers that use delegation (which are created using the selector option) cannot be individually destroyed on descendant trigger elements.
$('#element').popover('destroy')
Events
Event Type
Description
show.bs.popover
This event fires immediately when the show instance method is called.
shown.bs.popover
This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.popover
This event is fired immediately when the hide instance method has been called.
hidden.bs.popover
This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).
inserted.bs.popover
This event is fired after the show.bs.popover event when the popover template has been added to the DOM.
$('#myPopover').on('hidden.bs.popover', function () {
// do something…
})
The radio control provides a customized look and feel that can be standardized across all browsers.
Usage
Via JavaScript
Call the radio control via JavaScript on the label. The div.radio container is only present for block level stying:
$('#myRadioLabel').radio();
Via data-attributes
The radio will automatically instantiate any radios with data-initialize="radio" located on the <label>. If you add the control markup after page load with data-initialize="radio", this control initializes on mouseover.
Deprecated radio button markup
Before v3.7.0, the radio control could be bound with $().radio(); or data-initialize="radio" to the div.radio or the input elements. This is no longer supported. Please update your markup and JavaScript to be bound to the label only.
Methods
.radio('check')
Ensures the radio is checked
.radio('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.radio('disable')
Ensures the radio is disabled
.radio('enable')
Ensures the radio is enabled
.radio('isChecked')
Returns true or false indicating the radio's checked state
Use the data-toggle="{{selector}}" to automatically show or hide elements matching the selector within the body upon check or uncheck. This function works with any jQuery selector.
ID-toggling container
Class-toggling container
Class-toggling container
<div class="radio">
<label class="radio-custom" id="myCustomRadioLabel8" data-initialize="radio">
<input class="sr-only" name="radioEx3" data-toggle="#radioToggleID" type="radio" value="option1">
Toggles element with matching ID
</label>
</div>
<label class="radio-custom radio-inline" id="myCustomRadioLabel9" data-initialize="radio">
<input class="sr-only" name="radioEx3" data-toggle=".radioToggleCLASS" type="radio" value="option1">
Toggles elements with matching class
</label>
<div class="alert bg-info" id="radioToggleID">ID-toggling container</div>
<div class="alert bg-success radioToggleCLASS">Class-toggling container</div>
<div class="alert bg-success radioToggleCLASS">Class-toggling container</div>
Highlighting radios
Use the .highlight class to add a background highlight upon check.
<div class="radio highlight" id="myCustomRadioLabel10">
<label class="radio-custom highlight" data-initialize="radio">
<input class="sr-only" name="radioEx4" type="radio" value="option1">
This block-level radio will highlight on check.
</label>
</div>
<label class="radio-custom radio-inline highlight" id="myCustomRadio11" data-initialize="radio">
<input class="sr-only" name="radioEx4" type="radio" value="option2">
This inline radio will highlight on check.
</label>
The repeater list plug-in extends repeater functionality. This plug-in follows the steps specified in the repeater
docs. You can also use the following additional features:
Data Source
The dataSource function behaves as described in the repeater docs. However, the function potentially provides a few additional attributes in the options argument:
Attribute
type
description
sortDirection
string
If the list view is sortable and has been sorted by the user, this will indicate the sort direction.
Values are either 'asc' or 'desc'.
sortProperty
string
If the list view is sortable and has been sorted by the user, this will indicate the column property
that has been sorted on.
Additionally, the function requires a few additional parameters on the returned data object to render the data properly:
Attribute
type
description
columns
array
Array of objects representing the desired columns within the rendered list. The column objects contain
three attributes:
className - String representing the classes to be added to any DOM items associated with the column. Multiple classes can be adding a space between each name
label - String or jQuery attribute containing the content to be displayed as the "name" of the column
property - String value that dictates which item attribute is displayed within the column
sortable - Optional Boolean or string value dictating whether user can sort the column. A true value indicates sorting on the property value. A string value sorts on the specified value. This attribute defaults to false
sortDirection - Optional string to set initial sort direction of the column. Values can be either 'asc' or 'desc'. NOTE: only one column can be sorted upon at a time.
width - String or Number dictating this column's width
Array of objects representing the item data that will be displayed within the repeater. The item
objects can contain any number of attributes. The attribute name must match the column property value to display within a column.
Options
You can pass options via Javascript upon initialization.
Name
type
default
description
list_actions
object
null
Can be used to configure an additional actions column in the repeater. It will positioned as the rightmost column
and will always be visible. It creates a dropdown menu that can be populated with x number of actions to be applied
to the row. If multi select is also enabled will allow for bulk actions.
width - optional width to the actions column
items - Array of objects representing the different action items in the dropdown
name - String representing the name of the action
html - HTML string that would modify the markup of the action item
clickAction - returns a helpers obj once this action item has been clicked
helpers returns an object that contains helpers.item
which is the jquery element of the current table row. Also returns helpers.rowData
which are all key/value data from the current item/row in the dataSource
If set, the repeater calls this function after rendering each table cell within a row. It passes a helpers
object and a callback function as arguments. This function is the preferred way to modify table cell markup.
helpers.rowData - All key/value data from the current item/row in the dataSource
helpers.columnAttr - The key name specified by dataSource.columns of the current column/cell
helpers.container - jQuery element of the current tr or table row
helpers.item - jQuery element of the current td or table cell
callback - Call this function to continue rendering the view
list_columnSizing
boolean
true
Dictates whether the repeater should run the intelligent column resizing algorithm. This feature only resizes columns without a set value. Setting this value to false will disable this feature entirely.
list_columnSyncing
boolean
true
Dictates whether the repeater should run the post-render column syncing algorithm. This feature keeps
the `.repeater-list-heading` classed divs in alignment with the columns. Setting this value to
false will disable this feature entirely.
list_frozenColumns
number
0
Dictates whether the repeater should create frozen columns in the repeater. This feature creates
x number of frozen columns on the left side of the repeater. Frozen columns means that when scrolled
left to right these columns will not move and always be visible.
list_infiniteScroll
boolean or object
false
Dictates whether the repeater list view should utilize infinite scrolling instead of pagination.
A true value enables infinite scrolling with default settings. Additionally,
you can set this value to an object with attributes matching the options available in the
infinite scroll control. This option allows for further
customization and ignores the dataSource option.
list_noItemsHTML
string or jQuery object
''
Specifies what is displayed if no items return from the dataSource. You can use a
string or jQuery object.
list_selectable
boolean or string
false
Specifies whether a user can select rendered item rows. If you set the value to true,
users can select only one row at a time. If you set the value to 'multi', users can select multiple rows at once.
list_sortClearing
boolean
false
Specifies whether users can clear sortable columns with a third click:
one click, sort ASC.
second click, sort DESC
third click, no sorting
list_rowRendered
function
null
If set, the repeater calls this function after the repeater renders each row, passing a helpers
object and callback function as arguments. This function is the preferred way to modify table row markup.
helpers.rowData - All key/value data from the current item/row in the dataSource
helpers.container - jQuery element of the row's parent (tbody)
helpers.item - jQuery element of the current tr or table row
callback - Call this function to continue rendering the view
list_highlightSortedColumn
boolean
true
Specifies whether sorted columns should be highlighted.
Methods
.repeater('list_clearSelectedItems');
Clears any currently selected row items. You can use selectable row items only by enabling the list_selectable option.
Required Array of items objects. The items objects specify which item to select with attributes
to identify the item. If the items object contains an index property, that items object will select the matching item index within the currently displayed data. If the items object contains a property attribute and value attribute, that items object will select items with properties matching the specified value. (ex: [ { index: 4 }, { property: 'name', value: 'nameValue' } ] )
force
Optional Boolean specifying whether to ignore current list_selectable mode when
selecting items. This value defaults to false and allows only one selectable item if list_selectable does not equal multi, regardless of how many items
are passed into the items array parameter. Set the value to true to override this behavior
and select all provided items.
Events
Event Type
Description
deselected.fu.repeaterList
If list_selectable is enabled, fires whenever the user deselects a row. Provides an event
object and the deselected row as arguments.
selected.fu.repeaterList
If list_selectable is enabled, fires whenever the user selects a row. Provides an event
object and the selected row as arguments.
All repeater-list events are fired on the .repeater classed element.
$('#myRepeater').on('selected.fu.repeaterList', function () {
// do something…
});
The repeater thumbnail plug-in extends repeater functionality. This plug-in follows the steps specified in the repeater
docs. You can also use the following additional features:
Data Source
The dataSource function behaves as described in the repeater docs. However, the function requires a few additional parameters on the returned data object to render the data properly:
Attribute
type
description
items
array
Array of objects representing the thumbnails that will be displayed within the repeater. The item
objects can contain any number of attributes, although attributes with certain names will be
used to render the thumbnail. In the default thumbnail template, the `src` and `name` attributes
are expected.
Options
You can pass options via Javascript upon initialization.
Name
type
default
description
thumbnail_alignment
string
'justify'
Specifies the alignment of rendered thumbnails. The options for the alignment of thumbnails include
'left', 'center', 'justify', 'right' or
'none'
thumbnail_infiniteScroll
boolean or object
false
Dictates whether the repeater thumbnail view should utilize infinite scrolling instead of pagination.
A true value enables infinite scrolling with default settings. Additionally,
you can set this value to an object with attributes matching the options available in the
infinite scroll control. This option allows for further
customization and ignores the dataSource option.
thumbnail_itemRendered
function
null
The repeater calls this function after the repeater renders each item, passing a a helpers
object and callback function as arguments. The helpers object includes
itemData, parent container, and current thumbnail item as attributes,
if available. Once ready, call the callback function in order to continue with rendering.
thumbnail_selectable
boolean or string
false
Specifies whether a user can select rendered thumbnails. If you set the value to true,
users can select only one thumbnail at a time. If you set the value to 'multi', users
can select multiple thumbnails at once.
thumbnail_template
string
<div class="thumbnail repeater-thumbnail"><img height="75" src="{% raw %}{{src}}{% endraw %}" width="65"><span>{% raw %}{{name}}{% endraw %}</span></div>
Dictates the template used to render the repeater thumbnails. Mustache/Handlebar-style syntax ('{% raw %}{{example}}{% endraw %}')
can be used to specify where various attribute values will be inserted. NOTE: only the immediate
decendents of the thumbnail item object can be referenced; all other Mustache/Handlebars functionality
not supported.
Methods
.repeater('thumbnail_clearSelectedItems');
Clears any currently selected thumbnail items. You can use selectable thumbnail items only by enabling the thumbnail_selectable option.
Required Array of items objects. The items objects specify which thumbnails to select with attributes
to identify the item. If the items object contains an index property, the method will
select the matching thumbnail index within the currently displayed data. If the items object contains a
selector property, the method will select any thumbnails matching that selector.
(ex: [ { index: 4 }, { selector: '.coolThumbnail' } ] )
force
Optional Boolean specifying whether to ignore current thumbnail_selectable mode when
selecting items. This value defaults to false and allows only one selectable item if
thumbnail_selectable does not equal 'multi', regardless of how many items
are passed into the items array parameter. Set the value to true to override this behavior
and select all provided items.
Events
Event Type
Description
deselected.fu.repeaterThumbnail
If thumbnail_selectable is enabled, fires whenever the user deselects a thumbnail. Provides an event
object and the deselected thumbnail as arguments.
selected.fu.repeaterThumbnail
If thumbnail_selectable is enabled, fires whenever the user selects a thumbnail. Provides an event
object and the selected thumbnail as arguments.
All repeater-thumbnail events are fired on the .repeater classed element.
$('#myRepeater').on('selected.fu.repeaterThumbnail', function () {
// do something…
});
Use this function to provide paging information and data for the repeater. Call this function prior
to rendering the current view, passing a options object and callback
function. Run the callback function once you gather the appropriate information to complete
the rendering. Review more details on using dataSource below.
dataSourceOptions
object
null
Use this object to pass a parameter to a custom-defined dataSource function mentioned above. Then, use those values to customize the data that gets passed back into the repeater from your API. Suggested uses include sorting, filtering, and search values. This object is also valuable in custom renders when used as an object within the render methods's options parameter. Did you lose your custom dataSourceOptions when you changed the page within repeater? If you did, set preserveDataSourceOptions to true in order to keep them.
defaultView
string or number
-1
Specifies the initial view the repeater will render (usually a string value equivalent
to the desired repeater view extension). If set to -1, the repeater will check the
.repeater-views button group for an .active class, using its input
value as the defaultView setting.
dropPagingCap
number
10
Specifies the number of items allowed within the .repeater-primaryPaging drop-down menu.
If the number of pages exceeds this amount, the code will use the .repeater-secondaryPaging input.
preserveDataSourceOptions
boolean
false
Sets whether defineddataSourceOptions get preserved or reset when the dataSource is called. For example, the dataSource function is called when navigating to another page. If you would like to keep previously defined settings such as search or filtering, then set to true. Setting to true is generally recommended when using dataSourceOptions to manipulate your data.
staticHeight
boolean or number
-1
If true; height of CSS styles applied to repeater element will be used
If a positive number; that value will be used as height in pixels
If -1; value of data-staticheight attribute will be used if present
If false; height will be fluid, not static. Meaning reapeater contents will not be scrollable, and container must be big enough to show everything. Similar to CSS overflow: hidden.
views
object
null
Can be optionally used to configure multiple views, including those of the same view type (2 'list' views, 2
'thumbnail' views, etc) To utilize, first set the input values within .repeater-views to their
appropriate view names. For multiple views of the same type, use the . operator as a separator,
following the syntax [viewType].[viewName] (Ex: "list.view1") Then, within the views
option object, add these view names as attributes. Each attribute can be an object, with it's own view plugin / repeater
configuration. This configuration will then be honored by the repeater per view. Example:
optional -- if true, preserve must also be set to true to have an effect. If infinite scrolling is enabled, setting to true will clear all non data-preserved elements. Defaults to false.
preserve
boolean
optional If true, only items that don't have the data-preserve attribute will be removed. Otherwise, all items will be removed. Defaults to false.
.repeater('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.repeater('infiniteScrolling');
Enables or disabled infinite scrolling within the repeater. Used primarily by view extensions. Accepts an optionaloptions object.
If set to true, this function will enable infinite scrolling. Defaults to false.
options
object
Optional. Specifies the desired infinite scrolling settings. View the infinite scroll
documentation for more details on available features. Your code will ignore the dataSource option on this
object in favor of the dataSource on the repeater.
.repeater('render');
Calls the dataSource and renders the repeater data. Accepts an optionaloptions object.
If set to a string value, this attribute will change the current repeater view to be rendered. Defaults to
undefined.
clearInfinite
boolean
Passed to the clear method - see above for description.
pageIncrement
number or null
Use a number value to determine the amount by which the current page will increment or decrement. If
null the current page will reset to 0.
preserve
boolean
Passed to the clear method - see above for description.
.repeater('resize');
Resizes the repeater based on staticHeight presence and value
Data Source
Call the dataSource function prior to rendering data for the current view. Receives an
options object and callback function as arguments. The options object
provides context for which data should return. Please review the dataSourceOptions option if the dataSource needs to be manipulated (such as for a custom render, to search, to sort, or to filter). Use the callback to continue onward
with rendering.
The options object can vary in content depending on the view extension used. Many objects share
these common attributes in options object format:
Attribute
type
description
filter
object
Provides context for the selected .repeater-filters drop-down item representing data
filtering. The object contains a text attribute for the displayed text and
a value attribute for the value of the selected item.
pageIndex
number
Represents the current page of data. pageIndex is a zero-based index into an array and may need to be manipulated before requesting more data, if the server request is a one-based index.
pageSize
number
Provides context for the selected .repeater-itemization dropdown item value, representing the number of data items to be displayed
search
string
Provides context for the entered .repeater-search search box, representing the desired
user search value. Only present if the object includes a search value.
view
string
Provides context for the selected .repeater-views button group item, representing
the current view. Used to determine view-specific return data.
The dataSource's callback function should run after gathering the desired data for rendering. This function requires the code to pass a
data object as an argument. Contents of the object will vary depending on the view
extension used. The attributes below include common expected attributes:
Attribute
type
description
count
number
Provides the number of returned in the data to the repeater. Use this value as the text value for the
.repeater-count element.
end
number
Provides the end index of current displayed data items to the repeater. Use this value as the text value for the
.repeater-end element.
page
number
Sets the current repeater page. Also shown in the .repeater-primaryPaging or
.repeater-secondaryPaging element. page is 0-based.
pages
number
Provides the number of available pages of data to the repeater. Use this value as the text value for the .repeater-pages
element. pages is 1-based.
start
number
Provides the starting index of current displayed data items to the repeater. Use this value as the text value for the
.repeater-start element.
The default values are { count: 0, end: 0, items: [], page: 0, pages: 1, start: 0 }.
Events
Event Type
Description
disabled.fu.repeater
Fires whenever the repeater is disabled.
enabled.fu.repeater
Fires whenever the repeater is enabled.
filtered.fu.repeater
Fires whenever the repeater is filtered via the dropdown. Passes a filter value argument.
nextClicked.fu.repeater
Fires whenever the repeater next page button is clicked.
pageChanged.fu.repeater
Fires whenever the repeater page is changed via primary or secondary paging. NOTE: if the paged via
primary paging, an array is passed back as a parameter, containing the value and
data, respectively. If secondary paging causes the change, only a value is passed as
an argument.
pageSizeChanged.fu.repeater
Fires whenever the repeater page size is changed. Passes a value argument.
previousClicked.fu.repeater
Fires whenever the repeater previous page button is clicked.
rendered.fu.repeater
Fires whenever the repeater has rendered data returned from the dataSource. Passses an object containing
data, options, and renderOptions.
resized.fu.repeater
Fires whenever the repeater is resized.
searchChanged.fu.repeater
Fires whenever the repeater search control is used.
viewChanged.fu.repeater
Fires whenever the repeater view is switched. Passes the currentView as an argument.
All repeater events are fired on the .repeater classed element.
$('#myRepeater').on('resized.fu.repeater', function () {
// do something…
});
The repeater uses a view framework that allows for extensions to represent data in different ways. By default,
Fuel UX comes with two repeater view extensions (list and thumbnail).
Each extension provides additional options and requires different return data from the
dataSource to render appropriately. For
information on using extensions, visit the extensions page.
You can also learn how to write your own repeater extension.
Examples
Data viewer with paging, sorting, and searching using list and thumbnail extensions. Can be extended further for various other renderings.
Add data-initialize="scheduler" to the .scheduler element that you wish to initialize on $.ready(). Any scheduler that is programmatically generated after the initial page load will initialize when the mousedown event is fired on it if it has data-initialize="scheduler".
Markup
Place all of the following markup within any "fuelux" classed container (typically the html element). Scheduler consists of a specific arrangement of Datepickers, Comboboxes, Radios, Selectlists, and Spinboxes.
Should be passed in as an object (eg. {name: value}) on initialization. If initializing with options, Javascript initialization is required (you can't initialize with options through data-attributes).
Name
type
default
description
startDateOptions
object
{}
Attributes used to configure the datepicker object. All options for datepicker are available and they can
be found in the datepicker documentation.
endDateOptions
object
{}
This option can be set but will only be used if the event is repeated. Attributes used to configure the datepicker object.
All options for datepicker are available and they can
be found in the datepicker documentation.
startDateChanged
function
undefined
As of 3.11.5, Function to be run when the start date is changed. Currently this._guessEndDate(); is called, but, if you pass
a function, your function will be called instead. Your function can call this._guessEndDate(); at any point from
within the function to take advantage of the pre-built Guess End Date AI. See the code for details. Example here.
Methods
Once your scheduler is initialized, you can execute any of the following methods on it:
.scheduler('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.scheduler('disable')
Ensure all scheduler form fields are disabled
.scheduler('enable')
Ensure all scheduler form fields are enabled
.scheduler('value')
Gets or sets the current scheduler form field information
Required. String representing the start date & time in ISO 8601 format.
timeZone
Optional.String or Object (as {name: 'value'} or {offset: '+00:00'}) used for method call to selectBySelector() on scheduler's Timezone selectList. Whatever is passed in will be passed along to selectlist.selectBySelector(value). If a String is passed, it will be passed along as-is. If an Object is passed, name will be passed along if present, otherwise offset will be passed along but never both.
This event fires when the user changes any setting.
All scheduler event listeners should be attached to the element containing the scheduler class. Given the above example markup, you would attach event listeners thusly:
$('#myScheduler').on('changed.fu.scheduler', function () {
// do something
});
The following static scheduler displays all components simultaneously (start date and time, timezone, and all recurrence and recurrence end options) for illustration purposes only.
The ScrollSpy plugin is for automatically updating nav targets based on scroll position. Scroll the area below the navbar and watch the active class change. The dropdown sub items will be highlighted as well.
@fat
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.
@mdo
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.
one
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.
two
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.
three
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.
Usage
Requires Bootstrap nav
Scrollspy currently requires the use of a Bootstrap nav component for proper highlighting of active links.
Resolvable ID targets required
Navbar links must have resolvable id targets. For example, a <a href="#home">home</a> must correspond to something in the DOM like <div id="home"></div>.
Non-:visible target elements ignored
Target elements that are not :visible according to jQuery will be ignored and their corresponding nav items will never be highlighted.
Requires relative positioning
No matter the implementation method, scrollspy requires the use of position: relative; on the element you're spying on. In most cases this is the <body>. When scrollspying on elements other than the <body>, be sure to have a height set and overflow-y: scroll; applied.
Via data attributes
To easily add scrollspy behavior to your topbar navigation, add data-spy="scroll" to the element you want to spy on (most typically this would be the <body>). Then add the data-target attribute with the ID or class of the parent element of any Bootstrap .nav component.
Combines an input and a button to fire the searched event.
Usage
This function includes a simple input and button group that styles with a search icon and fires the searched event.
Via JavaScript:
Call the search control via JavaScript:
$('#mySearch').search();
Via data-attributes
To enable the search control without writing JavaScript, add data-initialize="search" to the .search element that you wish to initialize. Such elements that exist when $.ready() executes will be initialized. Any search markup that is programmatically created with data-initialize="search" sometime after the initial page load will not immediately initialize. Rather, it will initialize when the mousedown event is fired on it.
Markup
Wrap class="search" around an input and a button within a class="fuelux" container.
Add data-initialize="selectlist" to the .selectlist element that you wish to initialize on $.ready(). Any selectlist that is programmatically generated after the initial page load will initialize when the mousedown event is fired on it if it has data-initialize="selectlist".
Markup
Wrap class="selectlist" around an input and a button within a class="fuelux" container.
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.selectlist('disable')
Ensures the component is disabled
.selectlist('enable')
Ensures the component is enabled
.selectlist('selectedItem')
Returns an object containing the jQuery data() contents of the selected item. This data includes .data-* attributes plus a text property with the visible text from the item.
.selectlist('selectByIndex')
Set the selected item based on its index in the list (zero-based index). Convenience method for .selectBySelector('li:eq({index})')
This event fires when the value changes by selecting an item from the list. Arguments include event, data where data represents the same object structure returned by the selectedItem method.
All selectlist events are fired on the .selectlist classed element.
$('#mySelectlist').on('changed.fu.selectlist', function () {
// do something
});
Examples
A single select drop-down similar to the native select control. Wrap the input and selectlist button within .fuelux .selectlist
Spinbox includes an enhanced numeric input based upon the native <input type="number">.
Usage
A spinbox allows for click interaction with a numeric input.
Currently there is a bug causing changed events to fire twice for some elements. The workaround is to disable this data-api, using $.off('fu.data-api')
Via JavaScript
Call the selectlist control via JavaScript:
$('#mySpinbox').spinbox();
Via data-attributes
To enable the spinbox control without writing JavaScript, add data-initialize="spinbox" to the .spinbox element that you wish to initialize. Such elements that exist when $.ready() executes will be initialized. Any spinbox markup that is programmatically created with data-initialize="spinbox" sometime after the initial page load will not immediately initialize. Rather, it will initialize when the mousedown event is fired on it.
Markup
Add class="spinbox" to a div within a class="fuelux" container.
If value contains non-integers, the value returns as a string. Otherwise, the value returns as a number.
Options
Options that can be passed in via JavaScript once at initialization.
Name
type
default
description
value
number
1
Sets the initial spinbox value
min
number
1
Sets the minimum spinbox value
max
number
999
Sets the maximum spinbox value
step
number
1
Sets the increment by which the value in the spinbox will change each time the spinbox buttons are pressed
limitToStep
boolean
false
Limits the spinner value to increments of the step value. Eg. If step is 5, spinner values will be limited to increments of 5, (0, 5, 10, 15...)
hold
boolean
true
If true, the spinbox will react to its buttons being pressed and held down
hold
boolean
true
If true, the spinbox will react to its buttons being pressed and held down
speed
string
"medium"
Assigns spinbox speed when buttons are held down. Options include "fast","medium","slow".
disabled
boolean
false
Creates a disables spinbox.
units
array
[]
Units that will be allowed to appear and be typed into the spinbox input along with the numeric value. For example, setting units to a value of ['px', 'en', 'xx'] would allow px, en, and xx units to appear within the spinbox input
Events
Event Type
Description
changed.fu.spinbox
This event fires when the value changes (either by selecting an item from the list or updating the input value directly). Arguments include event, value where value is the current value of the spinner. Returns the current value of the spinner.
All spinbox events are fired on the .spinbox classed element.
$('#mySpinbox').on('changed.fu.spinbox', function () {
// do something
})
Example
Spinbox includes an enhanced numeric input based upon the native <input type="number">. Wrap the input and the increment/decrement buttons within .fuelux .spinbox
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.
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. Lomo wolf viral, mustache readymade thundercats keffiyeh craft beer marfa ethical. Wolf salvia freegan, sartorial keffiyeh echo park vegan.
$('#myTabs a[href="#profile"]').tab('show') // Select tab by name
$('#myTabs a:first').tab('show') // Select first tab
$('#myTabs a:last').tab('show') // Select last tab
$('#myTabs li:eq(2) a').tab('show') // Select third tab (0-indexed)
Markup
You can activate a tab or pill navigation without writing any JavaScript by simply specifying data-toggle="tab" or data-toggle="pill" on an element. Adding the nav and nav-tabs classes to the tab ul will apply the Bootstrap tab styling, while adding the nav and nav-pills classes will apply pill styling.
Activates a tab element and content container. Tab should have either a data-target or an href targeting a container node in the DOM. In the above examples, the tabs are the <a>s with data-toggle="tab" attributes.
.tab('show')
Selects the given tab and shows its associated content. Any other tab that was previously selected becomes unselected and its associated content is hidden. Returns to the caller before the tab pane has actually been shown (i.e. before the shown.bs.tab event occurs).
$('#someTab').tab('show')
Events
When showing a new tab, the events fire in the following order:
hide.bs.tab (on the current active tab)
show.bs.tab (on the to-be-shown tab)
hidden.bs.tab (on the previous active tab, the same one as for the hide.bs.tab event)
shown.bs.tab (on the newly-active just-shown tab, the same one as for the show.bs.tab event)
If no tab was already active, then the hide.bs.tab and hidden.bs.tab events will not be fired.
Event Type
Description
show.bs.tab
This event fires on tab show, but before the new tab has been shown. Use event.target and event.relatedTarget to target the active tab and the previous active tab (if available) respectively.
shown.bs.tab
This event fires on tab show after a tab has been shown. Use event.target and event.relatedTarget to target the active tab and the previous active tab (if available) respectively.
hide.bs.tab
This event fires when a new tab is to be shown (and thus the previous active tab is to be hidden). Use event.target and event.relatedTarget to target the current active tab and the new soon-to-be-active tab, respectively.
hidden.bs.tab
This event fires after a new tab is shown (and thus the previous active tab is hidden). Use event.target and event.relatedTarget to target the previous active tab and the new active tab, respectively.
$('a[data-toggle="tab"]').on('shown.bs.tab', function (e) {
e.target // newly activated tab
e.relatedTarget // previous active tab
})
Inspired by the excellent jQuery.tipsy plugin written by Jason Frame; Tooltips are an updated version, which don't rely on images, use CSS3 for animations, and data-attributes for local title storage.
Tooltips with zero-length titles are never displayed.
Examples
Hover over the links below to see tooltips:
Tight pants next level keffiyeh you probably haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.
Static tooltip
Four options are available: top, right, bottom, and left aligned.
Tooltip on the left
Tooltip on the top
Tooltip on the bottom
Tooltip on the right
Four directions
<button class="btn btn-default" data-toggle="tooltip" data-placement="left" type="button" title="Tooltip on left">Tooltip on left</button>
<button class="btn btn-default" data-toggle="tooltip" data-placement="top" type="button" title="Tooltip on top">Tooltip on top</button>
<button class="btn btn-default" data-toggle="tooltip" data-placement="bottom" type="button" title="Tooltip on bottom">Tooltip on bottom</button>
<button class="btn btn-default" data-toggle="tooltip" data-placement="right" type="button" title="Tooltip on right">Tooltip on right</button>
Opt-in functionality
For performance reasons, the Tooltip and Popover data-apis are opt-in, meaning you must initialize them yourself.
One way to initialize all tooltips on a page would be to select them by their data-toggle attribute:
The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element.
Trigger the tooltip via JavaScript:
$('#example').tooltip(options)
Markup
The required markup for a tooltip is only a data attribute and title on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to top by the plugin).
<!-- HTML to write -->
<a data-toggle="tooltip" href="#" title="Some tooltip text!">Hover over me</a>
<!-- Generated markup by the plugin -->
<div class="tooltip top" role="tooltip">
<div class="tooltip-arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Multiple-line links
Sometimes you want to add a tooltip to a hyperlink that wraps multiple lines. The default behavior of the tooltip plugin is to center it horizontally and vertically. Add white-space: nowrap; to your anchors to avoid this.
Tooltips in button groups, input groups, and tables require special setting
When using tooltips on elements within a .btn-group or an .input-group, or on table-related elements (<td>, <th>, <tr>, <thead>, <tbody>, <tfoot>), you'll have to specify the option container: 'body' (documented below) to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the tooltip is triggered).
Don't try to show tooltips on hidden elements
Invoking $(...).tooltip('show') when the target element is display: none; will cause the tooltip to be incorrectly positioned.
Accessible tooltips for keyboard and assistive technology users
For users navigating with a keyboard, and in particular users of assistive technologies, you should only add tooltips to keyboard-focusable elements such as links, form controls, or any arbitrary element with a tabindex="0" attribute.
Tooltips on disabled elements require wrapper elements
To add a tooltip to a disabled or .disabled element, put the element inside of a <div> and apply the tooltip to that <div> instead.
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-animation="".
Name
Type
Default
Description
animation
boolean
true
Apply a CSS fade transition to the tooltip
container
string | false
false
Appends the tooltip to a specific element. Example: container: 'body'. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize.
delay
number | object
0
Delay showing and hiding the tooltip (ms) - does not apply to manual trigger type
If a number is supplied, delay is applied to both hide/show
Object structure is: delay: { "show": 500, "hide": 100 }
html
boolean
false
Insert HTML into the tooltip. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement
string | function
'top'
How to position the tooltip - top | bottom | left | right | auto. When "auto" is specified, it will dynamically reorient the tooltip. For example, if placement is "auto left", the tooltip will display to the left when possible, otherwise it will display right.
When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the tooltip instance.
selector
string
false
If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have tooltips added. See this and an informative example.
The tooltip's title will be injected into the .tooltip-inner.
.tooltip-arrow will become the tooltip's arrow.
The outermost wrapper element should have the .tooltip class.
title
string | function
''
Default title value if title attribute isn't present.
If a function is given, it will be called with its this reference set to the element that the tooltip is attached to.
trigger
string
'hover focus'
How tooltip is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
viewport
string | object | function
{ selector: 'body', padding: 0 }
Keeps the tooltip within the bounds of this element. Example: viewport: '#viewport' or { "selector": "#viewport", "padding": 0 }
If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the tooltip instance.
Data attributes for individual tooltips
Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above.
Methods
$().tooltip(options)
Attaches a tooltip handler to an element collection.
.tooltip('show')
Reveals an element's tooltip. Returns to the caller before the tooltip has actually been shown (i.e. before the shown.bs.tooltip event occurs). This is considered a "manual" triggering of the tooltip. Tooltips with zero-length titles are never displayed.
$('#element').tooltip('show')
.tooltip('hide')
Hides an element's tooltip. Returns to the caller before the tooltip has actually been hidden (i.e. before the hidden.bs.tooltip event occurs). This is considered a "manual" triggering of the tooltip.
$('#element').tooltip('hide')
.tooltip('toggle')
Toggles an element's tooltip. Returns to the caller before the tooltip has actually been shown or hidden (i.e. before the shown.bs.tooltip or hidden.bs.tooltip event occurs). This is considered a "manual" triggering of the tooltip.
$('#element').tooltip('toggle')
.tooltip('destroy')
Hides and destroys an element's tooltip. Tooltips that use delegation (which are created using the selector option) cannot be individually destroyed on descendant trigger elements.
$('#element').tooltip('destroy')
Events
Event Type
Description
show.bs.tooltip
This event fires immediately when the show instance method is called.
shown.bs.tooltip
This event is fired when the tooltip has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.tooltip
This event is fired immediately when the hide instance method has been called.
hidden.bs.tooltip
This event is fired when the tooltip has finished being hidden from the user (will wait for CSS transitions to complete).
inserted.bs.tooltip
This event is fired after the show.bs.tooltip event when the tooltip template has been added to the DOM.
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something…
})
For simple transition effects, include transition.js once alongside the other JS files. If you're using the compiled (or minified) bootstrap.js, there is no need to include this—it's already there.
What's inside
Transition.js is a basic helper for transitionEnd events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.
Disabling transitions
Transitions can be globally disabled using the following JavaScript snippet, which must come after transition.js (or bootstrap.js or bootstrap.min.js, as the case may be) has loaded:
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup
.tree('selectedItems')
Returns an array containing selected items and associated data
.tree('selectItem', $('#itemId'))
Select the passed in non-folder item in the tree.
.tree('selectFolder', $('#itemId'))
Select the passed in folder item in the tree.
.tree('openFolder', $('#folderId'))
Open the targeted folder
.tree('closeFolder', $('#folderId'))
Close the targeted folder
.tree('toggleFolder', $('#folderId'))
Toggle the targeted folder (opened or closed)
.tree('closeAll')
Close all folders (collapse the entire tree).
.tree('discloseAll')
Disclose all folders (expand the entire tree).
.tree('discloseVisible')
Disclose only currently visible folders (expand already displayed folders).
.tree('populate', $el)
deprecated Populate the passed in element as if it were a new copy of the instantiated tree. If you call this on an already instantiated tree, it will append all of the items to the tree again. You probably don't want to call this. It will most likely become a private function in the future.
.tree('render')
Calls datasource callback for entire tree. Caution: Does not remove current top-level tree nodes.
.tree('refreshFolder', $('#folderId'))
Removes children and calls datasource callback for specified folder. Does not update data and attributes of the specified folder.
You can pass options via data attributes or JavaScript. For data attributes, append the option name to data-. For example, you could use data-selected="".
Name
type
default
description
multiSelect
boolean
false
Allows multiple tree items to be selected at once
cacheItems
boolean
true
Prevents refresh of sub-items when a user closes and reopens a folder
folderSelect
boolean
true
Enables folder selection
ignoreRedundantOpens
boolean
false
Makes openFolder() behave like toggleFolder() instead. Will be deprecated in 3.7.0 when openFolder() will only open the folder instead of toggling
disclosuresUpperLimit
integer
0
How many times discloseAll() should be called before a stopping and firing an exceededDisclosuresLimit.fu.tree event. You can force it to continue by listening for this event, setting data-ignore-disclosures-limit to true and starting discloseAll() back up again. This lets you make more decisions about if/when/how/why/how many times discloseAll() will be started back up after it exceeds the limit.
$tree.one('exceededDisclosuresLimit.fu.tree', function () {
$tree.data('ignore-disclosures-limit', true);
$tree.tree('discloseAll');
});
disclusuresUpperLimit defaults to 0, so by default this trigger will never fire. The true hard the upper limit is the browser's ability to load new items (i.e. it will keep loading until the browser falls over and dies). On the Fuel UX index.html testing page, the point at which the page became super slow (enough to seem almost unresponsive) was 4, meaning 256 folders had been opened, and 1024 were attempting to open.
Required Data Source
The tree control requires an array of objects in order to create a tree. To determine what tree nodes to create, the tree control uses a callback function named datasource that returns an object with an array named data within it. Items in data will be created when a branch is opened. All tree nodes must be loaded into the control one folder (branch) at a time. However, one can store the entire tree from a single network request, and use the datasource function to parse this combined object and not make additional network requests. The following are reserved keys within each item object.
Key
Type
Description
text
string
Required. Text of tree node. *Please note: text replaces and deprecates name
type
string
Required. Options are folder or item.
attr
object
Unless it is a reserved key in this table, child keys will be added as attributes to .tree-item or .tree-branch.
attr.cssClass
string
CSS classes that will be added to .tree-item or .tree-branch
attr.data-icon
string
CSS classes that will be added to .icon-item
attr.id
string
Adds id to .tree-item or .tree-branch and adds ARIA support with aria-labelledby.
attr.hasChildren
boolean
Set to false to hide the chevron next to folders. Defaults to true.
Events
Event Type
Description
selected.fu.tree
Fires when a user selects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. { selected: [array], target: [object] }
deselected.fu.tree
Fires when a user deselects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. { selected: [array], target: [object] }
loaded.fu.tree
Fires when sub-content has been is loaded. Returns the jQuery element of the folder loaded.
updated.fu.tree
Fires after selected.fu.tree and deselected.fu.tree events. Returns an object containing an array of selected items' jQuery data, the triggering jQuery element and the event type. { selected: [array], item: [object], eventType: [string] }
disclosedFolder.fu.tree
Fires when a user opens a folder. Returns an object containing the jQuery data of the opened folder.
refreshedFolder.fu.tree
Fires when a user refreshes a folder. Returns an object containing the jQuery data of the opened folder.
closed.fu.tree
Fires when a user closes a folder. Returns an object containing the jQuery data of the closed folder.
closedAll.fu.tree
Fires when all folders have finished closing. Returns an object containing an array of closed folders' jQuery data and the tree's jQuery element. The length of reportedClosed will provide the number of folders closed. { reportedClosed: [array], tree: [$element] }
disclosedVisible.fu.tree
Fires when all visible folders have disclosed/opened. Returns an object containing an array of disclosed folders' jQuery data and the tree's jQuery element. The length of reportedOpened will provide the number of folders opened. { reportedOpened: [array], tree: [$element] }
exceededDisclosuresLimit.fu.tree
Fires when tree halts disclosing due to hitting discloserLimit cap. Returns an object containing { disclosures: [number], tree: [$element] }
disclosedAll.fu.tree
Fires when all folders have disclosed. It will not fire if tree stops disclosing due to hitting discloserLimit cap. Returns an object containing { disclosures: [number], tree: [$element] }
All tree events are triggered from the .tree classed element.
$('#myTree').on('selected.fu.tree', function (event, data) {
// do something with data: { selected: [array], target: [object] }
})
Examples
Tree provides a categorical element selection. Use it to create a file system interface. Wrap the wrapper tree containers with .fuelux .tree
Please note the location of .glyphicon-playoutside.tree-branch-name. The control
allows folders to be selected by default unless the folderSelect option is set to false,
which then requires slightly different markup ("Items selectable only," shown further below)
A wizard divides a complex goal into multiple steps by separating sub-tasks or content into panes. You can add or remove panes. Completed steps remain clickable.
1Campaign
2Recipients
3Template
Setup Campaign
Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean garlic. Beetroot water spinach okra water chestnut ricebean pea catsear courgette.
Nori grape silver beet broccoli kombu beet greens fava bean potato quandong celery. Bunya nuts black-eyed pea prairie turnip leek lentil turnip greens parsnip. Sea lettuce lettuce water chestnut eggplant winter purslane fennel azuki bean earthnut pea sierra leone bologi leek soko chicory celtuce parsley jÃcama salsify.
Usage
Via JavaScript
$('#myWizard').wizard();
Via data-attributes
The wizard will automatically instantiate any wizards with data-initialize="wizard". If you add control markup after page load with data-initialize="wizard", this control initializes on mouseover.
Markup
Deprecated wizard markup
Before v3.8.0, the wizard control did not have a .steps-container element.
Wrap class="wizard" around a list of steps, navigation, and content within a class="fuelux" container.
For data attributes, append the option name to data-, as in data-restrict="".
Attribute
Value
Description
restrict
previous
Prevents the user from navigating to a previous step
step
1
Sets the current wizard step. Replace the value with a number of the wizard step to load on.
Options
You can pass options via Javascript upon initialization.
Name
Type
Default
Description
disablePreviousStep
boolean
false
Dictates whether the wizard should make the previous step button disabled. Setting this value to true will make the previous step button disabled
selectedItem
object
{ step: -1 }
By default { step: -1 } means it will attempt to look for "active" class in order to set the
step. Changing the step number would set the step that is loaded by default when the wizard loads.
Methods
.wizard('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup
.wizard('previous')
Moves to the previous step
.wizard('next')
Moves to the next step
.wizard('selectedItem')
Returns the current step index.
$('#myWizard').wizard('selectedItem');
.wizard('selectedItem', 3)
Moves to passed in step. This can be either an integer or the `data-name` of a step.
Required. Identifies the position used to start inserting pane(s). First pane exists at position 1. If you use -1, the item will append to end of the list of panes.
[item1, ..., itemX] item1, ..., itemX
Identifies an array or list of content pane objects to add at the index. Each pane can contain three strings:
a badge class to be appended to the class attribute of the step in order to override the default number
Required. Identifies the position where to begin removing pane(s). First pane exists at position 1.
howMany
Optional. Specifies the number of panes to removed. Defaults to 1.
Events
Event Type
Description
actionclicked.fu.wizard
This event fires immediately when the step changes, but before the wizard shows the new step. Use event.preventDefault() to cancel the event. Arguments include event, data where data is an object { step:1, direction:'next' }.
changed.fu.wizard
This event fires when the step changes and displays to the user.
finished.fu.wizard
This event fires when the user clicks the next button on the last step of the wizard.
stepclicked.fu.wizard
This event fires when the user clicks a completed step. Use event.preventDefault to cancel the event.
All wizard events are fired on the .wizard classed element.
$('#myWizard').on('actionclicked.fu.wizard', function (evt, data) {
// do something
});
Examples
Wrap the input and wizard button within .fuelux .wizard
1Campaign
2Recipients
3Template
Setup Campaign
Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean garlic. Beetroot water spinach okra water chestnut ricebean pea catsear courgette.