Features

• No images, no external CSS
• No dependencies (jQuery is supported, but not required)
• Highly configurable
• Resolution independent
• Uses VML as fallback in old IEs
• Uses @keyframe animations, falling back to setTimeout()
• Works in all major browsers, including IE6
• MIT License

Usage

var opts = {
 lines: 12, // The number of lines to draw
 length: 7, // The length of each line
 width: 5, // The line thickness
 radius: 10, // The radius of the inner circle
 corners: 1, // Corner roundness (0..1)
 rotate: 0, // The rotation offset
 color: '#000', // #rgb or #rrggbb
 speed: 1, // Rounds per second
 trail: 100, // Afterglow percentage
 shadow: true, // Whether to render a shadow
 hwaccel: false, // Whether to use hardware acceleration
 className: 'spinner', // The CSS class to assign to the spinner
 zIndex: 2e9, // The z-index (defaults to 2000000000)
 top: 'auto', // Top position relative to parent in px
 left: 'auto' // Left position relative to parent in px
};
var target = document.getElementById('foo');
var spinner = new Spinner(opts).spin(target);

The spin() method creates the necessary HTML elements and starts the animation. If a target element is passed as argument, the spinner is added as first child and horizontally and vertically centered.

Manual positioning

By default the spinner is centered within the target element. Alternatively you may specify a top and left option to position the spinner relative to the target element.

In order to manually insert the spinner into the DOM you can invoke the spin() method without any arguments and use the el property to access the HTML element:

var spinner = new Spinner().spin();
target.appendChild(spinner.el);

The returned element is a DIV with position:relative and no height. The center of the spinner is positioned at the top left corner of this DIV.

Hiding the spinner

To hide the spinner, invoke the stop() method, which removes the UI elements from the DOM and stops the animation. Stopped spinners may be reused by calling spin() again.

jQuery plugin

Spin.js does not require jQuery. Anyway, if you use jQuery (or zepto.js) you may use the following plugin:

$.fn.spin = function(opts) {
 this.each(function() {
 var $this = $(this),
 data = $this.data();
 if (data.spinner) {
 data.spinner.stop();
 delete data.spinner;
 }
 if (opts !== false) {
 data.spinner = new Spinner($.extend({color: $this.css('color')}, opts)).spin(this);
 }
 });
 return this;
};

Alternatively you may use this advanced version written by Bradley Smith.

Supported browsers

Spin.js has been successfully tested in the following browsers:

• Chrome
• Safari 3.2+
• Firefox 3.5+
• IE 6,7,8,9
• Opera 10.6+
• Mobile Safari (iOS 3.1+)
• Android 2.3+

Changes

Version 1.2.7 (2.10.2012)

• Added an option to set the position porperty. See issue #98
• Added a trailing semicolon to support concatenation tools that don't know about ASI.

Version 1.2.6 (30.08.2012)

• Added an option to set the border-radius. See issue #93
• Fix for Opera 12. See issue #87
• Fix for IE. See issue #77
• Fixed an issue with very wide target elements. See issue #78

Version 1.2.5 (22.03.2012)

• Fixed a bug that prevented the VML from being displayed when Modernizr or html5shiv was used.
• Added a rotate option. See issue #60.
• The constructor property is now preserved. See issue #61.

Version 1.2.4 (28.02.2012)

• Added new config options: top, left, zIndex and className.

Version 1.2.3 (30.01.2012)

Version 1.2.2 (8.11.2011)

• Fixed a cross-domain issue with the dynamically created stylesheet. See issue #36.

Version 1.2.1 (5.10.2011)

Version 1.2 (16.9.2011)

• Calling spin() now invokes stop() first. See issue #28.
• Added a workaround for the IE negative margin bug. See issue #27.
• The new operator is now optional. See issue #14.
• Improved accessibility by adding aria-role="progressbar".

Version 1.1 (6.9.2011)

• Fixed a bug where the animation occasionally got out of sync in Mobile Safari and Android's built-in WebKit.
• Fixed a bug where the spinner was misplaced when the target element had a non-zero padding.
• Optimized the code for gzip compression. While the minified version got slightly larger, the zipped version now only weighs 1.7K.

Version 1.0 (16.8.2011)

Contact

