Zepto is a minimalist JavaScript library for modern browsers with a largely jQuery-compatible API. If you use jQuery, you already know how to use Zepto.

While 100% jQuery coverage is not a design goal, the APIs provided match their jQuery counterparts. The goal is to have a ~5-10k modular library that downloads and executes fast, with a familiar and versatile API, so you can concentrate on getting stuff done.

Zepto is open source software and is released under the developer and business-friendly MIT license.

Other download alternatives:

The default build includes the following modules: Core, Ajax, Event, Form, IE.

Zepto will only set the $ global to itself if it is not yet defined. There is no Zepto.noConflict method.

Check if any elements in the collection have the specified class.

Get the height of the first element in the collection; or set the height of all elements in the collection.

Hide elements in this collection by setting their display CSS property to none.

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.

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.

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.

Insert elements from the current collection after the target element in the DOM. This is like after, but with reversed operands.

Emphasis mine.

Insert elements from the current collection before each of the target elements in the DOM. This is like before, but with reversed operands.

See the following table:

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.

Get the last element of the current 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 the next sibling–optionally filtered by selector–of each element in the 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.

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.

Find the first ancestor element that is positioned, meaning its CSS position value is “relative”, “absolute” or “fixed”.

Get immediate parents of each element in the collection. If CSS selector is given, filter results to include only ones matching the selector.

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.

Get values from a named property of each element in the collection, with null and undefined values filtered out.

This is a Zepto-provided method that is not part of the jQuery API.

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.

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.

Prepend elements of the current collection inside each of the target elements. This is like prepend, only with reversed operands.

Get the previous sibling–optionally filtered by selector–of each element in the collection.

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.

Short and lowercase names such as for, class, readonly and similar will be mapped to actual properties such as htmlFor, className, readOnly, etc.

Add elements to the end of the current collection.

This is a Zepto-provided method that is not part of the jQuery API.

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.

Identical to Array.reduce that iterates over current collection.

This is a Zepto-provided method that is not part of the jQuery API.

Remove elements in the current collection from their parent nodes, effectively detaching them from the DOM.

Remove the specified attribute from all elements in the collection. Multiple attributes to remove can be passed as a space-separated list.

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.

Remove a property from each of the DOM nodes in the collection. This is done with JavaScript’s delete operator. Note that trying to remove some built-in DOM properties such as className or maxLength won’t have any affect, since browsers disallow removing those properties.

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.

Gets or sets how many pixels were scrolled to the right so far on window or scrollable element on the page.

Gets or sets how many pixels were scrolled down so far on window or scrollable element on the page.

Restore the default value for the “display” property of each element in the array, effectively showing them if they were hidden with hide.

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.

Get the number of elements in this collection.

Extract the subset of this array, starting at start index. If end is specified, extract up to but not including end index.

Get or set the text content of elements in the collection. When no content is given, returns the text contents of all the elements in the collection, if no element exists, null will be returned. 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 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.

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.

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.

Content

Get or set the value of form controls. When no value is given, return the value of the first element. For , an array of values is returend. When a value is given, set all elements to this value.

Get the width of the first element in the collection; or set the width of all elements in the collection.

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 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 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.

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.

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.

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.

If additional arguments are passed beyond the 2nd argument, they are applied to every invocation of the wrapped function in front of its actual arguments.

Deprecated, use on instead.

Attach an event handler to elements.

Deprecated, use on instead.

Attach an event handler that is only triggered when the event originated from a node that matches a selector.

Deprecated, use off instead.

Detach event handler added by live.

Returns true if preventDefault() was called for this event instance. This serves as a cross-platform alternative to the native defaultPrevented property which is missing or unreliable in some browsers.

Returns true if stopImmediatePropagation() was called for this event instance. Zepto implements the native method in browsers that don’t support it (e.g. old versions of Android).

Returns true if stopPropagation() was called for this event instance.

Deprecated, use on instead.

Like delegate where the selector is taken from the current collection.

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 will detach all handlers of that type. When called without arguments, it detaches all event handlers registered on current elements.

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.

If the data argument is given, this value will be made available as the event.data property during the execution of the event handler.

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() and stopPropagation() is called for the current event, preventing the default browser action such as following links.

If false is passed as argument to this method in place of the callback function, it’s equivalent to passing a function that returns false.

Adds an event handler that removes itself the first time it runs, ensuring that the handler only fires once. See .on() for the explanation of selector and data arguments.

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 an args array is given, it is passed as additional arguments to event handlers.

Zepto only supports triggering events on DOM elements.

Like trigger, but triggers only event handlers on current elements and doesn’t bubble.

Deprecated, use off instead.

Detach event handler added with bind.

Deprecated, use off instead.

Detach event handler added with delegate.

Perform an Ajax request. It can be to a local resource, or cross-domain via HTTP access control support in browsers or JSONP.

Options:

If the URL contains =? or dataType is “jsonp”, the request is performed by injecting a tag instead of using XMLHttpRequest (see JSONP). This has the limitation of contentType, dataType, headers, and async not being supported.

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 and allows changing the settings. 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

If the optional modules “callbacks” and “deferred” are loaded, the XHR object returned from $.ajax() calls implements a promise interface for adding callbacks by chaining:

These methods supersede the success, error, and complete callback options.

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 (xhr, options): before sending the request; can be cancelled

ajaxSend (xhr, options): like ajaxBeforeSend, but not cancellable

ajaxSuccess (xhr, options, data): when the response is success

ajaxError (xhr, options, error): when there was an error

ajaxComplete (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.

Deprecated, use $.ajax instead.

Perform a JSONP request to fetch data from another domain.

This method has no advantages over $.ajax and should not be used.

Object containing the default settings for Ajax requests. Most settings are described in $.ajax. The ones that are useful when set globally are:

Perform an Ajax GET request. This is a shortcut for the $.ajax method.

Get JSON data via Ajax GET request. This is a shortcut for the $.ajax method.

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.

If any of the individual value objects is a function instead of a string, the function will get invoked and its return value will be what gets serialized.

This method accepts an array in serializeArray format, where each item has “name” and “value” properties.

Perform an Ajax POST request. This is a shortcut for the $.ajax method.

data can also be a string:

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:

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 form values to an URL-encoded string for use in Ajax post requests.

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.

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.

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:

Change existing values or add new properties to affect animations that use a string for setting duration.

Smoothly transition CSS properties of elements in the current collection.

Zepto also supports the following CSS transform properties:

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.

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.

The “touch” module adds the following events, which can be used with on and off:

All these events are also available via shortcut methods on any Zepto collection.

See the change log on Github.

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-2018 Thomas Fuchs, Freckle Online Time Tracking Zepto and this documentation is released under the terms of the MIT license.