There are more modules; a list of all modules
is available in the README.
Zepto is a good choice for browser extensions (for Safari and Chrome) and
to develop HTML-based views within native app frameworks, such as
PhoneGap.
In short, Zepto is expected to work in every modern browser
and browser-like environment, except for Internet Explorer.
Refer to the README
for instructions on how to build Zepto, including running the tests and
contributing patches.
To get started with plug-in development, take a look at the
source of Zepto's core module,
and be sure to read the
coding style guidelines.
Core methods
$()
$(selector, [context]) ⇒ collection
$(<Zepto collection>) ⇒ same collection
$(<DOM nodes>) ⇒ collection
$(htmlString) ⇒ collection
$(htmlString, attributes) ⇒ collection [v1.0]
Zepto(function($){ ... })
Create a Zepto collection object by performing a CSS selector, wrapping DOM
nodes, or creating elements from an HTML string.
A Zepto collection is an array-like object that has chainable methods for
manipulating the DOM nodes it references. All of the methods in this documentation
are collection methods, except the ones directly on the dollar (Zepto
) object,
such as $.extend
.
If a context (CSS selector, DOM node or Zepto collection object) is
given, perform the CSS selector only within nodes of the context; this is
functionally the same as calling $(context).find(selector)
.
When an HTML string is given, use it to create DOM nodes. If an attributes map
is given via argument, apply them to all created elements. For fast single
element creation, use <div>
or <div/>
forms.
When a function is given, attach it as a handler for the DOMContentLoaded
event.
If the page is already loaded, executes the function immediately.
$('div') //=> all DIV elements on the page
$('#foo') //=> element with ID "foo"
// create element:
$("<p>Hello</p>") //=> the new P element
// create element with attributes:
$("<p />", { text:"Hello", id:"greeting", css:{color:'darkblue'} })
//=> <p id=greeting style="color:darkblue">Hello</p>
// execute callback when the page is ready:
Zepto(function($){
alert('Ready to Zepto!')
})
jQuery
CSS extensions are not supported.
However, the optional "selector" module provides
limited support for a few of the most used pseudo-selectors, and can be
dropped in for compatibility with existing code or plugins.
Zepto will only set the $
global to itself if it is not yet defined.
This allows you to use Zepto with legacy code that uses, for example,
Prototype.js. Just load Prototype first, and Zepto will not touch
Prototype's $
function. Zepto will always set the Zepto
global
to itself.
$.camelCase
v1.0+
$.camelCase(string) ⇒ string
Turn a dasherized string into “camel case”. Doesn’t affect already camel-cased
strings.
$.camelCase('hello-there') //=> "helloThere"
$.camelCase('helloThere') //=> "helloThere"
$.contains
v1.0+
$.contains(parent, node) ⇒ boolean
Check if the parent node contains the given DOM node. Returns false if both
are the same node.
$.each
$.each(collection, function(index, item){ ... }) ⇒ collection
Iterate over array elements or object key-value pairs. Returning
false
from the iterator function stops the iteration.
$.each(['a', 'b', 'c'], function(index, item){
console.log('item %d is: %s', index, item)
})
var hash = { name: '../../../../zepto.js', size: 'micro' }
$.each(hash, function(key, value){
console.log('%s: %s', key, value)
})
$.extend
$.extend(target, [source, [source2, ...]]) ⇒ target
$.extend(true, target, [source, ...]) ⇒ target [v1.0]
Extend target object with properties from each of the source objects,
overriding the properties on target.
By default, copying is shallow. An optional true
for the first argument
triggers deep (recursive) copying.
var target = { one: 'patridge' },
source = { two: 'turtle doves' }
$.extend(target, source)
//=> { one: 'patridge',
// two: 'turtle doves' }
$.fn
Zepto.fn
is an object that holds all of the methods that are available on
Zepto collections, such as addClass()
, attr()
, and
other. Adding a function to this object makes that method available on every
Zepto collection.
Here’s an example implementation of Zepto’s empty()
method:
$.fn.empty = function(){
return this.each(function(){ this.innerHTML = '' })
}
$.grep
v1.0+
$.grep(items, function(item){ ... }) ⇒ array
Get a new array containing only the items for which the callback function
returned true.
$.inArray
v1.0+
$.inArray(element, array, [fromIndex]) ⇒ number
Get the position of element inside an array, or -1
if not found.
$.isArray
$.isArray(object) ⇒ boolean
True if the object is an array.
$.isFunction
$.isFunction(object) ⇒ boolean
True if the object is a function.
$.isPlainObject
v1.0+
$.isPlainObject(object) ⇒ boolean
True if the object is a “plain” JavaScript object, which is only true for object
literals and objects created with new Object
.
$.isPlainObject({}) // => true
$.isPlainObject(new Object) // => true
$.isPlainObject(new Date) // => false
$.isPlainObject(window) // => false
$.isWindow
v1.0+
$.isWindow(object) ⇒ boolean
True if the object is a window object. This is useful for iframes where each one
has its own window, and where these objects fail the regular obj === window
check.
$.map
$.map(collection, function(item, index){ ... }) ⇒ collection
Iterate through elements of collection and return all results of running the
iterator function, with null
and undefined
values filtered out.
$.parseJSON
v1.0+
$.parseJSON(string) ⇒ object
Alias for the native JSON.parse
method.
$.trim
v1.0+
$.trim(string) ⇒ string
Remove whitespace from beginning and end of a string; just like
String.prototype.trim().
$.type
v1.0+
$.type(object) ⇒ string
Get string type of an object. Possible types are:
null undefined boolean number string function array date regexp object error.
For other objects it will simply report “object”. To find out if an object is a
plain JavaScript object, use isPlainObject.
add
add(selector, [context]) ⇒ self
Modify the current collection by adding the results of performing the CSS
selector on the whole document, or, if context is given, just inside context
elements.
addClass
addClass(name) ⇒ self
addClass(function(index, oldClassName){ ... }) ⇒ self
Add class name to each of the elements in the collection. Multiple class
names can be given in a space-separated string.
after
after(content) ⇒ self
Add content to the DOM after each elements in the collection. The content can
be an HTML string, a DOM node or an array of nodes.
$('form label').after('<p>A note below the label</p>')
append
append(content) ⇒ self
Append content to the DOM inside each individual element in the collection. The
content can be an HTML string, a DOM node or an array of nodes.
$('ul').append('<li>new list item</li>')
appendTo
appendTo(target) ⇒ self
Append elements from the current collection to the target element. This is
like append, but with reversed operands.
$('<li>new list item</li>').appendTo('ul')
attr
attr(name) ⇒ string
attr(name, value) ⇒ self
attr(name, function(index, oldValue){ ... }) ⇒ self
attr({ name: value, name2: value2, ... }) ⇒ self
Read or set DOM attributes. When no value is given, reads specified attribute
from the first element in the collection. When value is given, sets the
attribute to that value on each element in the collection. When value is null,
the attribute is removed (like with removeAttr). Multiple
attributes can be set by passing an object with name-value pairs.
To read DOM properties such as checked
or selected
, use prop.
var form = $('form')
form.attr('action') //=> read value
form.attr('action', '/create') //=> set value
form.attr('action', null) //=> remove attribute
// multiple attributes:
form.attr({
action: '/create',
method: 'post'
})
before
before(content) ⇒ self
Add content to the DOM before each element in the collection. The content can
be an HTML string, a DOM node or an array of nodes.
$('table').before('<p>See the following table:</p>')
children
children([selector]) ⇒ collection
Get immediate children of each element in the current collection. If selector
is given, filter the results to only include ones matching the CSS selector.
$('ol').children('*:nth-child(2n)')
//=> every other list item from every ordered list
clone
v1.0+
clone() ⇒ collection
Duplicate all elements in the collection via deep clone.
This method doesn't have an option for copying data and event handlers over to
the new elements, as it has in jQuery.
closest
closest(selector, [context]) ⇒ collection
closest(collection) ⇒ collection [v1.0]
closest(element) ⇒ collection [v1.0]
Traverse upwards from the current element to find the first element that
matches the selector. If context node is given, consider only elements that are
its descendants. This method is similar to parents(selector)
, but
it only returns the first ancestor matched.
If a Zepto collection or element is given, the resulting element will have to
match one of the given elements instead of a selector.
var input = $('input[type=text]')
input.closest('form')
concat
concat(nodes, [node2, ...]) ⇒ self
Modify the collection by adding elements to it. If any of the arguments is an
array, its elements are merged into the current collection.
This is a Zepto-provided method that is not part of the jQuery API.
contents
v1.0+
contents() ⇒ collection
Get the children of each element in the collection, including text
and comment nodes.
css
css(property) ⇒ value
css(property, value) ⇒ self
css({ property: value, property2: value2, ... }) ⇒ self
Read or set CSS properties on DOM elements. When no value is given, returns the CSS
property from the first element in the collection. When a value is given, sets the
property to that value on each element of the collection. Multiple properties
can be set by passing an object to the method.
When a value for a property is blank (empty string, null, or undefined), that
property is removed. When a unitless number value is given, “px” is appended to
it for properties that require units.
var elem = $('h1')
elem.css('background-color') // read property
elem.css('background-color', '#369') // set property
elem.css('background-color', '') // remove property
// set multiple properties:
elem.css({ backgroundColor: '#8EE', fontSize: 28 })
data
data(name) ⇒ value
data(name, value) ⇒ self
Read or write data-*
DOM attributes. Behaves like attr, but prepends
data-
to the attribute name.
When reading attribute values, the following conversions apply:
v1.0+
- “true”, “false”, and “null” are converted to corresponding types;
- number values are converted to actual numeric types;
- JSON values are parsed, if it’s valid JSON;
- everything else is returned as string.
Zepto's basic implementation of `data()` only stores strings.
To store arbitrary objects, include the optional "data" module
in your custom build of Zepto.
each
each(function(index, item){ ... }) ⇒ self
Iterate through every element of the collection. Inside the iterator function,
this
keyword refers to the current item (also passed as the second argument to
the function). If the iterator function returns false
, iteration stops.
$('form input').each(function(index){
console.log('input %d is: %o', index, this)
})
empty
empty() ⇒ self
Clear DOM contents of each element in the collection.
eq
eq(index) ⇒ collection
Get the item at position specified by index from the current collection.
$('li').eq(0) //=> only the first list item
$('li').eq(-1) //=> only the last list item
filter
filter(selector) ⇒ collection
filter(function(index){ ... }) ⇒ collection [v1.0]
Filter the collection to contain only items that match the CSS selector.
If a function is given, return only elements for which the function
returns a truthy value. Inside the function, the this
keyword refers to
the current element.
For the opposite, see not.
find
find(selector) ⇒ collection
find(collection) ⇒ collection [v1.0]
find(element) ⇒ collection [v1.0]
Find elements that match CSS selector executed in scope of nodes in the
current collection.
If a Zepto collection or element is given, filter those elements down to only
ones that are descendants of element in the current collection.
var form = $('#myform')
form.find('input, select')
first
first() ⇒ collection
Get the first element of the current collection.
forEach
forEach(function(item, index, array){ ... }, [context])
Iterate through every element of the collection. Similar to each, but
the arguments for the iterator functions are different, and returning false
from the iterator won’t stop the iteration.
This is a Zepto-provided method that is not part of the jQuery API.
get
get() ⇒ array
get(index) ⇒ DOM node
Get all elements or a single element from the current collection. When no index
is given, returns all elements in an ordinary array. When index is specified,
return only the element at that position. This is different than eq in
the way that the returned node is not wrapped in a Zepto collection.
var elements = $('h2')
elements.get() //=> get all headings as an array
elements.get(0) //=> get first heading node
has
v1.0+
has(selector) ⇒ collection
has(node) ⇒ collection
Filter the current collection to include only elements that have any number of
descendants that match a selector, or that contain a specific DOM node.
$('ol > li').has('a[href]')
//=> get only LI elements that contain links
hasClass
hasClass(name) ⇒ boolean
Check if any elements in the collection have the specified class.
height
height() ⇒ number
height(value) ⇒ self
height(function(index, oldHeight){ ... }) ⇒ self
Get the height of the first element in the collection; or set the height of all elements in the collection.
$('#foo').height() // => 123
$(window).height() // => 838 (viewport height)
$(document).height() // => 22302
hide
hide() ⇒ self
Hide elements in this collection by setting their display
CSS property to
none
.
html
html() ⇒ string
html(content) ⇒ self
html(function(index, oldHtml){ ... }) ⇒ self
Get or set HTML contents of elements in the collection. When no content given,
returns innerHTML of the first element. When content is given, use it to replace
contents of each element. Content can be any of the types described in
append.
// autolink everything that looks like a Twitter username
$('.comment p').html(function(idx, oldHtml){
return oldHtml.replace(/(^|\W)@(\w{1,15})/g,
'$1@<a href="http://twitter.com/$2">$2</a>')
})
index
index([element]) ⇒ number
Get the position of an element. When no element is given, returns position of
the current element among its siblings. When an element is given, returns its
position in the current collection. Returns -1
if not found.
$('li:nth-child(2)').index() //=> 1
indexOf
indexOf(element, [fromIndex]) ⇒ number
Get the position of an element in the current collection. If fromIndex number is
given, search only from that position onwards. Returns the 0-based position when
found and -1
if not found. Use of index is recommended over this
method.
This is a Zepto-provided method that is not part of the jQuery API.
insertAfter
insertAfter(target) ⇒ self
Insert elements from the current collection after the target element in the
DOM. This is like after, but with reversed operands.
$('<p>Emphasis mine.</p>').insertAfter('blockquote')
insertBefore
insertBefore(target) ⇒ self
Insert elements from the current collection before each of the target elements
in the DOM. This is like before, but with reversed operands.
$('<p>See the following table:</p>').insertBefore('table')
is
is(selector) ⇒ boolean
Check if the first element of the current collection matches the CSS selector.
For basic support of jQuery’s non-standard pseudo-selectors such as :visible
,
include the optional “selector” module.
jQuery
CSS extensions are not supported. The optional "selector" module only
provides limited support for few of the most used ones.
last
last() ⇒ collection
Get the last element of the current collection.
map
map(function(index, item){ ... }) ⇒ collection
Iterate through all elements and collect the return values of the iterator
function. Inside the iterator function, this
keyword refers to the current
item (also passed as the second argument to the function).
Returns a collection of results of iterator function, with null
and
undefined
values filtered out.
// get text contents of all elements in collection
elements.map(function(){ return $(this).text() }).get().join(', ')
next
next() ⇒ collection
next(selector) ⇒ collection [v1.0]
Get the next sibling—optinally filtered by selector—of each element in the
collection.
$('dl dt').next() //=> the DD elements
not
not(selector) ⇒ collection
not(collection) ⇒ collection
not(function(index){ ... }) ⇒ collection
Filter the current collection to get a new collection of elements that don’t
match the CSS selector. If another collection is given instead of selector,
return only elements not present in it. If a function is given, return only
elements for which the function returns a falsy value. Inside the function,
the this
keyword refers to the current element.
For the opposite, see filter.
offset
offset() ⇒ object
offset(coordinates) ⇒ self [v1.0]
offset(function(index, oldOffset){ ... }) ⇒ self [v1.0]
Get position of the element in the document. Returns an object with properties:
top
, left
, width
and height
.
When given an object with properties left
and top
, use those values to
position each element in the collection relative to the document.
offsetParent
v1.0+
offsetParent() ⇒ collection
Find the first ancestor element that is positioned, meaning its CSS position
value is “relative”, “absolute” or “fixed”.
parent
parent([selector]) ⇒ collection
Get immediate parents of each element in the collection. If CSS selector is
given, filter results to include only ones matching the selector.
parents
parents([selector]) ⇒ collection
Get all ancestors of each element in the collection. If CSS selector is given,
filter results to include only ones matching the selector.
To get only immediate parents, use parent. To only get the first
ancestor that matches the selector, use closest.
$('h1').parents() //=> [<div#container>, <body>, <html>]
pluck
pluck(property) ⇒ array
Get values from a named property of each element in the collection, with null
and undefined
values filtered out.
$('body > *').pluck('nodeName') // => ["DIV", "SCRIPT"]
// implementation of Zepto's `next` method
$.fn.next = function(){
return $(this.pluck('nextElementSibling'))
}
This is a Zepto-provided method that is not part of the jQuery API.
position
v1.0+
position() ⇒ object
Get the position of the first element in the collection, relative to the
offsetParent. This information is useful when absolutely
positioning an element to appear aligned with another.
Returns an object with properties: top
, left
.
var pos = element.position()
// position a tooltip relative to the element
$('#tooltip').css({
position: 'absolute',
top: pos.top - 30,
left: pos.left
})
prepend
prepend(content) ⇒ self
Prepend content to the DOM inside each element in the collection. The content
can be an HTML string, a DOM node or an array of nodes.
$('ul').prepend('<li>first list item</li>')
prependTo
prependTo(target) ⇒ self
Prepend elements of the current collection inside each of the target elements. This is
like prepend, only with reversed operands.
$('<li>first list item</li>').prependTo('ul')
prev
prev() ⇒ collection
prev(selector) ⇒ collection [v1.0]
Get the previous sibling—optionally filtered by selector—of each element in
the collection.
prop
v1.0+
prop(name) ⇒ value
prop(name, value) ⇒ self
prop(name, function(index, oldValue){ ... }) ⇒ self
Read or set properties of DOM elements. This should be preferred over attr in
case of reading values of properties that change with user interaction over
time, such as checked
and selected
.
push
push(element, [element2, ...]) ⇒ self
Add elements to the end of the current collection.
This is a Zepto-provided method that is not part of the jQuery API.
ready
ready(function($){ ... }) ⇒ self
Attach an event handler for the “DOMContentLoaded” event that fires when the DOM
on the page is ready. It’s recommended to use the $() function instead
of this method.
reduce
reduce(function(memo, item, index, array){ ... }, [initial]) ⇒ value
Identical to Array.reduce that iterates over current collection.
This is a Zepto-provided method that is not part of the jQuery API.
remove
remove() ⇒ self
Remove elements in the current collection from their parent nodes, effectively
detaching them from the DOM.
removeAttr
removeAttr(name) ⇒ self
Remove the specified attribute from all elements in the collection.
removeClass
removeClass([name]) ⇒ self
removeClass(function(index, oldClassName){ ... }) ⇒ self
Remove the specified class name from all elements in the collection. When the
class name isn’t given, remove all class names. Multiple class names can be given in a space-separated string.
replaceWith
replaceWith(content) ⇒ self
Replace each element in the collection—both its contents and the element
itself—with the new content. Content can be of any type described in
before.
scrollTop
v1.0+
scrollTop() ⇒ number
Gets the value of how many pixels were scrolled so far on window or scrollable
element on the page.
show
show() ⇒ self
Restore the default value for the “display” property of each element in the
array, effectively showing them if they were hidden with hide.
siblings
siblings([selector]) ⇒ collection
Get all sibling nodes of each element in the collection. If CSS selector is
specified, filter the results to contain only elements that match the selector.
size
size() ⇒ number
Get the number of elements in this collection.
slice
slice(start, [end]) ⇒ array
Extract the subset of this array, starting at start
index. If end
is
specified, extract up to but not including end
index.
text
text() ⇒ string
text(content) ⇒ self
Get or set the text content of elements in the collection. When no content is
given, returns the text content of the first element in the collection. When
content is given, uses it to replace the text contents of each element in the
collection. This is similar to html, with the exception it can’t be
used for getting or setting HTML.
toggle
toggle([setting]) ⇒ self
Toggle between showing and hiding each of the elements, based on whether the
first element is visible or not. If setting
is present, this method behaves
like show if setting is truthy or hide otherwise.
var input = $('input[type=text]')
$('#too_long').toggle(input.val().length > 140)
toggleClass
toggleClass(names, [setting]) ⇒ self
toggleClass(function(index, oldClassNames){ ... }, [setting]) ⇒ self
Toggle given class names (space-separated) in each element in the collection.
The class name is removed if present on an element; otherwise it’s added. If
setting
is present, this method behaves like addClass if setting
is truthy or removeClass otherwise.
unwrap
unwrap() ⇒ self
Remove immediate parent nodes of each element in the collection and put their
children in their place. Basically, this method removes one level of ancestry
while keeping current elements in the DOM.
$(document.body).append('<div id=wrapper><p>Content</p></div>')
$('#wrapper p').unwrap().parents() //=> [<body>, <html>]
val
val() ⇒ string
val(value) ⇒ self
val(function(index, oldValue){ ... }) ⇒ self
Get or set the value of form controls. When no value is given, return
the value of the first element. For <select multiple>
, an array of values
is returend. When a value is given, set all elements to this value.
width
width() ⇒ number
width(value) ⇒ self
width(function(index, oldWidth){ ... }) ⇒ self
Get the width of the first element in the collection; or set the width of all elements in the collection.
$('#foo').width() // => 123
$(window).width() // => 768 (viewport width)
$(document).width() // => 768
wrap
wrap(structure) ⇒ self
wrap(function(index){ ... }) ⇒ self [v1.0]
Wrap each element of the collection separately in a DOM structure. Structure can
be a single element or several nested elements, and can be passed in as a HTML
string or DOM node, or as a function that is called for each element and returns
one of the first two types.
Keep in mind that wrapping works best when operating on nodes that are part
of the DOM. When calling wrap()
on a new element and then inserting the result
in the document, the element will lose the wrapping.
// wrap each button in a separate span:
$('.buttons a').wrap('<span>')
// wrap each code block in a div and pre:
$('code').wrap('<div class=highlight><pre /></div>')
// wrap all form inputs in a span with classname
// corresponding to input type:
$('input').wrap(function(index){
return '<span class=' + this.type + 'field />'
})
//=> <span class=textfield><input type=text /></span>,
// <span class=searchfield><input type=search /></span>
// WARNING: will not work as expected!
$('<em>broken</em>').wrap('<li>').appendTo(document.body)
// do this instead:
$('<em>better</em>').appendTo(document.body).wrap('<li>')
wrapAll
wrapAll(structure) ⇒ self
Wrap all elements in a single structure. Structure can be a single element or
several nested elements, and can be passed in as a HTML string or DOM node.
// wrap all buttons in a single div:
$('a.button').wrapAll('<div id=buttons />')
wrapInner
wrapInner(structure) ⇒ self
wrapInner(function(index){ ... }) ⇒ self [v1.0]
Wrap the contents of each element separately in a structure. Structure can be
a single element or several nested elements, and can be passed in as a HTML string
or DOM node, or as a function that is called for each element and returns one of
the first two types.
// wrap the contents of each navigation link in a span:
$('nav a').wrapInner('<span>')
// wrap the contents of each list item in a paragraph and emphasis:
$('ol li').wrapInner('<p><em /></p>')
Detect methods
Detect module
The “detect” module is useful to fine-tune your site or app to different environments, and helps you to discern between phone and tablets; as well as different browser engines and operating system versions.
// The following boolean flags are set to true if they apply,
// if not they're either set to `false` or `undefined`.
// We recommend accessing them with `!!` prefixed to coerce to a boolean.
// general device type
$.os.phone
$.os.tablet
// specific OS
$.os.ios
$.os.android
$.os.webos
$.os.blackberry
$.os.bb10
$.os.rimtabletos
// specific device type
$.os.iphone
$.os.ipad
$.os.touchpad
$.os.kindle
// specific browser
$.browser.chrome
$.browser.firefox
$.browser.silk
$.browser.playbook
// Additionally, version information is available as well.
// Here's what's returned for an iPhone running iOS 6.1.
!!$.os.phone // => true
!!$.os.iphone // => true
!!$.os.ios // => true
!!$.os.version // => "6.1"
!!$.browser.version // => "536.26"
Event handling
$.Event
$.Event(type, [properties]) ⇒ event
Create and initialize a DOM event of the specified type. If a properties object
is given, use it to extend the new event object. The event is configured to
bubble by default; this can be turned off by setting the bubbles
property to false
.
An event initialized with this function can be triggered with
trigger.
$.Event('mylib:change', { bubbles: false })
$.proxy
v1.0+
$.proxy(fn, context) ⇒ function
$.proxy(context, property) ⇒ function
Get a function that ensures that the value of this
in the original function
refers to the context object. In the second form, the original function is read
from the specific property of the context object.
var obj = {name: 'Zepto'},
handler = function(){ console.log("hello from + ", this.name) }
// ensures that the handler will be executed in the context of `obj`:
$(document).on('click', $.proxy(handler, obj))
bind
🐶🔫
Deprecated, use on instead.
bind(type, function(e){ ... }) ⇒ self
bind({ type: handler, type2: handler2, ... }) ⇒ self
Attach an event handler to elements.
delegate
🐶🔫
Deprecated, use on instead.
delegate(selector, type, function(e){ ... }) ⇒ self
delegate(selector, { type: handler, type2: handler2, ... }) ⇒ self
Attach an event handler that is only triggered when the event originated from a
node that matches a selector.
die
🐶🔫
Deprecated, use off instead.
die(type, function(e){ ... }) ⇒ self
die({ type: handler, type2: handler2, ... }) ⇒ self
Detach event handler added by live.
live
🐶🔫
Deprecated, use on instead.
live(type, function(e){ ... }) ⇒ self
live({ type: handler, type2: handler2, ... }) ⇒ self
Like delegate where the selector is taken from the current
collection.
off
off(type, [selector], function(e){ ... }) ⇒ self
off({ type: handler, type2: handler2, ... }, [selector]) ⇒ self
off(type, [selector]) ⇒ self
off() ⇒ self
Detach event handlers added with on. To detach a specific event handler,
the same function must be passed that was used for on()
. Otherwise, just
calling this method with an event type with detach all handlers of that type.
When called without arguments, it detaches all event handlers registered on
current elements.
on
on(type, [selector], function(e){ ... }) ⇒ self
on({ type: handler, type2: handler2, ... }, [selector]) ⇒ self
Add event handlers to the elements in collection. Multiple event types can be
passed in a space-separated string, or as an object where event types are keys
and handlers are values. If a CSS selector is given, the handler function will
only be called when an event originates from an element that matches the selector.
Event handlers are executed in the context of the element to which the handler
is attached, or the matching element in case a selector is provided. When an
event handler returns false
, preventDefault()
is called for the current
event, preventing the default browser action such as following links.
var elem = $('#content')
// observe all clicks inside #content:
elem.on('click', function(e){ ... })
// observe clicks inside navigation links in #content
elem.on('click', 'nav a', function(e){ ... })
// all clicks inside links in the document
$(document).on('click', 'a', function(e){ ... })
one
one(type, function(e){ ... }) ⇒ self
one({ type: handler, type2: handler2, ... }) ⇒ self
Adds an event handler that removes itself the first time it runs, ensuring that
the handler only fires once.
trigger
trigger(event, [data])
Trigger the specified event on elements of the collection. Event can either be a
string type, or a full event object obtained with $.Event. If a data
array is given, it is passed as additional arguments to event handlers.
// add a handler for a custom event
$(document).on('mylib:change', function(e, from, to){
console.log('change on %o with data %s, %s', e.target, from, to)
})
// trigger the custom event
$(document.body).trigger('mylib:change', ['one', 'two'])
Zepto only supports triggering events on DOM elements.
triggerHandler
triggerHandler(event, [data]) ⇒ self
Like trigger, but triggers only event handlers on current
elements and doesn’t bubble.
unbind
🐶🔫
Deprecated, use off instead.
unbind(type, function(e){ ... }) ⇒ self
unbind({ type: handler, type2: handler2, ... }) ⇒ self
Detach event handler added with bind.
undelegate
🐶🔫
Deprecated, use off instead.
undelegate(selector, type, function(e){ ... }) ⇒ self
undelegate(selector, { type: handler, type2: handler2, ... }) ⇒ self
Detach event handler added with delegate.
Ajax requests
$.ajax
$.ajax(options) ⇒ XMLHttpRequest
Perform an Ajax request. It can be to a local resource, or cross-domain via
HTTP access control support in browsers or JSONP.
Options:
type
(default: “GET”): HTTP request method (“GET”, “POST”, or other)
url
(default: current URL): URL to which the request is made
data
(default: none): data for the request; for GET requests it is appended
to query string of the URL. Non-string objects will get serialized with
$.param
processData
(default: true): whether to automatically serialize data
for
non-GET requests to string
contentType
(default: “application/x-www-form-urlencoded”): the Content-Type
of the data being posted to the server (this can also be set via headers
).
Pass false
to skip setting the default value.
dataType
(default: none): response type to expect from the server (“json”, “jsonp”, “xml”, “html”, or “text”)
timeout
(default: 0
): request timeout in milliseconds, 0
for no timeout
headers
: object of additional HTTP headers for the Ajax request
async
(default: true): set to false
to issue a synchronous (blocking) request
global
(default: true): trigger global Ajax events on this request
context
(default: window): context to execute callbacks in
traditional
(default: false): activate traditional (shallow) serialization
of data
parameters with $.param
If the URL contains =?
or dataType
is “jsonp”, the request is performed
by injecting a <script>
tag instead of using XMLHttpRequest (see JSONP).
This has the limitation of contentType
, dataType
, headers
, and async
not
being supported.
Ajax callbacks
You can specify the following callback functions, which are given in order of execution:
beforeSend(xhr, settings)
: before the request is sent. Provides access to
the xhr object. Return false
from the function to cancel the request
success(data, status, xhr)
: when request succeeds
error(xhr, errorType, error)
: if there is an error (timeout, parse error,
or status code not in HTTP 2xx)
complete(xhr, status)
: after the request is complete, regardless of error
or success
Ajax events
These events are fired during the lifecycle of an Ajax request performed with
the default setting of global: true
:
ajaxStart
(global): fired if no other Ajax requests are currently
active
ajaxBeforeSend
(data: xhr, options): before sending the request; can be
cancelled
ajaxSend
(data: xhr, options): like ajaxBeforeSend
, but not cancellable
ajaxSuccess
(data: xhr, options, data): when the response is success
ajaxError
(data: xhr, options, error): when there was an error
ajaxComplete
(data: xhr, options): after request has completed, regardless
of error or success
ajaxStop
(global): fired if this was the last active Ajax request
By default, Ajax events are fired on the document object. However, if the
context
of a request is a DOM node, the events are fired on that node and will
bubble up the DOM. The only exceptions to this are the global events ajaxStart
& ajaxStop
.
$(document).on('ajaxBeforeSend', function(e, xhr, options){
// This gets fired for every Ajax request performed on the page.
// The xhr object and $.ajax() options are available for editing.
// Return false to cancel this request.
})
$.ajax({
type: 'GET',
url: '/projects',
// data to be added to query string:
data: { name: '../../../../zepto.js' },
// type of data we are expecting in return:
dataType: 'json',
timeout: 300,
context: $('body'),
success: function(data){
// Supposing this JSON payload was received:
// {"project": {"id": 42, "html": "<div>..." }}
// append the HTML to context object.
this.append(data.project.html)
},
error: function(xhr, type){
alert('Ajax error!')
}
})
// post a JSON payload:
$.ajax({
type: 'POST',
url: '/projects',
// post payload:
data: JSON.stringify({ name: '../../../../zepto.js' }),
contentType: 'application/json'
})
$.ajaxJSONP
🐶🔫
Deprecated, use $.ajax instead.
$.ajaxJSONP(options) ⇒ mock XMLHttpRequest
Perform a JSONP request to fetch data from another domain.
This method has no advantages over $.ajax and should not be used.
$.ajaxSettings
Object containing the default settings for Ajax requests. Most settings are
described in $.ajax. The ones that are useful when set globally are:
timeout
(default: 0
): set to a non-zero value to specify a default timeout
for Ajax requests in milliseconds
global
(default: true): set to false to prevent firing Ajax events
xhr
(default: XMLHttpRequest factory): set to a function that returns
instances of XMLHttpRequest (or a compatible object)
accepts
: MIME types to request from the server for specific dataType
values:
- script: “text/javascript, application/javascript”
- json: “application/json”
- xml: “application/xml, text/xml”
- html: “text/html”
- text: “text/plain”
$.get
$.get(url, function(data, status, xhr){ ... }) ⇒ XMLHttpRequest
$.get(url, [data], [function(data, status, xhr){ ... }], [dataType]) ⇒ XMLHttpRequest [v1.0]
Perform an Ajax GET request. This is a shortcut for the $.ajax
method.
$.get('/whatevs.html', function(response){
$(document.body).append(response)
})
$.getJSON
$.getJSON(url, function(data, status, xhr){ ... }) ⇒ XMLHttpRequest
$.getJSON(url, [data], function(data, status, xhr){ ... }) ⇒ XMLHttpRequest [v1.0]
Get JSON data via Ajax GET request. This is a shortcut for the $.ajax
method.
$.getJSON('/awesome.json', function(data){
console.log(data)
})
// fetch data from another domain with JSONP
$.getJSON('//example.com/awesome.json?callback=?', function(remoteData){
console.log(remoteData)
})
$.param
$.param(object, [shallow]) ⇒ string
$.param(array) ⇒ string
Serialize an object to a URL-encoded string representation for use in Ajax
request query strings and post data. If shallow is set, nested objects are
not serialized and nested array values won’t use square brackets on their keys.
Also accepts an array in serializeArray format, where each
item has “name” and “value” properties.
$.param({ foo: { one: 1, two: 2 }})
//=> "foo[one]=1&foo[two]=2)"
$.param({ ids: [1,2,3] })
//=> "ids[]=1&ids[]=2&ids[]=3"
$.param({ ids: [1,2,3] }, true)
//=> "ids=1&ids=2&ids=3"
$.param({ foo: 'bar', nested: { will: 'not be ignored' }})
//=> "foo=bar&nested[will]=not+be+ignored"
$.param({ foo: 'bar', nested: { will: 'be ignored' }}, true)
//=> "foo=bar&nested=[object+Object]"
$.post
$.post(url, [data], function(data, status, xhr){ ... }, [dataType]) ⇒ XMLHttpRequest
Perform an Ajax POST request. This is a shortcut for the $.ajax
method.
$.post('/create', { sample: 'payload' }, function(response){
// process response
})
data
can also be a string:
$.post('/create', $('#some_form').serialize(), function(response){
// ...
})
load
load(url, function(data, status, xhr){ ... }) ⇒ self
Set the html contents of the current collection to the result of a GET Ajax call to the given URL. Optionally, a CSS selector can be specified in the URL, like so, to use only the HTML content matching the selector for updating the collection:
$('#some_element').load('/foo.html #bar')
If no CSS selector is given, the complete response text is used instead.
Note that any JavaScript blocks found are only executed in case no selector is given.
serialize
serialize() ⇒ string
Serialize form values to an URL-encoded string for use in Ajax post requests.
serializeArray
serializeArray() ⇒ array
Serialize form into an array of objects with name
and value
properties.
Disabled form controls, buttons, and unchecked radio buttons/checkboxes are skipped.
The result doesn’t include data from file inputs.
$('form').serializeArray()
//=> [{ name: 'size', value: 'micro' },
// { name: 'name', value: 'Zepto' }]
submit
submit() ⇒ self
submit(function(e){ ... }) ⇒ self
Trigger or attach a handler for the submit event. When no function given,
trigger the “submit” event on the current form and have it perform its submit
action unless preventDefault()
was called for the event.
When a function is given, this simply attaches it as a handler for the “submit”
event on current elements.
Effects
$.fx
Global settings for animations:
$.fx.off
(default false in browsers that support CSS transitions): set to
true to disable all animate()
transitions.
$.fx.speeds
: an object with duration settings for animations:
_default
(400 ms)
fast
(200 ms)
slow
(600 ms)
Change existing values or add new properties to affect animations that use
a string for setting duration.
animate
animate(properties, [duration, [easing, [function(){ ... }]]]) ⇒ self
animate(properties, { duration: msec, easing: type, complete: fn }) ⇒ self
animate(animationName, { ... }) ⇒ self
Smoothly transition CSS properties of elements in the current collection.
properties
: object that holds CSS values to animate to; or CSS keyframe
animation name
duration
(default 400): duration in milliseconds, or a string:
fast
(200 ms)
slow
(600 ms)
- any custom property of
$.fx.speeds
easing
(default linear
): specifies the type of animation easing to use, one of:
ease
linear
ease-in
/ ease-out
ease-in-out
cubic-bezier(...)
complete
: callback function for when the animation finishes
Zepto also supports the following CSS transform properties:
translate(X|Y|Z|3d)
rotate(X|Y|Z|3d)
scale(X|Y|Z)
matrix(3d)
perspective
skew(X|Y)
If the duration is 0
or $.fx.off
is true (default in a browser that doesn’t
support CSS transitions), animations will not be executed; instead the target
values will take effect instantly. Similarly, when the target CSS properties
match the current state of the element, there will be no animation and the
complete
function won’t be called.
If the first argument is a string instead of object, it is taken as a CSS
keyframe animation name.
$("#some_element").animate({
opacity: 0.25, left: '50px',
color: '#abcdef',
rotateZ: '45deg', translate3d: '0,10px,0'
}, 500, 'ease-out')
Zepto exclusively uses CSS transitions for effects and animation.
jQuery easings are not supported. jQuery's syntax for relative changes ("=+10px") is not supported.
See the spec for a
list of animatable properties.
Browser support may vary, so be sure to test in all browsers you want to support.
Touch
Touch events
The “touch” module adds the following events, which can be used with on and off:
tap
— fires when the element is tapped.
singleTap
and doubleTap
— this pair of events can be used to detect both single and double taps on the same element (if you don’t need double tap detection, use tap
instead).
longTap
— fires when an element is tapped and the finger is held down for more than 750ms.
swipe
, swipeLeft
, swipeRight
, swipeUp
, swipeDown
— fires when an element is swiped (optionally in the given direction)
All these events are also available via shortcut methods on any Zepto collection.
<style>.delete { display: none; }</style>
<ul id=items>
<li>List item 1 <span class=delete>DELETE</span></li>
<li>List item 2 <span class=delete>DELETE</span></li>
</ul>
<script>
// show delete buttons on swipe
$('#items li').swipe(function(){
$('.delete').hide()
$('.delete', this).show()
})
// delete row on tapping delete button
$('.delete').tap(function(){
$(this).parent('li').remove()
})
</script>
Change Log
v1.0
— 02 Mar 2013
— diff
Party like it’s one-oh!
Notable changes
- Zepto is now compatible with Twitter Bootstrap
- Portable, completely new node.js-based build system
- Fully automated tests with PhantomJS and Travis CI
- Removed
touch
module from default distribution
New features
$.fn.filter(function(index){ ... })
$.fn.contents()
$.fn.wrapInner()
$.fn.scrollTop()
$.contains()
$.fn.has()
$.fn.position()
$.fn.offsetParent()
$.parseJSON()
$.camelCase()
$.isWindow()
$.grep()
(interface to Array.filter
)
- Support
$(html, attributes)
syntax for element creation
- Emulate
mouseenter
and mouseleave
events
- Bootstrap compat: support
$.fn.offset(coordinates)
- Bootstrap compat: implement
$.fn.detach()
- Add support for Ajax
cache: false
option
- Prevent scrolling when horizontal swipe events are detected
cancelTouch
for tap events
prev
and next
now support an optional selector argument
$.fn.find
and $.fn.closest
now support Zepto objects as arguments
- Enable deep copy via
$.extend(true, target, source)
- Enable nested structures for
$.fn.wrap()
and $.fn.wrapAll()
- Enable function arguments for
$.fn.wrap()
and $.fn.wrapInner()
- Support number, boolean, JSON types in data attributes
- Support manipulating classnames on SVG elements
- Enable named durations for
animate
, e.g. slow
.
- Support
timing-function
for animate
- Support event properties passed to
$.fn.trigger()
or $.Event()
- Selector module: support child
> *
queries
- Add detect support for mobile Chrome browser
- Add
$.os.phone
and $.os.tablet
(booleans)
- Detect Firefox mobile, Playbooks and BB10
Fixes
- Fix passing null selector to
on
or off
- Fixed bug where self-closing html tags would act as open tags
- Fix
val
for multiple select
- Fix various touch and gesture bugs.
- Corrected parameters of
load
success callback to match jQuery.
- Fix
css
with 0 values and falsy values
- Fix a
css
performance issues with string values
- Fix
$.ajaxJSONP
when invoked directly
- Fix
animate
with 0 durations.
- Fix
toggle
and fadeToggle
for multiple elements.
- Fix ajax
$.fn.load
behavior with selector
- Make
attr(name, null)
unset attribute
- Fix
animate
in Firefox
- Fix
animate
for elements just added to DOM
- Fix an escaping issue with
$.param
- Respect
traditional: true
option in $.ajax
- Fix
focus
& blur
event delegation and enable unbind
- Simple wrapping for any object passed to
$()
- Enable
children
method for XML documents
- Don’t eval
<script>
content when src
is present
- Support
processData
option for $.ajax()
- Enable passing
contentType: false
to $.ajax()
- Apply
focus()
and blur()
to all elements in collection
- Change
$.fn.map()
to return a Zepto collection
- Selector argument for
on(evt, selector, fn)
can be false
- Don’t raise error on
$('#')
- Provide empty object in
$.support
return false
in event handler calls stopPropagation()
- Fix
$.isPlainObject()
for window
in Opera
$.ajax
error callback correctly reports abort
status
- Fix
hasClass
in collections of multiple elements
- Stop iteration in
each()
when the callback returns false
- Add ability to set
xhr
factory per-request
- Have
get()
method accept negative index
- Support for multiple class names in
toggleClass()
- Fix error callbacks for
ajaxJSONP
- Support optional
data
argument for various Ajax methods
- Fix DOM insertion operators for null values
- Fix dataType being set for
$.getJSON
v1.0rc1
— 09 Apr 2012
— diff
The semicolon-free edition! That’s right, we removed all trailing semicolons
from the source and tests. They were never needed anyway.
New methods:
New module:
- “selector.js” with experimental support for jQuery CSS
pseudo-selectors such as
:visible
and :first
Improvements in core:
- added missing methods for Ember.js compatibility
- improved creating DOM fragments from HTML with $()
- enable append & family to accept multiple arguments
- fix $.each context
- fix calling get without index
- fix calling val on empty collection
- using
css(property, '')
removes the property
- fix filter, is, and closest when operating on
nodes that are detached from the document
- remove
end
& andSelf
from core to the new “stack.js” plugin
- exposed important internal Zepto functions through the
$.zepto
object for
extending or overriding Zepto functionality.
- data method returns undefined when there is no data
- support camelized names in data method
Apart from improving the basic data
method in core, the “data.js” module got
improvements as well:
- better jQuery compatibility
- ability to store functions
- new
removeData
method
Ajax:
- have correct ajaxComplete argument order for JSONP abort and timeout
- JSONP requests that hit a 404 will now correctly invoke the error callback
- add support for
dataType: 'jsonp'
in $.ajax
- add support for
data
in $.ajaxJSONP
- HTTP 304 status is treated as success instead of an error
- made load more compatible with jQuery
- allow Content-Type to be set via request headers
- respect Content-Type of the response if
dataType
isn’t set
- work around Chrome CORS bug when data is empty
Changes in other modules:
- fix animate for edge cases such as when there is an animation
within an animated element, and improve handling of transition CSS properties
- new “singleTap” event
- improved “longTap” detection
0.8
— 03 Nov 2011
— diff
- CSS transitions for every browser with
animate()
method;
- unified event handling with
fn.on()
& off()
;
- Ajax global events & timeout support;
- performance boost for selectors.
See full release notes.
0.7
— 01 Aug 2011
— diff
- add
$.each
, $.map
, $.slice
;
- add
.serializeArray()
, .serialize()
;
- add
.triggerHandler()
;
- add
.wrap
, .wrapAll
, .unwrap
, .width/height
setters, .append
(and
friends) improvements;
- add “longTap” event;
.anim()
accepts CSS transform properties;
return false
in event handlers cancels browser event behavior.
0.6
— 14 May 2011
— diff
- add
.add
, .appendTo
, .prependTo
, .replaceWith
, .empty
, .submit
;
- allow function args for
.add/.remove/.toggleClass
;
- improvements to events and xhr.
0.5
— 01 Mar 2011
— diff
- add
.not
, .children
, .siblings
, $.param
;
- improve
.attr
& .html
;
- support callback for
.anim
.
0.4
— 21 Jan 2011
— diff
- JSONP;
- better
.find
, .each
, .closest
;
- add
.eq
, .size
, .parent
, .parents
, .removeAttr
, .val
;
- support function args in
.html
, .attr
;
- adjacency methods now take Zepto objects.
0.3
— 17 Dec 2010
— diff
- add
.toggleClass
, .attr
setter, .last
, .undelegate
, .die
;
- proxied event objects for event delegation;
- support
$
fragments.
0.2
— 01 Dec 2010
— diff
- now compatible with backbone.js;
- support event unbind;
- ajax posts with data.
0.1
— 26 Oct 2010
First. Release. Ever.
Acknowledgements & Thanks
A big Thank-You goes out to all of our
awesome ../../../../zepto.js contributors.
May you all forever bask in glory.
The Zepto API is based on jQuery's Core API, which
is released under the MIT license.
This documentation is based on the layout of the
Backbone.js
documentation, which is released under the
MIT license.
© 2010-2013 Thomas Fuchs, Freckle Online Time Tracking
Zepto and this documentation is released under the terms of the MIT license.