If you encounter any problems, please use the GitHub issue tracker.
For updates follow me on Twitter.
If you like spin.js and use it in the wild, let me know.

Holder.js

Holder renders image placeholders entirely on the client side.

It works both online and offline, and offers a chainable API to style and create placeholders with ease.

Download Holder.js (4KB)

Usage

<img src="holder.js/300x200">

Documentation

View detailed documentation at the Holder.js GitHub page.

Credits

Made by Ivan Malopinsky.

Parameter Type Description minimumInputLength int Number of characters necessary to start a search minimumResultsForSearch int

The minimum number of results that must be initially (after opening the dropdown for the first time) populated in order to keep the search field. This is useful for cases where local data is used with just a few results, in which case the search box is not very useful and wastes screen space.

Only applies to single-value select boxes

placeholder object/string

Initial value that is selected if no other selection is made.

The value can be specified either as an object or as a string. If specified as a string any custom formatSelection function will be bypassed and the string value will be rendered directly.

The placeholder can also be specified as a data-placeholder attribute on the select or input element that Select2 is attached to. In this case only string values are supported

Note that because browsers assume the first option element is selected in non-multi-value select boxes an empty first option element must be provided (<option></option>) for the placeholder to work.

When Select2 is used in multi-select mode the placeholder must be a string.

allowClear boolean

Whether or not a clear button is displayed when the select box has a selection. The button, when clicked, resets the value of the select box back to the placeholder, thus this option is only available when the placeholder is specified.

When attached to a select an option with an empty value must be provided. This is the option that will be selected when the button is pressed since a select box requires at least one selection option.

Also, note that this option only works with non-multi-value based selects because multi-value selects always provide such a button for every selected option.

multiple boolean

Whether or not Select2 allows selection of multiple values.

When Select2 is attached to a select element this value will be ignored and select's multiple attribute will be used instead.

closeOnSelect boolean

If set to true the dropdown is not closed after a selection is made, allowing for rapid selection of multiple items. By default this option is disabled.

Only applies when configured in multi-select mode.

id function Function used to get the id from the choice object or a string representing the key under which the id is stored.

id(object)

Parameter	Type	Description
object	object	A choice object
<returns>	string	the id of the object

The default implementation expects the object to have a id property that is returned. matcher function Used to determine whether or not the search term matches an option when a built-in query function is used. The built in query function is used when Select2 is attached to a select, or the local or tags helpers are used.

matcher(term, text)

Parameter	Type	Description
term	string	search term
text	string	text of the option being matched
<returns>	boolean	true if search term matches the option text, or false otherwise

The default implementation is case insensitive and matches anywhere in ther term: function(term, text) { return text.toUpperCase().indexOf(term.toUpperCase())>0; } formatSelection function Function used to render the current selection.

formatSelection(object)

Parameter	Type	Description
object	object	The selected result object returned from the query function
<returns>	string	Html that represents the selection

The default implementation expects the object to have a text property that is returned. formatResult function Function used to render a result that the user can select.

formatResult(object)

Parameter	Type	Description
object	object	One of the result objects returned from the query function
<returns>	string	Html that represents the result

The default implementation expects the object to have a text property that is returned. formatNoMatches function Function used to render the "No matches" message

formatNoMatches(term)

Parameter	Type	Description
term	string	Search string entered by user
<returns>	string	Message html

formatInputTooShort function Function used to render the "Search input too short" message

formatInputTooShort(term, minLength)

Parameter	Type	Description
term	string	Search string entered by user
minLength	int	Minimum required term length
<returns>	string	Message html

createSearchChoice function Creates a new selectable choice from user's search term. Allows creation of choices not available via the query function. Useful when the user can create choices on the fly, eg for the 'tagging' usecase.

createSearchChoice(term)

Parameter	Type	Description
term	string	Search string entered by user
<returns>	object (optional)	Object representing the new choice. Must at least contain an id attribute.

If the function returns undefined or null no choice will be created. If a new choice is created it is displayed first in the selection list so that user may select it by simply pressing enter.

When used in combination with input[type=hidden] tag care must be taken to sanitize the id attribute of the choice object, especially stripping , as it is used as a value separator

initSelection function Called when Select2 is created to allow the user to initialize the selection based on the value of the element select2 is attached to.

Essentially this is an id->object mapping function.

initSelection(element)

Parameter	Type	Description
element	jQuery array	element Select2 is attached to
<returns>	object or array of objects	Object representing the choice to be selected, or an array of such objects in case Select2 is in multi mode.

This function will only be called when there is initial input to be processed.

Here is an example implementation used for tags. Tags are the simplest form of data where the id is also the text:

$("#tags").select2({
 initSelection : function (element) {
 var data = [];
 $(element.val().split(",")).each(function () {
 data.push({id: this, text: this});
 });
 return data;
 }
});

query function Function used to query results for the search term.

query(options)

Parameter	Type	Description
options.term	string	Search string entered by user
options.page	int	1-based page number tracked by Select2 for use with infinite scrolling of results
options.context	object	An object that persists across the lifecycle of queries for the same search term (the query to retrieve the initial results, and subsequent queries to retrieve more result pages for the same search term). When this function is first called for a new search term this object will be null. The user may choose to set any object in the results.context field - this object will then be used as the context parameter for all calls to the query method that will load more search results for the initial search term. The object will be reset back to null when a new search term is queried. This feature is useful when a page number is not easily mapped against the server side paging mechanism. For example, some server side paging mechanism may return a "continuation token" that needs to be passed back to them in order to retrieve the next page of search results.
options.callback	function	Callback function that should be called with the result object. The result object: Parameter Type Description result.results [object] Array of result objects. The default renderers expect objects with id and text keys. The id attribute is required, even if custom renderers are used. result.more boolean trueif more results are available for the current search term results.context object A user-defined object that should be made available as the context parameter to the query function on subsequent queries to load more result pages for the same search term. See the description of options.context parameter.

In order for this function to work Select2 should be attached to a input type='hidden' tag instead of a select.

ajax object Options for the built in ajax query function. This object acts as a shortcut for having to manually write a function that performs ajax requests. The built-in function supports more advanced features such as throttling and dropping out-of-order responses.

Parameter	Type	Description
transport	function	Function that will be used to perform the ajax request. Must be parameter-compatible with $.ajax. Defaults to $.ajax if not specified. Allows the use of various ajax wrapper libraries such as: AjaxManager.
url	string	Ajax url
dataType	string	Data type for the request. ajax, jsonp, other formats supported by jquery
quietMillis	int	Number of milliseconds to wait for the user to stop typing before issuing the ajax request
data	function	Function to generate query parameters for the ajax request. data(term, page) Parameter Type Description term string Search term page int 1-based page number tracked by Select2 for use with infinite scrolling of results context object See options.context parameter to the query function above. <returns> object Object containing url paramters
results	function	Function used to build the query results object from the ajax response results(data, page) Parameter Type Description data object Retrieved data page int Page number that was passed into the data function above context object See options.context parameter to the query function above. <returns> object Results object. See "options.callback" in the "query" function for format.

In order for this function to work Select2 should be attached to a input type='hidden' tag instead of a select.

data array/object Options for the built in query function that works with arrays.

If this element contains an array, each element in the array must contain id and text keys

Alternatively, this element can be specified as an object in which results key must contain the data as an array and a text key can either be the name of the key in data items that contains text or a function that retrieves the text given a data element from the array

tags array/function Puts Select2 into 'tagging'mode where the user can add new choices and pre-existing tags are provided via this options attribute which is either an array or a function that returns an array of objects or strings. If strings are used instead of objects they will be converted into an object that has an id and text attribute equal to the value of the string.

Gets or sets the selection. If the value parameter is not specified, the id attribute of the currently selected element is returned. If the value parameter is specified it will become the current selection.

Reverts changes to DOM done by Select2. Any selection done via Select2 will be preserved.

Disables Select2. During this mode the user is not allowed to manipulate the selection.

Enables Select2.

Retrieves the main container element that wraps all of DOM added by Select2 Example: console.log($("#tags").select2("container"));

Notifies Select2 that a drag and drop sorting operation has started. Select2 will hide all non-selection list items such as the search container, etc. Example: $("#tags").select2("onSortStart");

Notifies Select2 that a drag and drop sorting operation has finished. Select2 will re-display any elements previously hidden and update the selection of the element it is attached to. Example: $("#tags").select2("onSortEnd");