Ajax – jQuery API

jQuery: Write Less, Do More.
  • jQuery
  • Plugins
  • UI
  • Blog
  • About
  • Donate
  • Download
  • Documentation
  • Tutorials
  • Bug Tracker
  • Discussion

jQuery API

Skip to content
  • api

Ajax

The jQuery library has a full suite of AJAX capabilities. The functions and methods therein allow us to load data from the server without a browser page refresh.

  • jQuery.ajax()

    Low-Level Interface

    Perform an asynchronous HTTP (Ajax) request.

  • .ajaxComplete()

    Global Ajax Event Handlers

    Register a handler to be called when Ajax requests complete. This is an Ajax Event.

  • .ajaxError()

    Global Ajax Event Handlers

    Register a handler to be called when Ajax requests complete with an error. This is an Ajax Event.

  • .ajaxSend()

    Global Ajax Event Handlers

    Show a message before an Ajax request is sent.

  • jQuery.ajaxSetup()

    Low-Level Interface

    Set default values for future Ajax requests.

  • .ajaxStart()

    Global Ajax Event Handlers

    Register a handler to be called when the first Ajax request begins. This is an Ajax Event.

  • .ajaxStop()

    Global Ajax Event Handlers

    Hide a loading message after all the Ajax requests have stopped.

  • .ajaxSuccess()

    Global Ajax Event Handlers

    Show a message when an Ajax request completes successfully.

  • jQuery.get()

    Shorthand Methods

    Load data from the server using a HTTP GET request.

  • jQuery.getJSON()

    Shorthand Methods

    Load JSON-encoded data from the server using a GET HTTP request.

  • jQuery.getScript()

    Shorthand Methods

    Load a JavaScript file from the server using a GET HTTP request, then execute it.

  • .load()

    Shorthand Methods

    Load data from the server and place the returned HTML into the matched element.

  • jQuery.param()

    Collection Manipulation, Forms, Helper Functions

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • jQuery.post()

    Shorthand Methods

    Load data from the server using a HTTP POST request.

  • .serialize()

    Forms, Helper Functions

    Encode a set of form elements as a string for submission.

  • .serializeArray()

    Forms, Helper Functions

    Encode a set of form elements as an array of names and values.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0
      • Version 1.0.4
      • Version 1.1
      • Version 1.1.2
      • Version 1.1.3
      • Version 1.1.4
      • Version 1.2
      • Version 1.2.3
      • Version 1.2.6
      • Version 1.3
      • Version 1.4

© 2010 John Resig and the jQuery Team.

Hosting provided by Media Temple

  • Download
  • Documentation
  • Tutorials
  • Bug Tracker
  • Discussion


Global Ajax Event Handlers – jQuery API

  • UI
  • Blog
  • About
  • Donate
  • Download
  • Documentation
  • Tutorials
  • Bug Tracker
  • Discussion

jQuery API

Skip to content
  • api

Global Ajax Event Handlers

These methods register handlers to be called when certain events, such as initialization or completion, take place for any AJAX request on the page.

  • .ajaxComplete()

    Register a handler to be called when Ajax requests complete. This is an Ajax Event.

  • .ajaxError()

    Register a handler to be called when Ajax requests complete with an error. This is an Ajax Event.

  • .ajaxSend()

    Show a message before an Ajax request is sent.

  • .ajaxStart()

    Register a handler to be called when the first Ajax request begins. This is an Ajax Event.

  • .ajaxStop()

    Hide a loading message after all the Ajax requests have stopped.

  • .ajaxSuccess()

    Show a message when an Ajax request completes successfully.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0
      • Version 1.0.4
      • Version 1.1
      • Version 1.1.2
      • Version 1.1.3
      • Version 1.1.4
      • Version 1.2
      • Version 1.2.3
      • Version 1.2.6
      • Version 1.3
      • Version 1.4

© 2010 John Resig and the jQuery Team.

Hosting provided by Media Temple


.ajaxComplete() – jQuery API

  • Donate
  • Download
  • Documentation
  • Tutorials
  • Bug Tracker
  • Discussion

jQuery API

Skip to content
  • api

.ajaxComplete()

Categories: Ajax > Global Ajax Event Handlers

.ajaxComplete( handler(event, XMLHttpRequest, ajaxOptions) ) Returns: jQuery

Description: Register a handler to be called when Ajax requests complete. This is an Ajax Event.

  • version added: 1.0.ajaxComplete( handler(event, XMLHttpRequest, ajaxOptions) )

    handler(event, XMLHttpRequest, ajaxOptions)The function to be invoked.

Whenever an Ajax request completes, jQuery triggers the ajaxComplete event. Any and all handlers that have been registered with the .ajaxComplete() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxComplete(function() {
  $(this).text('Triggered ajaxComplete handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});

When the user clicks the button and the Ajax request completes, the log message is displayed.

Note: Because .ajaxComplete() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxComplete handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an ajaxComplete handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxComplete(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxComplete handler.');
  }
});

Example:

Show a message when an Ajax request completes.

$("#msg").ajaxComplete(function(event,request, settings){
   $(this).append("<li>Request Complete.</li>");
 });

Comments

  • Please keep comments relevant to .ajaxComplete().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0
      • Version 1.0.4
      • Version 1.1
      • Version 1.1.2
      • Version 1.1.3
      • Version 1.1.4
      • Version 1.2
      • Version 1.2.3
      • Version 1.2.6
      • Version 1.3


.ajaxError() – jQuery API

  • Tutorials
  • Bug Tracker
  • Discussion

jQuery API

Skip to content
  • api

.ajaxError()

Categories: Ajax > Global Ajax Event Handlers

.ajaxError( handler(event, XMLHttpRequest, ajaxOptions, thrownError) ) Returns: jQuery

Description: Register a handler to be called when Ajax requests complete with an error. This is an Ajax Event.

  • version added: 1.0.ajaxError( handler(event, XMLHttpRequest, ajaxOptions, thrownError) )

    handler(event, XMLHttpRequest, ajaxOptions, thrownError)The function to be invoked.

Whenever an Ajax request completes with an error, jQuery triggers the ajaxError event. Any and all handlers that have been registered with the .ajaxError() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxError(function() {
  $(this).text('Triggered ajaxError handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/missing.html');
});

When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.

Note: Because .ajaxError() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxError handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an ajaxError handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxError(function(e, xhr, settings, exception) {
  if (settings.url == 'ajax/missing.html') {
    $(this).text('Triggered ajaxError handler.');
  }
});

Example:

Show a message when an Ajax request fails.

$("#msg").ajaxError(function(event, request, settings){
   $(this).append("<li>Error requesting page " + settings.url + "</li>");
 });

Comments

  • Please keep comments relevant to .ajaxError().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Artiom
    for some reason this stopped working in jQuery 1.4 =/

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0
      • Version 1.0.4
      • Version 1.1
      • Version 1.1.2
      • Version 1.1.3
      • Version 1.1.4
      • Version 1.2


.ajaxSend() – jQuery API

jQuery API

Skip to content
  • api

.ajaxSend()

Categories: Ajax > Global Ajax Event Handlers

.ajaxSend( handler(event, XMLHttpRequest, ajaxOptions) ) Returns: jQuery

Description:

  • version added: 1.0.ajaxSend( handler(event, XMLHttpRequest, ajaxOptions) )

    handler(event, XMLHttpRequest, ajaxOptions)The function to be invoked.

Whenever an Ajax request is about to be sent, jQuery triggers the ajaxSend event. Any and all handlers that have been registered with the .ajaxSend() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxSend(function() {
  $(this).text('Triggered ajaxSend handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});

When the user clicks the button and the Ajax request is about to begin, the log message is displayed.

Note: Because .ajaxSend() is implemented as a method of jQuery instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxSend handlers are invoked, regardless of what Ajax request is to be sent. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an ajaxSend handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxSend(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSend handler.');
  }
});

Example:

Show a message before an Ajax request is sent.

$("#msg").ajaxSend(function(evt, request, settings){
        $(this).append("<li>Starting request at " + settings.url + "</li>");
      });

Comments

  • Please keep comments relevant to .ajaxSend().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Alex Bosworth
    This doesn't appear to trigger for JSONP reqs (jq1.4.0)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0
      • Version 1.0.4
      • Version 1.1
      • Version 1.1.2


.ajaxStart() – jQuery API

jQuery API

Skip to content
  • api

.ajaxStart()

Categories: Ajax > Global Ajax Event Handlers

.ajaxStart( handler() ) Returns: jQuery

Description: Register a handler to be called when the first Ajax request begins. This is an Ajax Event.

  • version added: 1.0.ajaxStart( handler() )

    handler()The function to be invoked.

Whenever an Ajax request is about to be sent, jQuery checks whether there are any other outstanding Ajax requests. If none are in progress, jQuery triggers the ajaxStart event. Any and all handlers that have been registered with the .ajaxStart() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxStart(function() {
  $(this).text('Triggered ajaxStart handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});

When the user clicks the button and the Ajax request is sent, the log message is displayed.

Note: Because .ajaxStart() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

Example:

Show a loading message whenever an Ajax request starts (and none is already active).

$("#loading").ajaxStart(function(){
   $(this).show();
 });

Comments

  • Please keep comments relevant to .ajaxStart().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities
    • Version
      • Version 1.0


.ajaxStop() – jQuery API

jQuery API

Skip to content
  • api

.ajaxStop()

Categories: Ajax > Global Ajax Event Handlers

.ajaxStop( handler() ) Returns: jQuery

Description:

  • version added: 1.0.ajaxStop( handler() )

    handler()The function to be invoked.

Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the ajaxStop event. Any and all handlers that have been registered with the .ajaxStop() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxStop(function() {
  $(this).text('Triggered ajaxStop handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});

When the user clicks the button and the Ajax request completes, the log message is displayed.

Because .ajaxStop() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

Example:

Hide a loading message after all the Ajax requests have stopped.

$("#loading").ajaxStop(function(){
      $(this).hide();
      });

Comments

  • Please keep comments relevant to .ajaxStop().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.ajaxSuccess() – jQuery API

jQuery API

Skip to content
  • api

.ajaxSuccess()

Categories: Ajax > Global Ajax Event Handlers

.ajaxSuccess( handler(event, XMLHttpRequest, ajaxOptions) ) Returns: jQuery

Description:

  • version added: 1.0.ajaxSuccess( handler(event, XMLHttpRequest, ajaxOptions) )

    handler(event, XMLHttpRequest, ajaxOptions)The function to be invoked.

Whenever an Ajax request completes successfully, jQuery triggers the ajaxSuccess event. Any and all handlers that have been registered with the .ajaxSuccess() method are executed at this time.

To observe this method in action, we can set up a basic Ajax load request:

<div class="trigger">Trigger</div>
<div class="result"></div>
<div class="log"></div>

We can attach our event handler to any element:

$('.log').ajaxSuccess(function() {
  $(this).text('Triggered ajaxSuccess handler.');
});

Now, we can make an Ajax request using any jQuery method:

$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});

When the user clicks the button and the Ajax request completes successfully, the log message is displayed.

Note: Because .ajaxSuccess() is implemented as a method of jQuery object instances, we can use the this keyword as we do here to refer to the selected elements within the callback function.

All ajaxSuccess handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an ajaxSuccess handler is executed, it is passed the event object, the XMLHttpRequest object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:

$('.log').ajaxSuccess(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSuccess handler.');
  }
});

Example:

Show a message when an Ajax request completes successfully.

$("#msg").ajaxSuccess(function(evt, request, settings){
      $(this).append("<li>Successful Request!</li>");
      });

Comments

  • Please keep comments relevant to .ajaxSuccess().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Helper Functions – jQuery API

jQuery API

Skip to content
  • api

Helper Functions

These functions assist with common idioms encountered when performing AJAX tasks.

  • jQuery.param()

    Collection Manipulation, Forms

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • .serialize()

    Forms

    Encode a set of form elements as a string for submission.

  • .serializeArray()

    Forms

    Encode a set of form elements as an array of names and values.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.param() – jQuery API

jQuery API

Skip to content
  • api

jQuery.param()

Categories: Miscellaneous > Collection Manipulation | Forms | Ajax > Helper Functions

jQuery.param( obj ) Returns: String

Description: Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • version added: 1.2jQuery.param( obj )

    objAn array or object to serialize.

  • version added: 1.4jQuery.param( obj, traditional )

    objAn array or object to serialize.

    traditionalA Boolean indicating whether to perform a traditional "shallow" serialization.

This function is used internally to convert form element values into a serialized string representation (See .serialize() for more information).

As of jQuery 1.3, the return value of a function is used instead of the function as a String.

As of jQuery 1.4, the $.param() method serializes deep objects recursively to accommodate modern scripting languages and frameworks such as PHP and Ruby on Rails. You can disable this functionality globally by setting jQuery.ajaxSettings.traditional = true;.

Note: Because some frameworks have limited ability to parse serialized arrays, we should exercise caution when passing an obj argument that contains objects or arrays nested within another array.

In jQuery 1.4 HTML5 input elements are serialized, as well.

We can display a query string representation of an object and a URI-decoded version of the same as follows:

var myObject = {
  a: {
    one: 1,
    two: 2,
    three: 3
  },
  b: [1,2,3]
};
var recursiveEncoded = $.param(myObject);
var recursiveDecoded = decodeURIComponent($.param(myObject));

alert(recursiveEncoded);
alert(recursiveDecoded);

The values of recursiveEncoded and recursiveDecoded are alerted as follows:

a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

To emulate the behavior of $.param() prior to jQuery 1.4, we can set the traditional argument to true:

var myObject = {
  a: {
    one: 1,
    two: 2,
    three: 3
  },
  b: [1,2,3]
};
var shallowEncoded = $.param(myObject, true);
var shallowDecoded = decodeURIComponent(shallowEncoded);

alert(shallowEncoded);
alert(shallowDecoded);

The values of shallowEncoded and shallowDecoded are alerted as follows:

a=%5Bobject+Object%5D&b=1&b=2&b=3
a=[object+Object]&b=1&b=2&b=3

Examples:

Example: Serialize a key/value object.

<!DOCTYPE html>
<html>
<head>
  <style>div { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="results"></div>
<script>

    var params = { width:1680, height:1050 };
    var str = jQuery.param(params);
    $("#results").text(str);
</script>
</body>
</html>

Demo:

Example: Serialize a few complex objects

<!DOCTYPE html>
<html>
<head>
  <style>div { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="results"></div>
<script>
// <=1.3.2:
$.param({ a: [2,3,4] }) // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [2,3,4] }) // "a[]=2&a[]=3&a[]=4"

// <=1.3.2:
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a=[object+Object]&d=3&d=4&d=[object+Object]"
// >=1.4:
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a[b]=1&a[c]=2&d[]=3&d[]=4&d[]=[object+Object]"

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.param().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • "Cowboy" Ben Alman
    For more information on the changes in .param for jQuery 1.4, please see
    jQuery 1.4 $.param demystified

    For a .deparam counterpart to .param, please see
    jQuery BBQ: Back Button & Query Library

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.serialize() – jQuery API

jQuery API

Skip to content
  • api

.serialize()

Categories: Forms | Ajax > Helper Functions

.serialize() Returns: String

Description: Encode a set of form elements as a string for submission.

  • version added: 1.0.serialize()

The .serialize() method creates a text string in standard URL-encoded notation. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:

<form>
  <div><input type="text" name="a" value="1" id="a" /></div>
  <div><input type="text" name="b" value="2" id="b" /></div>
  <div><input type="hidden" name="c" value="3" id="c" /></div>
  <div>
    <textarea name="d" rows="8" cols="40">4</textarea>
  </div>
  <div><select name="e">
    <option value="5" selected="selected">5</option>
    <option value="6">6</option>
    <option value="7">7</option>
  </select></div>
  <div>
    <input type="checkbox" name="f" value="8" id="f" />
  </div>
  <div>
    <input type="submit" name="g" value="Submit" id="g" />
  </div>
</form>

The .serialize() method can act on a jQuery object that has selected individual form elements, such as <input>, <textarea>, and <select>. However, it is typically easier to select the <form> tag itself for serialization:

$('form').submit(function() {
  alert($(this).serialize());
  return false;
});

This produces a standard-looking query string:

a=1&b=2&c=3&d=4&e=5

Example:

Serialize a form to a query string, that could be sent to a server in an Ajax request.

<!DOCTYPE html>
<html>
<head>
  <style>
  body, select { font-size:12px; }
  form { margin:5px; }
  p { color:red; margin:5px; font-size:14px; }
  b { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<form>
    <select name="single">
      <option>Single</option>
      <option>Single2</option>
    </select>

<br />
    <select name="multiple" multiple="multiple">
      <option selected="selected">Multiple</option>
      <option>Multiple2</option>

      <option selected="selected">Multiple3</option>
    </select>
<br/>
    <input type="checkbox" name="check" value="check1" id="ch1"/>

    <label for="ch1">check1</label>

    <input type="checkbox" name="check" value="check2" checked="checked" id="ch2"/>

    <label for="ch2">check2</label>
<br />
    <input type="radio" name="radio" value="radio1" checked="checked" id="r1"/>

    <label for="r1">radio1</label>
    <input type="radio" name="radio" value="radio2" id="r2"/>

    <label for="r2">radio2</label>
  </form>
  <p><tt id="results"></tt></p>
<script>
    function showValues() {
      var str = $("form").serialize();
      $("#results").text(str);
    }
    $(":checkbox, :radio").click(showValues);
    $("select").change(showValues);
    showValues();
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .serialize().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Sanam Maharjan
    Happy Birthday jQuery.
    Ever since I have come across this, it feels like javascript is in my finger tips. "Write less, do more" has has been the motto of my programming ever since.
    Lately I have been trying to use the .serialize() method to post the form elements through ajax. But I could not send the <input type="file"> element value using .serialize(). I googled but in vain as I could not find any reference about it. Now release of jQuery1.4 raised some hope and started looking for .serialize(), but nothing was mentioned about the <input type="file"> here either. Is it that I am not looking at a correct place or it does not support it? Thanks for help in advance.
  • S. Kleineikenscheidt
    How would you expect the contents of the <input type="file"> element be serialized? This method will probably not help you. I have been using the form plugin for uploading files (see http://jquery.malsup.com/form/).

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.serializeArray() – jQuery API

jQuery API

Skip to content
  • api

.serializeArray()

Categories: Forms | Ajax > Helper Functions

.serializeArray() Returns: Array

Description: Encode a set of form elements as an array of names and values.

  • version added: 1.2.serializeArray()

The .serializeArray() method creates a JavaScript array of objects, ready to be encoded as a JSON string. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:

<form>
  <div><input type="text" name="a" value="1" id="a" /></div>
  <div><input type="text" name="b" value="2" id="b" /></div>
  <div><input type="hidden" name="c" value="3" id="c" /></div>
  <div>
    <textarea name="d" rows="8" cols="40">4</textarea>
  </div>
  <div><select name="e">
    <option value="5" selected="selected">5</option>
    <option value="6">6</option>
    <option value="7">7</option>
  </select></div>
  <div>
    <input type="checkbox" name="f" value="8" id="f" />
  </div>
  <div>
    <input type="submit" name="g" value="Submit" id="g" />
  </div>
</form>

The .serializeArray() method can act on a jQuery object that has selected individual form elements, such as <input>, <textarea>, and <select>. However, it is typically easier to select the <form> tag itself for serialization:

$('form').submit(function() {
  $.print($(this).serializeArray());
  return false;
});

This produces the following data structure:

[
  {
    name: a
    value: 1
  },
  {
    name: b
    value: 2
  },
  {
    name: c
    value: 3
  },
  {
    name: d
    value: 4
  },
  {
    name: e
    value: 5
  }
]

Example:

Get the values from a form, iterate through them, and append them to a results display.

<!DOCTYPE html>
<html>
<head>
  <style>
  body, select { font-size:14px; }
  form { margin:5px; }
  p { color:red; margin:5px; }
  b { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><b>Results:</b> <span id="results"></span></p>

  <form>
    <select name="single">
      <option>Single</option>
      <option>Single2</option>

    </select>
    <select name="multiple" multiple="multiple">
      <option selected="selected">Multiple</option>
      <option>Multiple2</option>

      <option selected="selected">Multiple3</option>
    </select><br/>
    <input type="checkbox" name="check" value="check1" id="ch1"/>

    <label for="ch1">check1</label>
    <input type="checkbox" name="check" value="check2" checked="checked" id="ch2"/>

    <label for="ch2">check2</label>
    <input type="radio" name="radio" value="radio1" checked="checked" id="r1"/>

    <label for="r1">radio1</label>
    <input type="radio" name="radio" value="radio2" id="r2"/>

    <label for="r2">radio2</label>
  </form>
<script>

    function showValues() {
      var fields = $(":input").serializeArray();
      $("#results").empty();
      jQuery.each(fields, function(i, field){
        $("#results").append(field.value + " ");
      });
    }

    $(":checkbox, :radio").click(showValues);
    $("select").change(showValues);
    showValues();
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .serializeArray().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Low-Level Interface – jQuery API

jQuery API

Skip to content
  • api

Low-Level Interface

These methods can be used to make arbitrary AJAX requests.

  • jQuery.ajax()

    Perform an asynchronous HTTP (Ajax) request.

  • jQuery.ajaxSetup()

    Set default values for future Ajax requests.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.ajax() – jQuery API

jQuery API

Skip to content
  • api

jQuery.ajax()

Categories: Ajax > Low-Level Interface

jQuery.ajax( settings ) Returns: XMLHttpRequest

Description: Perform an asynchronous HTTP (Ajax) request.

  • version added: 1.0jQuery.ajax( settings )

    settingsA set of key/value pairs that configure the Ajax request. All options are optional. A default can be set for any option with $.ajaxSetup().

    asyncBoolean
    Default: true

    By default, all requests are sent asynchronous (i.e. this is set to true by default). If you need synchronous requests, set this option to false. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active.

    beforeSend(XMLHttpRequest)Function

    A pre-callback to modify the XMLHttpRequest object before it is sent. Use this to set custom headers etc. The XMLHttpRequest is passed as the only argument. This is an Ajax Event. You may return false in function to cancel the request.

    cacheBoolean
    Default: true, false for dataType 'script' and 'jsonp'

    If set to false it will force the pages that you request to not be cached by the browser.

    complete(XMLHttpRequest, textStatus)Function

    A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The XMLHttpRequest object and a string describing the type of success of the request. This is an Ajax Event.

    contentTypeString
    Default: 'application/x-www-form-urlencoded'

    When sending data to the server, use this content-type. Default is "application/x-www-form-urlencoded", which is fine for most cases. If you explicitly pass in a content-type to $.ajax() then it'll always be sent to the server (even if no data is sent).

    contextObject

    This object will be made the context of all Ajax-related callbacks. For example specifying a DOM element as the context will make that the context for the complete callback of a request, like so:

    $.ajax({ url: "test.html", context: document.body, success: function(){
        $(this).addClass("done");
      }});

    dataObject, String

    Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See processData option to prevent this automatic processing. Object must be Key/Value pairs. If value is an Array, jQuery serializes multiple values with same key i.e. {foo:["bar1", "bar2"]} becomes '&foo=bar1&foo=bar2'.

    dataFilter(data, type)Function

    A function to be used to handle the raw responsed data of XMLHttpRequest.This is a pre-filtering function to sanitize the response.You should return the sanitized data.The function gets passed two arguments: The raw data returned from the server, and the 'dataType' parameter.

    dataTypeString
    Default: Intelligent Guess (xml, json, script, or html)

    The type of data that you're expecting back from the server. If none is specified, jQuery will intelligently try to get the results, based on the MIME type of the response (an XML MIME type will yield XML, in 1.4 JSON will yield a JavaScript object, in 1.4 script will execute the script, and anything else will be returned as a string). The available types (and the result passed as the first argument to your success callback) are:

    • "xml": Returns a XML document that can be processed via jQuery.
    • "html": Returns HTML as plain text; included script tags are evaluated when inserted in the DOM.
    • "script": Evaluates the response as JavaScript and returns it as plain text. Disables caching unless option "cache" is used. Note: This will turn POSTs into GETs for remote-domain requests.
    • "json": Evaluates the response as JSON and returns a JavaScript object. In jQuery 1.4 the JSON parsing is done in a strict manner, any malformed JSON is rejected and a parsererror is thrown.
    • "jsonp": Loads in a JSON block using JSONP. Will add an extra "?callback=?" to the end of your URL to specify the callback.
    • "text": A plain text string.

    error(XMLHttpRequest, textStatus, errorThrown)Function

    A function to be called if the request fails. The function is passed three arguments: The XMLHttpRequest object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are "timeout", "error", "notmodified" and "parsererror". This is an Ajax Event.

    globalBoolean
    Default: true

    Whether to trigger global Ajax event handlers for this request. The default is true. Set to false to prevent the global handlers like ajaxStart or ajaxStop from being triggered. This can be used to control various Ajax Events.

    ifModifiedBoolean
    Default: false

    Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header. Default value is false, ignoring the header. In jQuery 1.4 this technique also checks the 'etag' specified by the server to catch unmodified data.

    jsonpString

    Override the callback function name in a jsonp request. This value will be used instead of 'callback' in the 'callback=?' part of the query string in the url for a GET or the data for a POST. So {jsonp:'onJsonPLoad'} would result in 'onJsonPLoad=?' passed to the server.

    jsonpCallbackFunction

    Specify the callback function name for a jsonp request. This value will be used instead of the random name automatically generated by jQuery. It is preferable to let jQuery generate a unique name as it'll make it easier to manage the requests and provide callbacks and error handling. You may want to specify the callback when you want to enable better browser caching of GET requests.

    passwordString

    A password to be used in response to an HTTP access authentication request.

    processDataBoolean
    Default: true

    By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.

    scriptCharsetString

    Only for requests with "jsonp" or "script" dataType and "GET" type. Forces the request to be interpreted as a certain charset. Only needed for charset differences between the remote and local content.

    success(data, textStatus, XMLHttpRequest)Function

    A function to be called if the request succeeds. The function gets passed three arguments: The data returned from the server, formatted according to the 'dataType' parameter; and a string describing the status; and the XMLHttpRequest object. This is an Ajax Event.

    timeoutNumber

    Set a local timeout (in milliseconds) for the request. This will override the global timeout, if one is set via $.ajaxSetup. For example, you could use this property to give a single request a longer timeout than all other requests that you've set to time out in one second. See $.ajaxSetup() for global timeouts.

    traditionalBoolean

    Set this to true if you wish to use the traditional style of param serialization.

    typeString
    Default: 'GET'

    The type of request to make ("POST" or "GET"), default is "GET". Note: Other HTTP request methods, such as PUT and DELETE, can also be used here, but they are not supported by all browsers.

    urlString
    Default: The current page

    A string containing the URL to which the request is sent.

    usernameString

    A username to be used in response to an HTTP access authentication request.

    xhrFunction

    Callback for creating the XMLHttpRequest object. Defaults to the ActiveXObject when available (IE), the XMLHttpRequest otherwise. Override to provide your own implementation for XMLHttpRequest or enhancements to the factory.

The $.ajax() function underlies all Ajax requests sent by jQuery. It is often unnecessary to directly call this function, as several higher-level alternatives like $.get() and .load() are available and are easier to use. If less common options are required, though, $.ajax() can be used more flexibly.

At its simplest, the $.ajax() function can be called with no arguments:

$.ajax();

Note: Default settings can be set globally by using the $.ajaxSetup() function.

This example, using no options, loads the contents of the current page, but does nothing with the result. To use the result, we can implement one of the callback functions.

Callback Functions

The beforeSend, error, dataFilter, success and complete options all take callback functions that are invoked at the appropriate times:

  1. beforeSend is called before the request is sent, and is passed the XMLHttpRequest object as a parameter.
  2. error is called if the request fails. It is passed the XMLHttpRequest object, a string indicating the error type, and an exception object if applicable.
  3. dataFilter is called on success. It is passed the returned data and the value of dataType, and must return the (possibly altered) data to pass on to success.
  4. success is called if the request succeeds. It is passed the returned data, as well as a string containing the success code.
  5. complete is called when the request finishes, whether in failure or success. It is passed the XMLHttpRequest object, as well as a string containing the success or error code.

To make use of the returned HTML, we can implement a success handler:

$.ajax({
  url: 'ajax/test.html',
  success: function(data) {
    $('.result').html(data);
    alert('Load was performed.');
  }
});

Such a simple example would generally be better served by using .load() or $.get().

Data Types

The $.ajax() function relies on the server to provide information about the retrieved data. If the server reports the return data as XML, the result can be traversed using normal XML methods or jQuery's selectors. If another type is detected, such as HTML in the example above, the data is treated as text.

Different data handling can be achieved by using the dataType option. Besides plain xml, the dataType can be html, json, jsonp, script, or text.

The text and xml types return the data with no processing. The data is simply passed on to the success handler, either through the responseText or responseHTML property of the XMLHttpRequest object, respectively.

Note: We must ensure that the MIME type reported by the web server matches our choice of dataType. In particular, XML must be declared by the server as text/xml or application/xml for consistent results.

If html is specified, any embedded JavaScript inside the retrieved data is executed before the HTML is returned as a string. Similarly, script will execute the JavaScript that is pulled back from the server, then return the script itself as textual data.

The json type parses the fetched data file as a JavaScript object and returns the constructed object as the result data. To do so, it uses JSON.parse() when the browser supports it; otherwise it uses a Function constructor. JSON data is convenient for communicating structured data in a way that is concise and easy for JavaScript to parse. If the fetched data file exists on a remote server, the jsonp type can be used instead. This type will cause a query string parameter of callback=? to be appended to the URL; the server should prepend the JSON data with the callback name to form a valid JSONP response. If a specific parameter name is desired instead of callback, it can be specified with the jsonp option to $.ajax().

Note: JSONP is an extension of the JSON format, requiring some server-side code to detect and handle the query string parameter. More information about it can be found in the original post detailing its use.

When data is retrieved from remote servers (which is only possible using the script or jsonp data types), the operation is performed using a <script> tag rather than an XMLHttpRequest object. In this case, no XMLHttpRequest object is returned from $.ajax(), nor is one passed to the handler functions such as beforeSend.

Sending Data to the Server

By default, Ajax requests are sent using the GET HTTP method. If the POST method is required, the method can be specified by setting a value for the type option. This option affects how the contents of the data option are sent to the server.

The data option can contain either a query string of the form key1=value1&key2=value2, or a map of the form {key1: 'value1', key2: 'value2'}. If the latter form is used, the data is converted into a query string before it is sent. This processing can be circumvented by setting processData to false. The processing might be undesirable if we wish to send an XML object to the server; in this case, we would also want to change the contentType option from application/x-www-form-urlencoded to a more appropriate MIME type.

Advanced Options

The global option prevents handlers registered using .ajaxSend(), .ajaxError(), and similar methods from firing when this request would trigger them. This can be useful to, for example, suppress a loading indicator that was implemented with .ajaxSend() if the requests are frequent and brief. See the descriptions of these methods below for more details.

If the server performs HTTP authentication before providing a response, the user name and password pair can be sent via the username and password options.

Ajax requests are time-limited, so errors can be caught and handled to provide a better user experience. Request timeouts are usually either left at their default or set as a global default using $.ajaxSetup() rather than being overridden for specific requests with the timeout option.

By default, requests are always issued, but the browser may serve results out of its cache. To disallow use of the cached results, set cache to false. To cause the request to report failure if the asset has not been modified since the last request, set ifModified to true.

The scriptCharset allows the character set to be explicitly specified for requests that use a <script> tag (that is, a type of script or jsonp). This is useful if the script and host page have differing character sets.

The first letter in Ajax stands for "asynchronous," meaning that the operation occurs in parallel and the order of completion is not guaranteed. The async option to $.ajax() defaults to true, indicating that code execution can continue after the request is made. Setting this option to false (and thus making the call no longer asynchronous) is strongly discouraged, as it can cause the browser to become unresponsive.

The $.ajax() function returns the XMLHttpRequest object that it creates. Normally jQuery handles the creation of this object internally, but a custom function for manufacturing one can be specified using the xhr option. The returned object can generally be discarded, but does provide a lower-level interface for observing and manipulating the request. In particular, calling .abort() on the object will halt the request before it completes.

Examples:

Example: Load and execute a JavaScript file.

$.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });

Example: Save some data to the server and notify the user once it's complete.

$.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

Example: Retrieve the latest version of an HTML page.

$.ajax({
  url: "test.html",
  cache: false,
  success: function(html){
    $("#results").append(html);
  }
});

Example: Loads data synchronously. Blocks the browser while the requests is active. It is better to block user interaction by other means when synchronization is necessary.

var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

Example: Sends an xml document as data to the server. By setting the processData option to false, the automatic conversion of data to strings is prevented.

var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });

Example: Sends an id as data to the server, save some data to the server and notify the user once it's complete.

bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      success: function(msg){
         alert(msg);
      }
   }
).responseText;

Comments

  • Please keep comments relevant to jQuery.ajax().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • jrs_66
    Is there any additional documentation available for ETag support with .ajax?
  • Yay
    You need to update the two descriptions of the success callback in order to include the new third parameter (the XHR object).
  • TweetKishore
    I dont see support for passing HTTP Headers to the Server. Is this not supported?
  • gabel
    Any chance jQuery will implement cross domain ajax via YQL native as an option?

    jQuery plugin for that purpose...
    http://james.padolsey.com/javascript/cross-doma...
  • kapouer
    is redirection supported ?
  • kapouer
    sure, the question is : do a request answered back by server with a "Location" header set is handled by jquery's ajax module ?
  • gabel
    I think redirection is the duty of the server side connector not the Javascript.
    e.g. http://framework.zend.com/manual/en/zend.http.h...

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.ajaxSetup() – jQuery API

jQuery API

Skip to content
  • api

jQuery.ajaxSetup()

Categories: Ajax > Low-Level Interface

jQuery.ajaxSetup( options )

Description: Set default values for future Ajax requests.

  • version added: 1.1jQuery.ajaxSetup( options )

    optionsA set of key/value pairs that configure the default Ajax request. All options are optional.

For details on the settings available for $.ajaxSetup(), see $.ajax().

All subsequent Ajax calls using any function will use the new settings, unless overridden by the individual calls, until the next invocation of $.ajaxSetup().

For example, we could set a default for the URL parameter before pinging the server repeatedly:

$.ajaxSetup({
  url: 'ping.php',
});

Now each time an Ajax request is made, this URL will be used automatically:

$.ajax({});
$.ajax({
  data: {'date': Date()},
});

Note: Global callback functions should be set with their respective global Ajax event handler methods-.ajaxStart(), .ajaxStop(), .ajaxComplete(), .ajaxError(), .ajaxSuccess(), .ajaxSend()-rather than within the settings object for $.ajaxSetup().

Example:

Sets the defaults for Ajax requests to the url "/xmlhttp/", disables global handlers and uses POST instead of GET. The following Ajax requests then sends some data without having to set anything else.

$.ajaxSetup({
   url: "/xmlhttp/",
   global: false,
   type: "POST"

 });
 $.ajax({ data: myData });

Comments

  • Please keep comments relevant to jQuery.ajaxSetup().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Yukulélé
    what is "/xmlhttp/" in exemple ?
    an URL ?
  • taktu
    this one is really usefull, good job!
  • Struan Judd
    This function appears twice when the "Ajax" heading is selected
  • shernshiou
    I love this .ajaxSetup it not only save the time of my coding, also keep the js smaller. Thanks

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Shorthand Methods – jQuery API

jQuery API

Skip to content
  • api

Shorthand Methods

These methods perform the more common types of AJAX requests in less code.

  • jQuery.get()

    Load data from the server using a HTTP GET request.

  • jQuery.getJSON()

    Load JSON-encoded data from the server using a GET HTTP request.

  • jQuery.getScript()

    Load a JavaScript file from the server using a GET HTTP request, then execute it.

  • .load()

    Load data from the server and place the returned HTML into the matched element.

  • jQuery.post()

    Load data from the server using a HTTP POST request.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.get() – jQuery API

jQuery API

Skip to content
  • api

jQuery.get()

Categories: Ajax > Shorthand Methods

jQuery.get( url, [ data ], [ callback(data, textStatus, XMLHttpRequest) ], [ dataType ] ) Returns: XMLHttpRequest

Description: Load data from the server using a HTTP GET request.

  • version added: 1.0jQuery.get( url, [ data ], [ callback(data, textStatus, XMLHttpRequest) ], [ dataType ] )

    urlA string containing the URL to which the request is sent.

    dataA map or string that is sent to the server with the request.

    callback(data, textStatus, XMLHttpRequest)A callback function that is executed if the request succeeds.

    dataTypeThe type of data expected from the server.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  data: data,
  success: success
  dataType: dataType
});

The callback is passed the returned data, which will be an XML root element, text string, JavaScript file, or JSON object, depending on the MIME type of the response.

Most implementations will specify a success handler:

$.get('ajax/test.html', function(data) {
  $('.result').html(data);
  alert('Load was performed.');
});

This example fetches the requested HTML snippet and inserts it on the page.

Examples:

Example: Request the test.php page, but ignore the return results.

$.get("test.php");

Example: Request the test.php page and send some additional data along (while still ignoring the return results).

$.get("test.php", { name: "John", time: "2pm" } );

Example: pass arrays of data to the server (while still ignoring the return results).

$.get("test.php", { 'choices[]': ["Jon", "Susan"]} );

Example: Alert out the results from requesting test.php (HTML or XML, depending on what was returned).

$.get("test.php", function(data){
   alert("Data Loaded: " + data);
 });

Example: Alert out the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).

$.get("test.cgi", { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   });

Comments

  • Please keep comments relevant to jQuery.get().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Seth
    How does this work with cross domain URL's? Is there any issue with trying to pull information from another URL via the .get method?
  • Eli
    If I'm doing something like this:

    function example () {
    var value = '';

    $.get('url', function (data) {
    process data;
    value = data.something;
    });

    return value;
    }

    the returned value of the example function is '', because it was returned /before/ the new value was set using the $.get function.

    how can I avoid it? I want the value to be returned only after the $.get function has finished it's thing.

    Thanks.
  • Hyponiq
    Expanding on carlo:
    Essentially, you would use an anonymous function to get the result of the request. Example:
    var value = (function () {
        var val = null;

        $.ajax({
            'async': false,
            'global': false,
            'url': 'path/to/url.php',
            'success': function (data) {
                val = data;
            }
        });

        return val;
    })();

    While this solution would suffice, there are a multitude of different ways to go about it. This is the simplest way (that I have found).
  • carlo
    you must set async option

    async Boolean
    Default: true

    By default, all requests are sent asynchronous (i.e. this is set to true by default). If you need synchronous requests, set this option to false. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active.

    see: http://api.jquery.com/jQuery.ajax/
  • nickretallack
    What happens if the server can't be reached or it returns an error code?
  • Karl Swedberg
    If you make the request with $.get() and it returns an error code, it fails silently unless you call the global .ajaxError() method. So, either use .ajaxError() in conjunction with $.get() or use $.ajax() with an error callback.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.getJSON() – jQuery API

jQuery API

Skip to content
  • api

jQuery.getJSON()

Categories: Ajax > Shorthand Methods

jQuery.getJSON( url, [ data ], [ callback(data, textStatus) ] ) Returns: XMLHttpRequest

Description: Load JSON-encoded data from the server using a GET HTTP request.

  • version added: 1.0jQuery.getJSON( url, [ data ], [ callback(data, textStatus) ] )

    urlA string containing the URL to which the request is sent.

    dataA map or string that is sent to the server with the request.

    callback(data, textStatus)A callback function that is executed if the request succeeds.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  dataType: 'json',
  data: data,
  success: success
});

The callback is passed the returned data, which will be a JavaScript object or array as defined by the JSON structure and parsed using the eval() function.

Note: For details on the JSON format, see http://json.org/.

Most implementations will specify a success handler:

$.getJSON('ajax/test.json', function(data) {
  $('.result').html('<p>' + data.foo + '</p>'
    + '<p>' + data.baz[1] + '</p>');
});

This example, of course, relies on the structure of the JSON file:

{
  "foo": "The quick brown fox jumps over the lazy dog.",
  "bar": "ABCDEFG",
  "baz": [52, 97]
}

Using this structure, the example inserts the first string and second number from the file onto the page.

If there is a syntax error in the JSON file, the request will usually fail silently. Avoid frequent hand-editing of JSON data for this reason.

If the specified URL is on a remote server, the request is treated as JSONP instead. See the discussion of the jsonp data type in $.ajax() for more details.

Examples:

Example: Loads the four most recent cat pictures from the Flickr JSONP API.

<!DOCTYPE html>
<html>
<head>
  <style>img{ height: 100px; float: left; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="images">

</div>
<script>$.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?tags=cat&tagmode=any&format=json&jsoncallback=?",
        function(data){
          $.each(data.items, function(i,item){
            $("<img/>").attr("src", item.media.m).appendTo("#images");
            if ( i == 3 ) return false;
          });
        });</script>
</body>
</html>

Demo:

Example: Load the JSON data from test.js and access a name from the returned JSON data.

$.getJSON("test.js", function(json){
   alert("JSON Data: " + json.users[3].name);
 });

Example: Load the JSON data from test.js, passing along additional data, and access a name from the returned JSON data.

$.getJSON("test.js", { name: "John", time: "2pm" }, function(json){
    alert("JSON Data: " + json.users[3].name);
    });

Example: List the result of a consultation of pages.php in HTML as an array. By Manuel Gonzalez.

var id=$("#id").attr("value");
$.getJSON("pages.php",{id:id},dates);

function dates(datos) {

  $("#list").html("Name:"+datos[1].name+"<br>"+"Last Name:"+datos[1].lastname+"<br>"+"Address:"+datos[1].address);
}

Comments

  • Please keep comments relevant to jQuery.getJSON().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Christian Fleschhut
    Hi guys, what’s this “$.print” method (4th line, 2nd code example block) supposed to be?

    Is it just me or is this an error??? *confused*
  • Karl Swedberg
    Sorry about that. I just removed it. In the print version of the documentation, we show a simple $.print plugin to dump results into a div on the page, and we use that throughout the book for examples. We removed references to that plugin for the online version, but apparently we missed this one.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.getScript() – jQuery API

jQuery API

Skip to content
  • api

jQuery.getScript()

Categories: Ajax > Shorthand Methods

jQuery.getScript( url, [ success(data, textStatus) ] ) Returns: XMLHttpRequest

Description: Load a JavaScript file from the server using a GET HTTP request, then execute it.

  • version added: 1.0jQuery.getScript( url, [ success(data, textStatus) ] )

    urlA string containing the URL to which the request is sent.

    success(data, textStatus)A callback function that is executed if the request succeeds.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  url: url,
  type: 'script',
  success: success
});

The callback is passed the returned JavaScript file. This is generally not useful as the script will already have run at this point.

The script is executed in the global context, so it can refer to other variables and use jQuery functions. Included scripts should have some impact on the current page:

$('.result').html('<p>Lorem ipsum dolor sit amet.</p>');

The script can then be included and run by referencing the file name:

$.getScript('ajax/test.js', function() {
  alert('Load was performed.');
});

Examples:

Example: We load the new official jQuery Color Animation plugin dynamically and bind some color animations to occur once the new functionality is loaded.

<!DOCTYPE html>
<html>
<head>
  <style>.block {
   background-color: blue;
   width: 150px;
   height: 70px;
   margin: 10px;
}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="go">&raquo; Run</button>

<div class="block"></div>

<script>$.getScript("http://dev.jquery.com/view/trunk/plugins/color/jquery.color.js", function(){
  $("#go").click(function(){
    $(".block").animate( { backgroundColor: 'pink' }, 1000)
      .animate( { backgroundColor: 'blue' }, 1000);
  });
});</script>
</body>
</html>

Demo:

Example: Load the test.js JavaScript file and execute it.

$.getScript("test.js");

Example: Load the test.js JavaScript file and execute it, displaying an alert message when the execution is complete.

$.getScript("test.js", function(){
   alert("Script loaded and executed.");
 });

Comments

  • Please keep comments relevant to jQuery.getScript().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Frikki
    Cannot load files that are higher up in the local folder hierarchy. Works fine for absolute paths and relative paths that are at level or lower.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.load() – jQuery API

jQuery API

Skip to content
  • api

.load()

Categories: Ajax > Shorthand Methods

.load( url, [ data ], [ success(responseText, textStatus, XMLHttpRequest) ] ) Returns: jQuery

Description: Load data from the server and place the returned HTML into the matched element.

  • version added: 1.0.load( url, [ data ], [ success(responseText, textStatus, XMLHttpRequest) ] )

    urlA string containing the URL to which the request is sent.

    dataA map or string that is sent to the server with the request.

    success(responseText, textStatus, XMLHttpRequest)A callback function that is executed if the request succeeds.

This method is the simplest way to fetch data from the server. It is roughly equivalent to $.get(url, data, success) except that it is a method rather than global function and it has an implicit callback function. When a successful response is detected, .load() sets the HTML contents of the matched element to the returned data. This means that most uses of the method can be quite simple:

$('.result').load('ajax/test.html');

The provided callback, if any, is executed after this post-processing has been performed:

$('.result').load('ajax/test.html', function() {
  alert('Load was performed.');
});

The POST method is used if data is provided as an object; otherwise, GET is assumed.

Note: The event handling suite also has a method named .load(). Which one is fired depends on the set of arguments passed.

Loading Page Fragments

The .load() method, unlike $.get(), allows only part of a remote document to be fetched. This is achieved with a special syntax for the url parameter. If one or more space characters are included in the string, the portion of the string following the first space is assumed to be a jQuery selector. This selector is used to identify a portion of the remote document to retrieve.

We could modify the example above to fetch only part of the document:

$('.result').load('ajax/test.html #container');

When this method executes, the content of ajax/test.html is loaded, but then jQuery parses this returned document to find the element with an ID of container. The inner content of this element is inserted into the element with a class of result, and the rest of the loaded document is discarded.

Examples:

Example: Load a piece of the documentation sidebar navigation into a custom unordered list.

<!DOCTYPE html>
<html>
<head>
  <style>body{ font-size: 11px; font-family: Arial; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <b>Main Page Header:</b> <span id="header"></span>
<script>$("#header").load("/ h1");</script>
</body>
</html>

Demo:

Example: Load the feeds.html file into the div with the ID of feeds.

$("#feeds").load("feeds.html");

Result:

<div id="feeds"><b>45</b> feeds found.</div>

Example: pass arrays of data to the server.

$("#objectID").load("test.php", { 'choices[]': ["Jon", "Susan"] } );

Example: Same as above, but will POST the additional parameters to the server and a callback that is executed when the server is finished responding.

$("#feeds").load("feeds.php", {limit: 25}, function(){
   alert("The last 25 entries in the feed have been loaded");
 });

Comments

  • Please keep comments relevant to .load().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Stuart
    Be mindful of no cache in header with IE. Or use an inject of random number like
    $("#objectID").load("test.php?n="+random, { 'choices[]': ["Jon", "Susan"] } );
  • veggieguy
    Shouldn't this be documented as a "complete" function rather than a "success" function, since it is called even on an error? A url that returns a 404 still results in this callback function being invoked, with textStatus === "error".
  • guest
    [success(responseText, textStatus, XMLHttpRequest)] an optional param?
  • Karl Swedberg
    Yes. Fixed. Thanks!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.post() – jQuery API

jQuery API

Skip to content
  • api

jQuery.post()

Categories: Ajax > Shorthand Methods

jQuery.post( url, [ data ], [ success(data, textStatus) ], [ dataType ] ) Returns: XMLHttpRequest

Description: Load data from the server using a HTTP POST request.

  • version added: 1.0jQuery.post( url, [ data ], [ success(data, textStatus) ], [ dataType ] )

    urlA string containing the URL to which the request is sent.

    dataA map or string that is sent to the server with the request.

    success(data, textStatus)A callback function that is executed if the request succeeds.

    dataTypeThe type of data expected from the server.

This is a shorthand Ajax function, which is equivalent to:

$.ajax({
  type: 'POST',
  url: url,
  data: data,
  success: success
  dataType: dataType
});

The callback is passed the returned data, which will be an XML root element or a text string depending on the MIME type of the response.

Most implementations will specify a success handler:

$.post('ajax/test.html', function(data) {
  $('.result').html(data);
  $.print('Load was performed.');
});

This example fetches the requested HTML snippet and inserts it on the page.

Pages fetched with POST are never cached, so the cache and ifModified options have no effect on these requests.

Examples:

Example: Request the test.php page, but ignore the return results.

$.post("test.php");

Example: Request the test.php page and send some additional data along (while still ignoring the return results).

$.post("test.php", { name: "John", time: "2pm" } );

Example: pass arrays of data to the server (while still ignoring the return results).

$.post("test.php", { 'choices[]': ["Jon", "Susan"] });

Example: send form data using ajax requests

$.post("test.php", $("#testform").serialize());

Example: Alert out the results from requesting test.php (HTML or XML, depending on what was returned).

$.post("test.php", function(data){
   alert("Data Loaded: " + data);
 });

Example: Alert out the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).

$.post("test.php", { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   });

Example: Gets the test.php page content, store it in a XMLHttpResponse object and applies the process() JavaScript function.

$.post("test.php", { name: "John", time: "2pm" },
   function(data){
     process(data);
   }, "xml");

Example: Gets the test.php page contents which has been returned in json format ()

$.post("test.php", { func: "getNameAndTime" },
   function(data){
     alert(data.name); // John
     console.log(data.time); //  2pm
   }, "json");

Comments

  • Please keep comments relevant to jQuery.post().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attributes – jQuery API

jQuery API

Skip to content
  • api

Attributes

These methods get and set DOM attributes of elements.

  • .addClass()

    CSS, Class Attribute

    Adds the specified class(es) to each of the set of matched elements.

  • .attr()

    General Attributes

    Get the value of an attribute for the first element in the set of matched elements.

  • .hasClass()

    CSS, Class Attribute

    Determine whether any of the matched elements are assigned the given class.

  • .html()

    DOM Insertion

    Get the HTML contents of the first element in the set of matched elements.

  • .removeAttr()

    General Attributes

    Remove an attribute from each element in the set of matched elements.

  • .removeClass()

    CSS, Class Attribute

    Remove one or all classes from each element in the set of matched elements.

  • .text()

    DOM Insertion, Inside, General Attributes

    Get the combined text contents of each element in the set of matched elements, including their descendants.

  • .toggleClass()

    CSS, Class Attribute

    Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

  • .val()

    Forms, General Attributes

    Get the current value of the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.addClass() – jQuery API

jQuery API

Skip to content
  • api

.addClass()

Categories: Attributes | Manipulation > Class Attribute | CSS

.addClass( className ) Returns: jQuery

Description: Adds the specified class(es) to each of the set of matched elements.

  • version added: 1.0.addClass( className )

    classNameOne or more class names to be added to the class attribute of each matched element.

  • version added: 1.4.addClass( function(index, class) )

    function(index, class)A function returning one or more space-separated class names to be added. Receives the index position of the element in the set and the old class value as arguments.

It's important to note that this method does not replace a class. It simply adds the class, appending it to any which may already be assigned to the elements.

More than one class may be added at a time, separated by a space, to the set of matched elements, like so:

$('p').addClass('myClass yourClass');

This method is often used with .removeClass() to switch elements' classes from one to another, like so:

$('p').removeClass('myClass noClass').addClass('yourClass');

Here, the myClass and noClass classes are removed from all paragraphs, while yourClass is added.

As of jQuery 1.4, the .addClass() method allows us to set the class name by passing in a function.

$('ul li:last').addClass(function() {
  return 'item-' + $(this).index();
});

Given an unordered list with five <li> elements, this example adds the class "item-4" to the last <li>.

Examples:

Example: Adds the class 'selected' to the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 8px; font-size:16px; }
  .selected { color:blue; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>and</p>
  <p>Goodbye</p>
<script>$("p:last").addClass("selected");</script>
</body>
</html>

Demo:

Example: Adds the classes 'selected' and 'highlight' to the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 8px; font-size:16px; }
  .selected { color:red; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>and</p>
  <p>Goodbye</p>
<script>$("p:last").addClass("selected highlight");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .addClass().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.attr() – jQuery API

jQuery API

Skip to content
  • api

.attr()

Categories: Attributes | Manipulation > General Attributes
Contents:
  • attr( attributeName )
    • .attr( attributeName )
  • attr( attributeName, value )
    • .attr( attributeName, value )
    • .attr( map )
    • .attr( attributeName, function(index, attr) )

.attr( attributeName ) Returns: String

Description: Get the value of an attribute for the first element in the set of matched elements.

  • version added: 1.0.attr( attributeName )

    attributeNameThe name of the attribute to get.

It's important to note that the .attr() method gets the attribute value for only the first element in the matched set. To get the value for each element individually, we need to rely on a looping construct such as jQuery's .each() method.

Using jQuery's .attr() method to get the value of an element's attribute has two main benefits:

  1. Convenience: It can be called directly on a jQuery object and chained to other jQuery methods.
  2. Cross-browser consistency: Some attributes have inconsistent naming from browser to browser. Furthermore, the values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The .attr() method reduces such inconsistencies.

Example:

Finds the title attribute of the first <em> in the page.

<!DOCTYPE html>
<html>
<head>
  <style>em { color:blue; font-weight;bold; }
  div { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    Once there was a <em title="huge, gigantic">large</em> dinosaur...
  </p>

  The title of the emphasis is:<div></div>
<script>var title = $("em").attr("title");
    $("div").text(title);
</script>
</body>
</html>

Demo:

.attr( attributeName, value ) Returns: jQuery

Description: Set one or more attributes for the set of matched elements.

  • version added: 1.0.attr( attributeName, value )

    attributeNameThe name of the attribute to set.

    valueA value to set for the attribute.

  • version added: 1.0.attr( map )

    mapA map of attribute-value pairs to set.

  • version added: 1.1.attr( attributeName, function(index, attr) )

    attributeNameThe name of the attribute to set.

    function(index, attr)A function returning the value to set. this is the current element. Receives the index position of the element in the set and the old attribute value as arguments.

The .attr() method is a convenient and powerful way to set the value of attributes—especially when setting multiple attributes or using values returned by a function. Let's consider the following image:

<img id="greatphoto" src="brush-seller.jpg" alt="brush seller" />

Setting a simple attribute

We can change the alt attribute by simply passing the name of the attribute and its new value to the .attr() method:

$('#greatphoto').attr('alt', 'Beijing Brush Seller');

We can add an attribute the same way:

$('#greatphoto')
  .attr('title', 'Photo by Kelly Clark');

Setting several attributes at once

To change the alt attribute and add the title attribute at the same time, we can pass both sets of names and values into the method at once using a map (JavaScript object literal). Each key-value pair in the map adds or modifies an attribute:

$('#greatphoto').attr({
  alt: 'Beijing Brush Seller',
  title: 'photo by Kelly Clark'
});

When setting multiple attributes, the quotation marks around attribute names are optional.

Computed attribute values

By using a function to set attributes, we can compute the value based on other properties of the element. For example, we could concatenate a new value with an existing value:

$('#greatphoto').attr('title', function() {
  return this.alt + ' - photo by Kelly Clark'
});

This use of a function to compute attribute values can be particularly useful when we modify the attributes of multiple elements at once.

Examples:

Example: Set some attributes for all <img>s in the page.

<!DOCTYPE html>
<html>
<head>
  <style>
  img { padding:10px; }
  div { color:red; font-size:24px; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <img />
  <img />
  <img />

  <div><B>Attribute of Ajax</B></div>
<script>$("img").attr({
          src: "/images/hat.gif",
          title: "jQuery",
          alt: "jQuery Logo"
        });
    $("div").text($("img").attr("alt"));</script>
</body>
</html>

Demo:

Example: Disables buttons greater than the 1st button.

<!DOCTYPE html>
<html>
<head>
  <style>button { margin:10px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>0th Button</button>
  <button>1st Button</button>
  <button>2nd Button</button>
<script>$("button:gt(1)").attr("disabled","disabled");</script>
</body>
</html>

Demo:

Example: Sets id for divs based on the position in the page.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  span { color:red; }
  b { font-weight:bolder; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>Zero-th <span></span></div>
  <div>First <span></span></div>
  <div>Second <span></span></div>
<script>$("div").attr("id", function (arr) {
          return "div-id" + arr;
        })
        .each(function () {
          $("span", this).html("(ID = '<b>" + this.id + "</b>')");
        });</script>
</body>
</html>

Demo:

Example: Sets src attribute from title attribute on the image.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <img title="hat.gif"/>
<script>$("img").attr("src", function() {
          return "/images/" + this.title;
        });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .attr().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Kroc Camen
    Could you please add a boolean feature for HTML5 attributes, where you don’t need a value.

    E.g. `$(:input).attr ('disabled');`

    I.e. `<input disabled>` instead of `<input disabled="disabled">`

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.hasClass() – jQuery API

jQuery API

Skip to content
  • api

.hasClass()

Categories: Attributes | Manipulation > Class Attribute | CSS

.hasClass( className ) Returns: Boolean

Description: Determine whether any of the matched elements are assigned the given class.

  • version added: 1.2.hasClass( className )

    classNameThe class name to search for.

Elements may have more than one class assigned to them. In HTML, this is represented by separating the class names with a space:

<div id="mydiv" class="foo bar"></div>

The .hasClass() method will return true if the class is assigned to an element, even if other classes also are. For example, given the HTML above, the following will return true:

$('#mydiv').hasClass('foo')

as would:

$('#mydiv').hasClass('bar')

Example:

Looks for the class 'selected' on the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 8px; font-size:16px; }
  .selected { color:red; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p class="selected">Goodbye</p>
  <div id="result1">First paragraph has selected class: </div>

  <div id="result2">Last paragraph has selected class: </div>
  <div id="result3">Some paragraph has selected class: </div>
<script>$("div#result1").append($("p:first").hasClass("selected").toString());
$("div#result2").append($("p:last").hasClass("selected").toString());
$("div#result3").append($("p").hasClass("selected").toString());</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .hasClass().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.html() – jQuery API

jQuery API

Skip to content
  • api

.html()

Categories: Attributes | Manipulation > DOM Insertion
Contents:
  • html()
    • .html()
  • html( htmlString )
    • .html( htmlString )
    • .html( function(index, html) )

.html() Returns: String

Description: Get the HTML contents of the first element in the set of matched elements.

  • version added: 1.0.html()

This method is not available on XML documents.

In an HTML document, we can use .html() to get the contents of any element. If the selector expression matches more than one element, only the first one's HTML content is returned. Consider this code:

$('div.demo-container').html();

In order for the following <div>'s content to be retrieved, it would have to be the first one with class="demo-container" in the document:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
</div>

The result would look like this:

<div class="demo-box">Demonstration Box</div>

Example:

Click a paragraph to convert it from html to text.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { margin:8px; font-size:20px; color:blue;
      cursor:pointer; }
  b { text-decoration:underline; }
  button { cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>

    <b>Click</b> to change the <span id="tag">html</span>
  </p>
  <p>

    to a <span id="text">text</span> node.
  </p>
  <p>
    This <button name="nada">button</button> does nothing.
  </p>
<script>
    $("p").click(function () {
      var htmlStr = $(this).html();
      $(this).text(htmlStr);
    });
</script>
</body>
</html>

Demo:

.html( htmlString ) Returns: jQuery

Description: Set the HTML contents of each element in the set of matched elements.

  • version added: 1.0.html( htmlString )

    htmlStringA string of HTML to set as the content of each matched element.

  • version added: 1.4.html( function(index, html) )

    function(index, html)A function returning the HTML content to set. Receives the index position of the element in the set and the old HTML value as arguments.

The .html() method is not available in XML documents.

When we use .html() to set elements' contents, any contents that were in those elements is completely replaced by the new contents. Consider the following HTML:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
</div>

We can set the HTML contents of <div class="demo-container"> like so:

$('div.demo-container'>
  .html('<p>All new content. <em>You bet!</em></p>');

That line of code will replace everything inside <div class="demo-container">:

<div class="demo-container">
  <p>All new content. <em>You bet!</em></p>
</div>

As of jQuery 1.4, the .html() method allows us to set the HTML content by passing in a function.

$('div.demo-container').html(function() {
  var emph = '<em>' + $('p').length + ' paragraphs!</em>';
  return '<p>All new content for ' + emph + '</p>';
});

Given a document with six paragraphs, this example will set the HTML of <div class="demo-container"> to <p>All new content for <em>6 paragraphs!</em></p>.

Examples:

Example: Add some html to each div.

<!DOCTYPE html>
<html>
<head>
  <style>

  .red { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>Hello</span>
  <div></div>
  <div></div>
  <div></div>
<script>$("div").html("<span class='red'>Hello <b>Again</b></span>");</script>
</body>
</html>

Demo:

Example: Add some html to each div then immediately do further manipulations to the inserted html.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; font-size:18px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div></div>
  <div></div>
<script>

    $("div").html("<b>Wow!</b> Such excitement...");
    $("div b").append(document.createTextNode("!!!"))
              .css("color", "red");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .html().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • mmbee
    Typo:
    $('div.demo-container'>
    .html('

    All new content. You bet!

    ');

    should be:
    $('div.demo-container')
    .html('

    All new content. You bet!

    ');
  • janbaars
    Hello,
    Can someone explain to me how to get the value(text) from div id="two".

    <div id="content" class="content">
    <div id="one" class="test">joop</div>
    <div id="two" class="test">kees</div>
    <div id="tree" class="test">gert</div>
    </div>

    I try ,
    $(this).click(function() {
    alert($(this).html());
    });
    but this is wrong.

    Thanks, Jan
  • NickT
    .text() ?
  • janbaars
    I fixed it,
    Instead of ID should I use the class name.

    <script>
    $(".test").click(function () {
    var test = $(this).text();
    $("#result").text(test);
    });
    </script>
  • janbaars
    Hello Nick,

    For example, i want to receive the name (kees) when i click on the div (with id="two").
    Kees must be inserted in (<span id="result"></span>).
    But this div is a child of (div id="content").
    When i click on the div (div id="content") i get joop kees gert.
    When i click on the div's with id's one,two,tree i also get joop kees gert.
    How to get only the name kees when i click at div (div id="two").?

    <!DOCTYPE html>
    <html>
    <head>
    <script src="jquery-1.4rc1.js"></script>
    </head>
    <body>
    <span id="result"></span>

    <div id="content" class="content">

    <div id="one" class="test">joop</div>
    <div id="two" class="test">kees</div>
    <div id="tree" class="test">gert</div>
    </div>

    <script>
    $("div").click(function () {
    var test = $(this).text();
    $("#result").text(test);
    });
    </script>

    </body>
    </html>

    Thanks,

    jan
  • Alexsandro
    Is this using innerHTML?

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.removeAttr() – jQuery API

jQuery API

Skip to content
  • api

.removeAttr()

Categories: Attributes | Manipulation > General Attributes

.removeAttr( attributeName ) Returns: jQuery

Description: Remove an attribute from each element in the set of matched elements.

  • version added: 1.0.removeAttr( attributeName )

    attributeNameAn attribute to remove.

The .removeAttr() method uses the JavaScript removeAttribute() function, but it has the advantage of being able to be called directly on a jQuery object and it accounts for different attribute naming across browsers.

Example:

Clicking the button enables the input next to it.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Enable</button>
<input type="text" disabled="disabled" value="can't edit this" />
<script>
$("button").click(function () {
  $(this).next().removeAttr("disabled")
  .focus()
  .val("editable now");
});
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .removeAttr().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • carlo
    I think is like removeClass...

    .removeClass( function(index, class) )

    .removeAttr( function(index, class) )
  • smigl
    Is not found this method with the function annotation in jQuery 1.4 :(
  • David Koss
    There is no information about what's new in 1.4 release...
  • Xan
    Maybe because nothing changed?
    (I don't know, it's just a hypothesis)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.removeClass() – jQuery API

jQuery API

Skip to content
  • api

.removeClass()

Categories: Attributes | Manipulation > Class Attribute | CSS

.removeClass( [ className ] ) Returns: jQuery

Description: Remove one or all classes from each element in the set of matched elements.

  • version added: 1.0.removeClass( [ className ] )

    classNameA class name to be removed from the class attribute of each matched element.

  • version added: 1.4.removeClass( function(index, class) )

    function(index, class)A function returning one or more space-separated class names to be removed. Receives the index position of the element in the set and the old class value as arguments.

If a class name is included as a parameter, then only that class will be removed from the set of matched elements. If no class names are specified in the parameter, all classes will be removed.

More than one class may be removed at a time, separated by a space, from the set of matched elements, like so:

$('p').removeClass('myClass yourClass')

This method is often used with .addClass() to switch elements' classes from one to another, like so:

$('p').removeClass('myClass noClass').addClass('yourClass');

Here, the myClass and noClass classes are removed from all paragraphs, while yourClass is added.

To replace all existing classes with another class, we can use .attr('class', 'newClass') instead.

As of jQuery 1.4, the .removeClass() method allows us to indicate the class to be removed by passing in a function.

$('li:last').removeClass(function() {
          return $(this).prev().attr('class');
        });

This example removes the class name of the penultimate <li> from the last <li>.

Examples:

Example: Remove the class 'blue' from the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="blue under">Hello</p>
  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>

  <p class="blue under">Goodbye</p>
<script>$("p:even").removeClass("blue");</script>
</body>
</html>

Demo:

Example: Remove the class 'blue' and 'under' from the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="blue under">Hello</p>

  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>
  <p class="blue under">Goodbye</p>
<script>$("p:odd").removeClass("blue under");</script>
</body>
</html>

Demo:

Example: Remove all the classes from the matched elements.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="blue under">Hello</p>
  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>

  <p class="blue under">Goodbye</p>
<script>$("p:eq(1)").removeClass();</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .removeClass().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.text() – jQuery API

jQuery API

Skip to content
  • api

.text()

Categories: Attributes | Manipulation > DOM Insertion, Inside | Manipulation > General Attributes
Contents:
  • text()
    • .text()
  • text( textString )
    • .text( textString )
    • .text( function(index, text) )

.text() Returns: String

Description: Get the combined text contents of each element in the set of matched elements, including their descendants.

  • version added: 1.0.text()

Unlike the .html() method, .text() can be used in both XML and HTML documents. The result of the .text() method is a string containing the combined text of all matched elements. Consider the following HTML:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
  <ul>
  <li>list item 1</li>
  <li>list <strong>item</strong> 2</li>
  </ul>
  </div>

The code $('div.demo-container').text() would produce the following result:

Demonstration Box list item 1 list item 2

The .text() method cannot be used on input elements. For input field text, use the .val() method.

As of jQuery 1.4, the .text() method returns the value of text and CDATA nodes as well as element nodes.

Example:

Find the text in the first paragraph (stripping out the html), then set the html of the last paragraph to show it is just text (the red bold is gone).

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; margin:8px; }
  b { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><b>Test</b> Paragraph.</p>

  <p></p>
<script>
    var str = $("p:first").text();
    $("p:last").html(str);
</script>
</body>
</html>

Demo:

.text( textString ) Returns: jQuery

Description: Set the content of each element in the set of matched elements to the specified text.

  • version added: 1.0.text( textString )

    textStringA string of text to set as the content of each matched element.

  • version added: 1.4.text( function(index, text) )

    function(index, text)A function returning the text content to set. Receives the index position of the element in the set and the old text value as arguments.

Unlike the .html() method, .text() can be used in both XML and HTML documents.

We need to be aware that this method escapes the string provided as necessary so that it will render correctly in HTML. To do so, it calls the DOM method .createTextNode(), which replaces special characters with their HTML entity equivalents (such as &lt; for <). Consider the following HTML:

<div class="demo-container">
  <div class="demo-box">Demonstration Box</div>
  <ul>
    <li>list item 1</li>
    <li>list <strong>item</strong> 2</li>
  </ul>
</div>

The code $('div.demo-container').text('<p>This is a test.</p>'); will produce the following DOM output:

<div class="demo-container">
&lt;p&gt;This is a test.&lt;/p&gt;
</div>

It will appear on a rendered page as though the tags were exposed, like this:

<p>This is a test</p>

The .text() method cannot be used on input elements. For input field text, use the .val() method.

As of jQuery 1.4, the .text() method allows us to set the text content by passing in a function.

$('ul li').text(function() {
  return 'item number ' + ($(this).index() + 1);
});

Given an unordered list with three <li> elements, this example will produce the following DOM output:

<ul>
  <li>item number 1</li>
  <li>item number 2</li>
  <li>item number 3</li>
</ul>

Example:

Add text to the paragraph (notice the bold tag is escaped).

<!DOCTYPE html>
<html>
<head>
  <style>

  p { color:blue; margin:8px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Test Paragraph.</p>
<script>$("p").text("<b>Some</b> new text.");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .text().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Anders Mattson
    This function seems to return different values for different browsers in some cases. IE7, for example strips out new lines and tabs in clean text content while Firefox (currently using 3.5.7) and Chrome doesn't.

    <div>One row
    Another row with tab at the beginning</div>

    returns "One rowAnother row" in IE7.

    Can anyone confirm or deny this?

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.toggleClass() – jQuery API

jQuery API

Skip to content
  • api

.toggleClass()

Categories: Attributes | Manipulation > Class Attribute | CSS

.toggleClass( className ) Returns: jQuery

Description: Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

  • version added: 1.0.toggleClass( className )

    classNameA class name to be toggled for each element in the matched set.

  • version added: 1.3.toggleClass( className, switch )

    classNameA class name to be toggled for each element in the matched set.

    switchA boolean value to determine whether the class should be added or removed.

  • version added: 1.4.toggleClass( function(index, class), [ switch ] )

    function(index, class)A function that returns a class name to be toggled in the class attribute of each element in the matched set. Receives the index position of the element in the set and the old class value as arguments.

    switchA boolean value to determine whether the class should be added or removed.

This method takes one or more class names as its parameter. In the first version, if an element in the matched set of elements already has the class, then it is removed; if an element does not have the class, then it is added. For example, we can apply .toggleClass() to a simple <div>:

<div class="tumble">Some text.</div>

The first time we apply $('div.tumble').toggleClass('bounce'), we get the following:

<div class="tumble bounce">Some text.</div>

The second time we apply $('div.tumble').toggleClass('bounce'), the <div> class is returned to the single tumble value:

<div class="tumble">Some text.</div>

Applying .toggleClass('bounce spin') to the same <div> alternates between <div class="tumble bounce spin"> and <div class="tumble">.

The second version of .toggleClass() uses the second parameter for determining whether the class should be added or removed. If this parameter's value is true, then the class is added; if false, the class is removed. In essence, the statement:

$('#foo').toggleClass(className, addOrRemove);

is equivalent to:

if (addOrRemove) {
    $('#foo').addClass(className);
  }
  else {
    $('#foo').removeClass(className);
  }

As of jQuery 1.4, the .toggleClass() method allows us to indicate the class name to be toggled by passing in a function.

$('div.foo').toggleClass(function() {
  if ($(this).parent().is('.bar') {
    return 'happy';
  } else {
    return 'sad';
  }
});

This example will toggle the happy class for <div class="foo"> elements if their parent element has a class of bar; otherwise, it will toggle the sad class.

Examples:

Example: Toggle the class 'highlight' when a paragraph is clicked.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin: 4px; font-size:16px; font-weight:bolder;
      cursor:pointer; }
  .blue { color:blue; }
  .highlight { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="blue">Click to toggle</p>
  <p class="blue highlight">highlight</p>
  <p class="blue">on these</p>
  <p class="blue">paragraphs</p>
<script>
    $("p").click(function () {
      $(this).toggleClass("highlight");
    });
</script>
</body>
</html>

Demo:

Example: Add the "highlight" class to the clicked paragraph on every third click of that paragraph, remove it every first and second click.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { margin: 4px; font-size:16px; font-weight:bolder;
      cursor:pointer; }
  .blue { color:blue; }
  .highlight { background:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="blue">Click to toggle (<span>clicks: 0</span>)</p>
  <p class="blue highlight">highlight (<span>clicks: 0</span>)</p>
  <p class="blue">on these (<span>clicks: 0</span>)</p>

  <p class="blue">paragraphs (<span>clicks: 0</span>)</p>
<script>
var count = 0;
$("p").each(function() {
  var $thisParagraph = $(this);
  var count = 0;
  $thisParagraph.click(function() {
    count++;
    $thisParagraph.find("span").text('clicks: ' + count);
    $thisParagraph.toggleClass("highlight", count % 3 == 0);
  });
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .toggleClass().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.val() – jQuery API

jQuery API

Skip to content
  • api

.val()

Categories: Attributes | Forms | Manipulation > General Attributes
Contents:
  • val()
    • .val()
  • val( value )
    • .val( value )
    • .val( function )

.val() Returns: String, Array

Description: Get the current value of the first element in the set of matched elements.

  • version added: 1.0.val()

The .val() method is primarily used to get the values of form elements. In the case of <select multiple="multiple"> elements, the .val() method returns an array containing each selected option.

For selects and checkboxes, you can also use the :selected and :checked selectors to get at values, for example:

$('select.foo option:selected').val();    // get the value from a dropdown select
$('select.foo').val();                    // get the value from a dropdown select even easier
$('input:checkbox:checked').val();        // get the value from a checked checkbox
$('input:radio[name=bar]:checked').val(); // get the value from a set of radio buttons

Examples:

Example: Get the single value from a single select and an array of values from a multiple select and display their values.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:red; margin:4px; }
  b { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p></p>
  <select id="single">
    <option>Single</option>
    <option>Single2</option>

  </select>
  <select id="multiple" multiple="multiple">
    <option selected="selected">Multiple</option>
    <option>Multiple2</option>

    <option selected="selected">Multiple3</option>
  </select>
<script>
    function displayVals() {
      var singleValues = $("#single").val();
      var multipleValues = $("#multiple").val() || [];
      $("p").html("<b>Single:</b> " +
                  singleValues +
                  " <b>Multiple:</b> " +
                  multipleValues.join(", "));
    }

    $("select").change(displayVals);
    displayVals();

</script>
</body>
</html>

Demo:

Example: Find the value of an input box.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { color:blue; margin:8px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input type="text" value="some text"/>
  <p></p>
<script>
    $("input").keyup(function () {
      var value = $(this).val();
      $("p").text(value);
    }).keyup();
</script>
</body>
</html>

Demo:

.val( value ) Returns: jQuery

Description: Set the value of each element in the set of matched elements.

  • version added: 1.0.val( value )

    valueA string of text or an array of strings to set as the value property of each matched element.

  • version added: 1.4.val( function )

    functionA function returning the value to set.

This method is typically used to set the values of form fields. For <select multiple="multiple"> elements, multiple <option>s can be selected by passing in an array.

The .val() method allows us to set the value by passing in a function:

$('input:text.items').val(function() {
  return this.value + ' ' + this.className;
});

This example appends the string "items" to the text inputs' values.

In jQuery 1.2, this is also able to set the value of select elements, but selecting the appropriate options.

Examples:

Example: Set the value of an input box.

<!DOCTYPE html>
<html>
<head>
  <style>
  button { margin:4px; cursor:pointer; }
  input { margin:4px; color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <button>Feed</button>
    <button>the</button>

    <button>Input</button>
  </div>
  <input type="text" value="click a button" />
<script>

    $("button").click(function () {
      var text = $(this).text();
      $("input").val(text);
    });
</script>
</body>
</html>

Demo:

Example: Set a single select and a multiple select .

<!DOCTYPE html>
<html>
<head>
  <style>
  body { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <select id="single">
    <option>Single</option>
    <option>Single2</option>
  </select>

  <select id="multiple" multiple="multiple">
    <option selected="selected">Multiple</option>
    <option>Multiple2</option>

    <option selected="selected">Multiple3</option>
  </select><br/>
  <input type="checkbox" name="checkboxname" value="check1"/> check1
  <input type="checkbox" name="checkboxname" value="check2"/> check2
  <input type="radio"  name="r" value="radio1"/> radio1
  <input type="radio"  name="r" value="radio2"/> radio2
<script>

    $("#single").val("Single2");
    $("#multiple").val(["Multiple2", "Multiple3"]);
    $("input").val(["check1","check2", "radio1" ]);

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .val().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Core – jQuery API

jQuery API

Skip to content
  • api

Core

  • jQuery()

    Accepts a string containing a CSS selector which is then used to match a set of elements.

  • jQuery.noConflict()

    Setup Methods

    Relinquish jQuery's control of the $ variable.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery() – jQuery API

jQuery API

Skip to content
  • api

jQuery()

Categories: Core
Contents:
  • jQuery( selector, [ context ] )
    • jQuery( selector, [ context ] )
    • jQuery( element )
    • jQuery( elementArray )
    • jQuery( jQuery object )
    • jQuery()
  • jQuery( html, [ ownerDocument ] )
    • jQuery( html, [ ownerDocument ] )
    • jQuery( html, props )
  • jQuery( callback )
    • jQuery( callback )

jQuery( selector, [ context ] ) Returns: jQuery

Description: Accepts a string containing a CSS selector which is then used to match a set of elements.

  • version added: 1.0jQuery( selector, [ context ] )

    selectorA string containing a selector expression

    contextA DOM Element, Document, or jQuery to use as context

  • version added: 1.0jQuery( element )

    elementA DOM element to wrap in a jQuery object.

  • version added: 1.0jQuery( elementArray )

    elementArrayAn array containing a set of DOM elements to wrap in a jQuery object.

  • version added: 1.0jQuery( jQuery object )

    jQuery objectAn existing jQuery object to clone.

  • version added: 1.4jQuery()

In the first formulation listed above, $() searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:

$('div.foo');

Selector Context

By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the $() function. For example, if within a callback function we wish to do a search for an element, we can restrict that search:

$('div.foo').click(function() {
  $('span', this).addClass('bar');
});

Since we've restricted the span selector to the context of this, only spans within the clicked element will get the additional class.

Internally, selector context is implemented with the .find() method, so $('span', this) is equivalent to $(this).find('span').

Using DOM elements

The second and third formulations of this function allow us to create a jQuery object using a DOM element or elements that we have already found in some other way. A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

$('div.foo').click(function() {
  $(this).slideUp();
});

This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the this keyword as a bare DOM element, the element must be wrapped in a jQuery object before we can call jQuery methods on it.

When XML data is returned from an Ajax call, we can use the $() function to wrap it in a jQuery object that we can easily work with. Once this is done, we can retrieve individual elements of the XML structure using .find() and other DOM traversal methods.

Cloning jQuery Objects

When a jQuery object is passed as a parameter to the $() function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.

Returning an Empty Set

As of jQuery 1.4, if you pass no arguments in to the jQuery() method, an empty jQuery set will be returned. In previous versions of jQuery, a set containing the document node would be returned.

Examples:

Example: Finds all p elements that are children of a div element.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>one</p> <div><p>two</p></div> <p>three</p>
<script>$("div > p").css("border", "1px solid gray");</script>
</body>
</html>

Demo:

Result:

[ <p>two</p> ]

Example: Finds all inputs of type radio within the first form in the document.

$("input:radio", document.forms[0]);

Example: Finds all div elements within an XML document from an Ajax response.

$("div", xml.responseXML);

Example: Sets the background color of the page to black.

$(document.body).css( "background", "black" );

Example: Hides all the input elements within a form.

$(myForm.elements).hide()

jQuery( html, [ ownerDocument ] ) Returns: jQuery

Description: Creates DOM elements on the fly from the provided string of raw HTML.

  • version added: 1.0jQuery( html, [ ownerDocument ] )

    htmlA string of HTML to create on the fly. Note that this parses HTML, not XML.

    ownerDocumentA document in which the new elements will be created

  • version added: 1.4jQuery( html, props )

    htmlA string defining a single, standalone, HTML element (e.g. <div/> or <div>).

    propsAttributes, events, and methods to call on the newly-created element.

Creating New Elements

If a string is passed as the parameter to $(), jQuery examines the string to see if it looks like HTML (i.e., it has <tag ... > somewhere within the string). If not, the string is interpreted as a selector expression, as explained above. But if the string appears to be an HTML snippet, jQuery attempts to create new DOM elements as described by the HTML. Then a jQuery object is created and returned that refers to these elements. We can perform any of the usual jQuery methods on this object:

$('<p id="test">My <em>new</em> text</p>').appendTo('body');

When the HTML is more complex than a single tag without attributes, as it is in the above example, the actual creation of the elements is handled by the browser's innerHTML mechanism. Specifically, jQuery creates a new <div> element and sets the innerHTML property of the element to the HTML snippet that was passed in. When the parameter has a single tag, such as $('<img />') or $('<a></a>'), jQuery creates the element using the native JavaScript createElement() function.

To ensure cross-platform compatibility, the snippet must be well-formed. Tags that can contain other elements should be paired with a closing tag:

$('<a href="http://jquery.com"></a>');

Alternatively, jQuery allows XML-like tag syntax (with or without a space before the slash):

$('<a/>');

Tags that cannot contain elements may be quick-closed or not:

$('<img />');
$('<input>');

As of jQuery 1.4, we can pass a map of properties to the second argument. This argument accepts a superset of properties that can be passed to the .attr() method. Furthermore, any event type can be passed in, and the following jQuery methods can be called: val, css, html, text, data, width, height, or offset.

Examples:

Example: Creates a div element (and all of its contents) dynamically, and appends it to the body element. Internally, an element is created and its innerHTML property set to the given markup. It is therefore both quite flexible and limited.

$("<div><p>Hello</p></div>").appendTo("body")

Example: Create some DOM elements.

$("<div>", {
  "class": "test",
  text: "Click me!",
  click: function(){
    $(this).toggleClass("test");
  }
}).appendTo("body");

$("<input>", {
  type: "text",
  val: "Test",
  focusin: function() {
    $(this).addClass("active");
  },
  focusout: function() {
    $(this).removeClass("active");
  }
}).appendTo("form");

jQuery( callback ) Returns: jQuery

Description: Binds a function to be executed when the DOM has finished loading.

  • version added: 1.0jQuery( callback )

    callbackThe function to execute when the DOM is ready.

This function behaves just like $(document).ready(), in that it should be used to wrap other $() operations on your page that depend on the DOM being ready. While this function is, technically, chainable, there really isn't much use for chaining against it.

Examples:

Example: Executes the function when the DOM is ready to be used.

$(function(){
  // Document is ready
});

Example: Uses both the shortcut for $(document).ready() and the argument to write failsafe jQuery code using the $ alias, without relying on the global alias.

jQuery(function($) {
  // Your code using failsafe $ alias here...
});

Comments

  • Please keep comments relevant to jQuery().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • MarcusT
    With regard to the use of jQuery(callback) for executing code when the document is ready, it has never been clear from the documentation whether you can do this any number of times (perhaps at different places in the HTML document) and be assured that each chunk of code will be called after each other, or whether each use of jQuery(callback) overwrites the previous call. While the answer can of course be found by simply testing, this shouldn't be necessary to be sure, and hence I'd like to see this made abundantly clear in the documentation with an explicit statement.
  • Bob
    The addition of the properties parameter is a great addition. It will certainly save writing code, which is what jQuery is all about.
  • MJ
    jQuery link broken it takes you to the types page but there is no anchor for jQuery. Where is the jQuery object documented.
  • bronson
    "jQuery examines the string to see if it looks like HTML"

    How? Must the HTML string begin with '<'?
  • Karl Swedberg
    It doesn't need to begin with '<. jQuery uses a regular expression to inspect the string, and the part of it that tests for an HTML-string match is ^[^<]*(<[\w\W]+>)[^>]*$.

    In case you're not very familiar with regular expressions, it basically checks for something that looks like an HTML tag anywhere within the string.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.noConflict() – jQuery API

jQuery API

Skip to content
  • api

jQuery.noConflict()

Categories: Core | Miscellaneous > Setup Methods

jQuery.noConflict( [ removeAll ] ) Returns: Object

Description: Relinquish jQuery's control of the $ variable.

  • version added: 1.0jQuery.noConflict( [ removeAll ] )

    removeAllA Boolean indicating whether to remove all jQuery variables from the global scope (including jQuery itself).

Many JavaScript libraries use $ as a function or variable name, just as jQuery does. In jQuery's case, $ is just an alias for jQuery, so all functionality is available without using $. If we need to use another JavaScript library alongside jQuery, we can return control of $ back to the other library with a call to $.noConflict():

<script type="text/javascript" src="other_lib.js"></script>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript">
  $.noConflict();
  // Code that uses other library's $ can follow here.
</script>

This technique is especially effective in conjunction with the .ready() method's ability to alias the jQuery object, as within callback passed to .ready() we can use $ if we wish without fear of conflicts later:

<script type="text/javascript" src="other_lib.js"></script>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript">
  $.noConflict();
  jQuery(document).ready(function($) {
    // Code that uses jQuery's $ can follow here.
  });
  // Code that uses other library's $ can follow here.
</script>

If necessary, we can free up the jQuery name as well by passing true as an argument to the method. This is rarely necessary, and if we must do this (for example, if we need to use multiple versions of the jQuery library on the same page), we need to consider that most plug-ins rely on the presence of the jQuery variable and may not operate correctly in this situation.

Examples:

Example: Maps the original object that was referenced by $ back to $.

jQuery.noConflict();
// Do something with jQuery
jQuery("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';

Example: Reverts the $ alias and then creates and executes a function to provide the $ as a jQuery alias inside the functions scope. Inside the function the original $ object is not available. This works well for most plugins that don't rely on any other library.

jQuery.noConflict();
(function($) {
  $(function() {
    // more code using $ as alias to jQuery
  });
})(jQuery);
// other code using $ as an alias to the other library

Example: You can chain the jQuery.noConflict() with the shorthand ready for a compact code.

jQuery.noConflict()(function(){
    // code using jQuery
});
// other code using $ as an alias to the other library

Example: Creates a different alias instead of jQuery to use in the rest of the script.

var j = jQuery.noConflict();
// Do something with jQuery
j("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';

Example: Completely move jQuery to a new namespace in another object.

var dom = {};
dom.query = jQuery.noConflict(true);

Result:

// Do something with the new jQuery
dom.query("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';
// Do something with another version of jQuery
jQuery("div > p").hide();

Comments

  • Please keep comments relevant to jQuery.noConflict().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


CSS – jQuery API

jQuery API

Skip to content
  • api

CSS

These methods get and set CSS-related properties of elements.

  • .addClass()

    Attributes, Class Attribute

    Adds the specified class(es) to each of the set of matched elements.

  • .css()

    Style Properties

    Get the value of a style property for the first element in the set of matched elements.

  • .hasClass()

    Attributes, Class Attribute

    Determine whether any of the matched elements are assigned the given class.

  • .height()

    Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements.

  • .innerHeight()

    Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • .innerWidth()

    Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • .offset()

    Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • .outerHeight()

    Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding and border.

  • .outerWidth()

    Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding and border.

  • .position()

    Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • .removeClass()

    Attributes, Class Attribute

    Remove one or all classes from each element in the set of matched elements.

  • .scrollLeft()

    Offset, Style Properties

    Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • .scrollTop()

    Offset, Style Properties

    Get the current vertical position of the scroll bar for the first element in the set of matched elements.

  • .toggleClass()

    Attributes, Class Attribute

    Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

  • .width()

    Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.css() – jQuery API

jQuery API

Skip to content
  • api

.css()

Categories: CSS | Manipulation > Style Properties
Contents:
  • css( propertyName )
    • .css( propertyName )
  • css( propertyName, value )
    • .css( propertyName, value )
    • .css( propertyName, function(index, value) )
    • .css( map )

.css( propertyName ) Returns: String

Description: Get the value of a style property for the first element in the set of matched elements.

  • version added: 1.0.css( propertyName )

    propertyNameA CSS property.

The .css() method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the getComputedStyle() method in standards-based browsers versus the currentStyle and runtimeStyle properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the float property as styleFloat, while W3C standards-compliant browsers refer to it as cssFloat. The .css() method accounts for such differences, producing the same result no matter which term we use. For example, an element that is floated left will return the string left for each of the following three lines:

  1. $('div.left').css('float');
  2. $('div.left').css('cssFloat');
  3. $('div.left').css('styleFloat');

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css('background-color') and .css('backgroundColor').

Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: $(elem).css('marginTop') and $(elem).css('marginRight'), and so on.

Example:

To access the background color of a clicked div.

<!DOCTYPE html>
<html>
<head>
  <style>
div { width:60px; height:60px; margin:5px; float:left; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<span id="result">&nbsp;</span>
<div style="background-color:blue;"></div>
<div style="background-color:rgb(15,99,30);"></div>

<div style="background-color:#123456;"></div>
<div style="background-color:#f11;"></div>
<script>
$("div").click(function () {
  var color = $(this).css("background-color");
  $("#result").html("That div is <span style='color:" +
                     color + ";'>" + color + "</span>.");
});

</script>
</body>
</html>

Demo:

.css( propertyName, value ) Returns: jQuery

Description: Set one or more CSS properties for the set of matched elements.

  • version added: 1.0.css( propertyName, value )

    propertyNameA CSS property name.

    valueA value to set for the property.

  • version added: 1.4.css( propertyName, function(index, value) )

    propertyNameA CSS property name.

    function(index, value)A function returning the value to set. Receives the index position of the element in the set and the old value as arguments.

  • version added: 1.0.css( map )

    mapA map of property-value pairs to set.

As with the .attr() method, the .css() method makes setting properties of elements quick and easy. This method can take either a property name and value as separate parameters, or a single map of key-value pairs (JavaScript object notation).

Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both .css({'background-color': '#ffe', 'border-left': '5px solid #ccc'}) and .css({backgroundColor: '#ffe', borderLeft: '5px solid #ccc'}). Notice that with the DOM notation, quotation marks around the property names are optional, but with CSS notation they're required due to the hyphen in the name.

As with .attr(), .css() allows us to pass a function as the property value:

$('div.example').css('width', function(index) {
  return index * 50;
});

This example sets the widths of the matched elements to incrementally larger values.

Examples:

Example: To change the color of any paragraph to red on mouseover event.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; width:200px; font-size:14px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

  <p>Just roll the mouse over me.</p>

  <p>Or me to see a color change.</p>

<script>
  $("p").mouseover(function () {
    $(this).css("color","red");
  });
</script>
</body>
</html>

Demo:

Example: To highlight a clicked word in the paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; font-weight:bold; cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<p>
  Once upon a time there was a man
  who lived in a pizza parlor. This
  man just loved pizza and ate it all
  the time.  He went on to be the
  happiest man in the world.  The end.
</p>
<script>
  var words = $("p:first").text().split(" ");
  var text = words.join("</span> <span>");
  $("p:first").html("<span>" + text + "</span>");
  $("span").click(function () {
    $(this).css("background-color","yellow");
  });

</script>
</body>
</html>

Demo:

Example: To set the color of all paragraphs to red and background to blue:

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:green; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

  <p>Move the mouse over a paragraph.</p>
  <p>Like this one or the one above.</p>

<script>
  $("p").hover(function () {
    $(this).css({'background-color' : 'yellow', 'font-weight' : 'bolder'});
  }, function () {
    var cssObj = {
      'background-color' : '#ddd',
      'font-weight' : '',
      'color' : 'rgb(0,40,244)'
    }
    $(this).css(cssObj);
  });
</script>
</body>
</html>

Demo:

Example: Increase the size of a div when you click it:

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width: 20px; height: 15px; background-color: #f33; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

  <div>click</div>
  <div>click</div>

<script>
  $("div").click(function() {
    $(this).css({
      width: function(index, value) {
        return parseFloat(value) * 1.2;
      },
      height: function(index, value) {
        return parseFloat(value) * 1.2;
      }

    });
  });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .css().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Etienne Dupuis
    If you have a background image, and want to use a rollover, i made the following: Name your background images with blablabla-off.png or blablabla-on.png. Then you only set the class "box" to the items you want the rollover to happen

    $(".box").mouseenter(function() {
    $(this).css({ background: $(this).css("background-image").replace("-off.", "-on.") + ' no-repeat' });
    });

    $(".box").mouseleave(function() {
    $(this).css({ background: $(this).css("background-image").replace("-on.", "-off.") + ' no-repeat' });
    });
  • Ben Hollis
    I wouldn't recommend that - why not just change the background image in CSS by adding and removing a class? Or use :hover in your CSS and avoid JS altogether.
  • Aivo Paas
    The last example seems to have wrong source code (same as previous one).

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.height() – jQuery API

jQuery API

Skip to content
  • api

.height()

Categories: CSS | Dimensions | Manipulation > Style Properties
Contents:
  • height()
    • .height()
  • height( value )
    • .height( value )

.height() Returns: Integer

Description: Get the current computed height for the first element in the set of matched elements.

  • version added: 1.0.height()

The difference between .css('height') and .height() is that the latter returns a unit-less pixel value (for example, 400) while the former returns a value with units intact (for example, 400px). The .height() method is recommended when an element's height needs to be used in a mathematical calculation.

This method is also able to find the height of the window and document.

$(window).height();   // returns height of browser viewport
$(document).height(); // returns height of HTML document

Example:

Show various heights. Note the values are from the iframe so might be smaller than you expected. The yellow highlight shows the iframe body.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { background:yellow; }
  button { font-size:12px; margin:2px; }
  p { width:150px; border:1px red solid; }
  div { color:red; font-weight:bold; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="getp">Get Paragraph Height</button>
  <button id="getd">Get Document Height</button>
  <button id="getw">Get Window Height</button>

  <div>&nbsp;</div>
  <p>
    Sample paragraph to test height
  </p>
<script>
    function showHeight(ele, h) {
      $("div").text("The height for the " + ele +
                    " is " + h + "px.");
    }
    $("#getp").click(function () {
      showHeight("paragraph", $("p").height());
    });
    $("#getd").click(function () {
      showHeight("document", $(document).height());
    });
    $("#getw").click(function () {
      showHeight("window", $(window).height());
    });

</script>
</body>
</html>

Demo:

.height( value ) Returns: jQuery

Description: Set the CSS height of every matched element.

  • version added: 1.0.height( value )

    valueAn integer representing the number of pixels, or an integer with an optional unit of measure appended (as a string).

When calling .height(value), the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, any valid CSS measurement may be used for the height (such as 100px, 50%, or auto). Note that in modern browsers, the CSS height property does not include padding, border, or margin.

If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.

Example:

To set the height of each div on click to 30px plus a color change.

<!DOCTYPE html>
<html>
<head>
  <style>div { width:50px; height:70px; float:left; margin:5px;
        background:rgb(255,140,0); cursor:pointer; }  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>
<script>$("div").one('click', function () {
      $(this).height(30)
             .css({cursor:"auto", backgroundColor:"green"});
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .height().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.innerHeight() – jQuery API

jQuery API

Skip to content
  • api

.innerHeight()

Categories: CSS | Dimensions | Manipulation > Style Properties

.innerHeight() Returns: Integer

Description: Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • version added: 1.2.6.innerHeight()

This method returns the height of the element, including top and bottom padding, in pixels.

This method is not applicable to window and document objects; for these, use .height() instead.

Example:

Get the innerHeight of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>p { margin:10px;padding:5px;border:2px solid #666; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
$("p:last").text( "innerHeight:" + p.innerHeight() );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .innerHeight().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.innerWidth() – jQuery API

jQuery API

Skip to content
  • api

.innerWidth()

Categories: CSS | Dimensions | Manipulation > Style Properties

.innerWidth() Returns: Integer

Description: Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • version added: 1.2.6.innerWidth()

This method returns the width of the element, including left and right padding, in pixels.

This method is not applicable to window and document objects; for these, use .width() instead.

Example:

Get the innerWidth of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>p { margin:10px;padding:5px;border:2px solid #666; } </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
$("p:last").text( "innerWidth:" + p.innerWidth() );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .innerWidth().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.offset() – jQuery API

jQuery API

Skip to content
  • api

.offset()

Categories: CSS | Offset | Manipulation > Style Properties
Contents:
  • offset()
    • .offset()
  • offset( coordinates )
    • .offset( coordinates )
    • .offset( function(index, coords) )

.offset() Returns: Object

Description: Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • version added: 1.2.offset()

The .offset() method allows us to retrieve the current position of an element relative to the document. Contrast this with .position(), which retrieves the current position relative to the offset parent. When positioning a new element on top of an existing one for global manipulation (in particular, for implementing drag-and-drop), .offset() is the more useful.

.offset() returns an object containing the properties top and left.

Examples:

Example: Access the offset of the second paragraph:

<!DOCTYPE html>
<html>
<head>
  <style>
p { margin-left:10px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p>2nd Paragraph</p>
<script>var p = $("p:last");
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );</script>
</body>
</html>

Demo:

Example: Click to see the offset.

<!DOCTYPE html>
<html>
<head>
  <style>
p { margin-left:10px; color:blue; width:200px;
    cursor:pointer; }
span { color:red; cursor:pointer; }
div.abs { width:50px; height:50px; position:absolute;
          left:220px; top:35px; background-color:green;
          cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="result">Click an element.</div>
<p>
  This is the best way to <span>find</span> an offset.
</p>

<div class="abs">
</div>

<script>
$("*", document.body).click(function (e) {
  var offset = $(this).offset();
  e.stopPropagation();
  $("#result").text(this.tagName + " coords ( " + offset.left + ", " +
                                  offset.top + " )");
});

</script>
</body>
</html>

Demo:

.offset( coordinates ) Returns: Object

Description: Set the current coordinates of every element in the set of matched elements, relative to the document.

  • version added: 1.4.offset( coordinates )

    coordinatesAn object containing the properties top and left, which are integers indicating the new top and left coordinates for the elements.

  • version added: 1.4.offset( function(index, coords) )

    function(index, coords)A function to return the coordinates to set. Receives the index of the element in the collection as the first argument and the current coordinates as the second argument.

The .offset() setter method allows us to reposition an element. The element's position is specified relative to the document. If the element's position style property is currently static, it will be set to relative to allow for this repositioning.

Example:

Set the offset of the second paragraph:

<!DOCTYPE html>
<html>
<head>
  <style>p { margin-left:10px; } </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p>2nd Paragraph</p>
<script>$("p:last").offset({ top: 10, left: 30 });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .offset().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Shawphy
    The returns of .offset( coordinates ) is Object? Maybe a jQuery?
  • jason
    maybe .offset( coordinates(index, coords) ) is offset( function(index, coords) )
  • Karl Swedberg
    fixed. thanks!
  • yunchenge
    What's the "i" means in "coordinates(i, coords)"?
  • John Resig
    It's the index of the element in the collection (works just like calling the each method).
  • yunchenge
    Is that means ".offset( coordinates(index, coords) )" can set for a collection, while ".offset( coordinates )" just for the first element in a collection?
  • John Resig
    .offset(), and all other jQuery setters, set for all elements - this argument just sets using a function.
  • yunchenge
    But the description is "Set the current coordinates of the first element in the set of matched elements, relative to the document.". Is that wrong?
  • John Resig
    Ah, that was a mistake in the description, fixed.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.outerHeight() – jQuery API

jQuery API

Skip to content
  • api

.outerHeight()

Categories: CSS | Dimensions | Manipulation > Style Properties

.outerHeight( [ includeMargin ] ) Returns: Integer

Description: Get the current computed height for the first element in the set of matched elements, including padding and border.

  • version added: 1.2.6.outerHeight( [ includeMargin ] )

    includeMarginA Boolean indicating whether to include the element's margin in the calculation.

If includeMargin is omitted or false, the padding and border are included in the calculation; if true, the margin is also included.

This method is not applicable to window and document objects; for these, use .height() instead.

Example:

Get the outerHeight of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>p { margin:10px;padding:5px;border:2px solid #666; } </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
$("p:last").text( "outerHeight:" + p.outerHeight() + " , outerHeight(true):" + p.outerHeight(true) );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .outerHeight().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.outerWidth() – jQuery API

jQuery API

Skip to content
  • api

.outerWidth()

Categories: CSS | Dimensions | Manipulation > Style Properties

.outerWidth( [ includeMargin ] ) Returns: Integer

Description: Get the current computed width for the first element in the set of matched elements, including padding and border.

  • version added: 1.2.6.outerWidth( [ includeMargin ] )

    includeMarginA Boolean indicating whether to include the element's margin in the calculation.

Returns the width of the element, along with left and right padding, border, and optionally margin, in pixels.

If includeMargin is omitted or false, the padding and border are included in the calculation; if true, the margin is also included.

This method is not applicable to window and document objects; for these, use .width() instead.

Example:

Get the outerWidth of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { margin:10px;padding:5px;border:2px solid #666; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
$("p:last").text( "outerWidth:" + p.outerWidth()+ " , outerWidth(true):" + p.outerWidth(true) );

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .outerWidth().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.position() – jQuery API

jQuery API

Skip to content
  • api

.position()

Categories: CSS | Offset | Manipulation > Style Properties

.position() Returns: Object

Description: Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • version added: 1.2.position()

The .position() method allows us to retrieve the current position of an element relative to the offset parent. Contrast this with .offset(), which retrieves the current position relative to the document. When positioning a new element near another one and within the same containing DOM element, .position() is the more useful.

Returns an object containing the properties top and left.

Example:

Access the position of the second paragraph:

<!DOCTYPE html>
<html>
<head>
  <style>

  div { padding: 15px;}
  p { margin-left:10px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><p>Hello</p></div><p></p>
<script>var p = $("p:first");
var position = p.position();
$("p:last").text( "left: " + position.left + ", top: " + position.top );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .position().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Alejo
    I have a problem with .position() in Google Chrome.

    It may sound weird, but when browsing with Google Chrome, .position().left doesn't returns the actual X position of an element. I have a DIV:

    #imgCont
    {
    margin: auto;
    width: 50%;
    height: 300px;
    background-color: #408080;
    }

    When browsing with Firefox or IE, .position().left returns ~= 260, but Google Chrome returns 8! The curious thing is that .position().top works great. Any ideas?

    (excuse my poor english)
  • Angelo D'Ambrosio
    It's not possible also to set the position with the same method?

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.scrollLeft() – jQuery API

jQuery API

Skip to content
  • api

.scrollLeft()

Categories: CSS | Offset | Manipulation > Style Properties
Contents:
  • scrollLeft()
    • .scrollLeft()
  • scrollLeft( value )
    • .scrollLeft( value )

.scrollLeft() Returns: Integer

Description: Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • version added: 1.2.6.scrollLeft()

The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very left, or if the element is not scrollable, this number will be 0.

Example:

Get the scrollLeft of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
    p { margin:10px;padding:5px;border:2px solid #666; }
    </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
            $("p:last").text( "scrollLeft:" + p.scrollLeft() );

            </script>
</body>
</html>

Demo:

.scrollLeft( value ) Returns: jQuery

Description: Set the current horizontal position of the scroll bar for each of the set of matched elements.

  • version added: 1.2.6.scrollLeft( value )

    valueAn integer indicating the new position to set the scroll bar to.

The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the scrollLeft positions the horizontal scroll of each matched element.

Example:

Set the scrollLeft of a div.

<!DOCTYPE html>
<html>
<head>
  <style>
  div.demo {
  background:#CCCCCC none repeat scroll 0 0;
  border:3px solid #666666;
  margin:5px;
  padding:5px;
  position:relative;
  width:200px;
  height:100px;
  overflow:auto;
  }
  p { margin:10px;padding:5px;border:2px solid #666;width:1000px;height:1000px; }
    </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div class="demo"><h1>lalala</h1><p>Hello</p></div>
<script>$("div.demo").scrollLeft(300);
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .scrollLeft().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.scrollTop() – jQuery API

jQuery API

Skip to content
  • api

.scrollTop()

Categories: CSS | Offset | Manipulation > Style Properties
Contents:
  • scrollTop()
    • .scrollTop()
  • scrollTop( value )
    • .scrollTop( value )

.scrollTop() Returns: Integer

Description: Get the current vertical position of the scroll bar for the first element in the set of matched elements.

  • version added: 1.2.6.scrollTop()

The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very top, or if the element is not scrollable, this number will be 0.

Example:

Get the scrollTop of a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { margin:10px;padding:5px;border:2px solid #666; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><p></p>
<script>var p = $("p:first");
$("p:last").text( "scrollTop:" + p.scrollTop() );

</script>
</body>
</html>

Demo:

.scrollTop( value ) Returns: jQuery

Description: Set the current vertical position of the scroll bar for each of the set of matched elements.

  • version added: 1.2.6.scrollTop( value )

    valueAn integer indicating the new position to set the scroll bar to.

The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the scrollTop positions the vertical scroll of each matched element.

Example:

Set the scrollTop of a div.

<!DOCTYPE html>
<html>
<head>
  <style>
div.demo {
background:#CCCCCC none repeat scroll 0 0;
border:3px solid #666666;
margin:5px;
padding:5px;
position:relative;
width:200px;
height:100px;
overflow:auto;
}
  p { margin:10px;padding:5px;border:2px solid #666;width:1000px;height:1000px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div class="demo"><h1>lalala</h1><p>Hello</p></div>
<script>$("div.demo").scrollTop(300);
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .scrollTop().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.width() – jQuery API

jQuery API

Skip to content
  • api

.width()

Categories: CSS | Dimensions | Manipulation > Style Properties
Contents:
  • width()
    • .width()
  • width( value )
    • .width( value )

.width() Returns: Integer

Description: Get the current computed width for the first element in the set of matched elements.

  • version added: 1.0.width()

The difference between .css(width) and .width() is that the latter returns a unit-less pixel value (for example, 400) while the former returns a value with units intact (for example, 400px). The .width() method is recommended when an element's width needs to be used in a mathematical calculation.

This method is also able to find the width of the window and document.

$(window).width();   // returns width of browser viewport
$(document).width(); // returns width of HTML document

Example:

Show various widths. Note the values are from the iframe so might be smaller than you expected. The yellow highlight shows the iframe body.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { background:yellow; }
  button { font-size:12px; margin:2px; }
  p { width:150px; border:1px red solid; }
  div { color:red; font-weight:bold;  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="getp">Get Paragraph Width</button>
  <button id="getd">Get Document Width</button>
  <button id="getw">Get Window Width</button>

  <div>&nbsp;</div>
  <p>
    Sample paragraph to test width
  </p>
<script>
    function showWidth(ele, w) {
      $("div").text("The width for the " + ele +
                    " is " + w + "px.");
    }
    $("#getp").click(function () {
      showWidth("paragraph", $("p").width());
    });
    $("#getd").click(function () {
      showWidth("document", $(document).width());
    });
    $("#getw").click(function () {
      showWidth("window", $(window).width());
    });

</script>
</body>
</html>

Demo:

.width( value ) Returns: jQuery

Description: Set the CSS width of each element in the set of matched elements.

  • version added: 1.0.width( value )

    valueAn integer representing the number of pixels, or an integer along with an optional unit of measure appended (as a string).

When calling .width('value'), the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, any valid CSS measurement may be used for the width (such as 100px, 50%, or auto). Note that in modern browsers, the CSS width property does not include padding, border, or margin.

If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.

Example:

To set the width of each div on click to 30px plus a color change.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:70px; height:50px; float:left; margin:5px;
        background:red; cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div>d</div>

  <div>d</div>
  <div>d</div>
  <div>d</div>
<script>

    $("div").one('click', function () {
      $(this).width(30)
             .css({cursor:"auto", "background-color":"blue"});
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .width().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Data – jQuery API

jQuery API

Skip to content
  • api

Data

These methods allow us to associate arbitrary data with specific DOM elements.

  • .clearQueue()

    Custom, Utilities

    Remove from the queue all items that have not yet been run.

  • jQuery.data()

    Utilities

    Store arbitrary data associated with the specified element.

  • .dequeue()

    Custom, Utilities

    Execute the next function on the queue for the matched elements.

  • jQuery.dequeue()

    Utilities

    Execute the next function on the queue for the matched elements.

  • .queue()

    Custom, Utilities

    Show the queue of functions to be executed on the matched elements.

  • jQuery.queue()

    Utilities

    Show the queue of functions to be executed on the matched elements.

  • jQuery.removeData()

    Utilities

    Remove a previously-stored piece of data.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.clearQueue() – jQuery API

jQuery API

Skip to content
  • api

.clearQueue()

Categories: Effects > Custom | Data | Utilities

.clearQueue( [ queueName ] ) Returns: jQuery

Description: Remove from the queue all items that have not yet been run.

  • version added: 1.4.clearQueue( [ queueName ] )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

When the .clearQueue() method is called, all functions on the queue that have not been executed are removed from the queue. When used without an argument, .clearQueue() removes the remaining functions from fx, the standard effects queue. In this way it is similar to .stop(true). However, while the .stop() method is meant to be used only with animations, .clearQueue() can also be used to remove any function that has been added to a generic jQuery queue with the .queue() method.

Example:

Empty the queue.

<!DOCTYPE html>
<html>
<head>
  <style>
div { margin:3px; width:40px; height:40px;
    position:absolute; left:0px; top:30px;
    background:green; display:none; }
div.newcolor { background:blue; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="start">Start</button>
<button id="stop">Stop</button>
<div></div>
<script>$("#start").click(function () {
  $("div").show("slow");
  $("div").animate({left:'+=200'},5000);
  $("div").queue(function () {
    $(this).addClass("newcolor");
    $(this).dequeue();
  });
  $("div").animate({left:'-=200'},1500);
  $("div").queue(function () {
    $(this).removeClass("newcolor");
    $(this).dequeue();
  });
  $("div").slideUp();
});
$("#stop").click(function () {
  $("div").clearQueue();
  $("div").stop();
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .clearQueue().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.data() – jQuery API

jQuery API

Skip to content
  • api

jQuery.data()

Categories: Data | Utilities
Contents:
  • jQuery.data( element, key, value )
    • jQuery.data( element, key, value )
  • jQuery.data( element, key )
    • jQuery.data( element, key )
    • jQuery.data()

jQuery.data( element, key, value ) Returns: jQuery

Description: Store arbitrary data associated with the specified element.

  • version added: 1.2.3jQuery.data( element, key, value )

    elementThe DOM element to associate with the data.

    keyA string naming the piece of data to set.

    valueThe new data value.

Note: This is a low-level method; you should probably use .data() instead.

The jQuery.data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can set several distinct values for a single element and retrieve them later:

jQuery.data(document.body, 'foo', 52);
        jQuery.data(document.body, 'bar', 'test');

Example:

Store then retrieve a value from the div element.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    The values stored were
    <span></span>
    and
    <span></span>
  </div>
<script>var div = $("div")[0];
    jQuery.data(div, "test", { first: 16, last: "pizza!" });
    $("span:first").text(jQuery.data(div, "test").first);
    $("span:last").text(jQuery.data(div, "test").last);</script>
</body>
</html>

Demo:

jQuery.data( element, key ) Returns: Object

Description: Returns value at named data store for the element, as set by jQuery.data(element, name, value), or the full data store for the element.

  • version added: 1.2.3jQuery.data( element, key )

    elementThe DOM element to query for the data.

    keyName of the data stored.

  • version added: 1.4jQuery.data()

Note: This is a low-level method; you should probably use .data() instead.

The jQuery.data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:

alert(jQuery.data( document.body, 'foo' );
alert(jQuery.data( document.body ));

The above lines alert the data values that were set on the body element. If nothing was set on that element, an empty string is returned.

Calling jQuery.data() with no parameters retrieves all of the values as a JavaScript object.

Example:

Get the data named "blah" stored at for an element.

<!DOCTYPE html>
<html>
<head>
  <style>
div { margin:5px; background:yellow; }
button { margin:5px; font-size:14px; }
p { margin:5px; color:blue; }
span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>A div</div>
<button>Get "blah" from the div</button>
<button>Set "blah" to "hello"</button>

<button>Set "blah" to 86</button>
<button>Remove "blah" from the div</button>
<p>The "blah" value of this div is <span>?</span></p>
<script>
$("button").click(function(e) {
  var value, div = $("div")[0];

  switch ($("button").index(this)) {
    case 0 :
      value = jQuery.data(div, "blah");
      break;
    case 1 :
      jQuery.data(div, "blah", "hello");
      value = "Stored!";
      break;
    case 2 :
      jQuery.data(div, "blah", 86);
      value = "Stored!";
      break;
    case 3 :
      jQuery.removeData(div, "blah");
      value = "Removed!";
      break;
  }

  $("span").text("" + value);
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.data().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • jason
    it's jQuery.data() not Query.data(element) ??
  • Mark Gibson
    You appear to be missing the first 'element' parameter from the function signatures...

    jQuery.data( element, key, value ) etc.
  • davemethvin
    Thanks, it's fixed now.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.dequeue() – jQuery API

jQuery API

Skip to content
  • api

.dequeue()

Categories: Effects > Custom | Data | Utilities

.dequeue( [ queueName ] ) Returns: jQuery

Description: Execute the next function on the queue for the matched elements.

  • version added: 1.2.dequeue( [ queueName ] )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

When .dequeue() is called, the next function on the queue is removed from the queue, and then executed. This function should in turn (directly or indirectly) cause .dequeue() to be called, so that the sequence can continue.

Example:

Use dequeue to end a custom queue function which allows the queue to keep going.

<!DOCTYPE html>
<html>
<head>
  <style>div { margin:3px; width:50px; position:absolute;
        height:50px; left:10px; top:30px;
        background-color:yellow; }
  div.red { background-color:red; }  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Start</button>  <div></div>
<script>$("button").click(function () {
      $("div").animate({left:'+=200px'}, 2000);
      $("div").animate({top:'0px'}, 600);
      $("div").queue(function () {
        $(this).toggleClass("red");
         $(this).dequeue();
              });
      $("div").animate({left:'10px', top:'30px'}, 700);
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .dequeue().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.dequeue() – jQuery API

jQuery API

Skip to content
  • api

jQuery.dequeue()

Categories: Data | Utilities

jQuery.dequeue( [ queueName ] ) Returns: jQuery

Description: Execute the next function on the queue for the matched elements.

  • version added: 1.3jQuery.dequeue( [ queueName ] )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

Note: This is a low-level method, you should probably use .dequeue() instead.

When jQuery.dequeue() is called, the next function on the queue is removed from the queue, and then executed. This function should in turn (directly or indirectly) cause jQuery.dequeue() to be called, so that the sequence can continue.

Example:

Use dequeue to end a custom queue function which allows the queue to keep going.

<!DOCTYPE html>
<html>
<head>
  <style>div { margin:3px; width:50px; position:absolute;
        height:50px; left:10px; top:30px;
        background-color:yellow; }
  div.red { background-color:red; }  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Start</button>  <div></div>
<script>$("button").click(function () {
      $("div").animate({left:'+=200px'}, 2000);
      $("div").animate({top:'0px'}, 600);
      $("div").queue(function () {
        $(this).toggleClass("red");
         $.dequeue( this );
              });
      $("div").animate({left:'10px', top:'30px'}, 700);
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.dequeue().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.queue() – jQuery API

jQuery API

Skip to content
  • api

.queue()

Categories: Effects > Custom | Data | Utilities
Contents:
  • queue( [ queueName ] )
    • .queue( [ queueName ] )
  • queue( [ queueName ], newQueue )
    • .queue( [ queueName ], newQueue )
    • .queue( [ queueName ], callback( next ) )

.queue( [ queueName ] ) Returns: Array

Description: Show the queue of functions to be executed on the matched elements.

  • version added: 1.2.queue( [ queueName ] )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

Example:

Show the length of the queue.

<!DOCTYPE html>
<html>
<head>
  <style>div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  span { color:red; }  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="show">Show Length of Queue</button>
  <span></span>
  <div></div>
<script>$("#show").click(function () {
      var n = $("div").queue("fx");
      $("span").text("Queue length is: " + n.length);
    });
    function runIt() {
      $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      $("div").slideToggle(1000);
      $("div").slideToggle("fast");
      $("div").animate({left:'-=200'},1500);
      $("div").hide("slow");
      $("div").show(1200);
      $("div").slideUp("normal", runIt);
    }
    runIt();</script>
</body>
</html>

Demo:

.queue( [ queueName ], newQueue ) Returns: jQuery

Description: Manipulate the queue of functions to be executed on the matched elements.

  • version added: 1.2.queue( [ queueName ], newQueue )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

    newQueueAn array of functions to replace the current queue contents.

  • version added: 1.2.queue( [ queueName ], callback( next ) )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

    callback( next )The new function to add to the queue, with a function to call that will dequeue the next item.

Every element can have one to many queues of functions attached to it by jQuery. In most applications, only one queue (called fx) is used. Queues allow a sequence of actions to be called on an element asynchronously, without halting program execution. The typical example of this is calling multiple animation methods on an element. For example:

$('#foo').slideUp().fadeIn();

When this statement is executed, the element begins its sliding animation immediately, but the fading transition is placed on the fx queue to be called only once the sliding transition is complete.

The .queue() method allows us to directly manipulate this queue of functions. Calling .queue() with a callback is particularly useful; it allows us to place a new function at the end of the queue.

This feature is similar to providing a callback function with an animation method, but does not require the callback to be given at the time the animation is performed.

$('#foo').slideUp();
$('#foo').queue(function() {
  alert('Animation complete.');
  $(this).dequeue();
});

This is equivalent to:

$('#foo').slideUp(function() {
  alert('Animation complete.');
});

Note that when adding a function with .queue(), we should ensure that .dequeue() is eventually called so that the next function in line executes.

In jQuery 1.4 the function that's called is passed in another function, as the first argument, that when called automatically dequeues the next item and keeps the queue moving. You would use it like so:

$("#test").queue(function(next) {
    // Do some stuff...
    next();
});

Examples:

Example: Queue a custom function.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Click here...
  <div></div>
<script>$(document.body).click(function () {
      $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      $("div").queue(function () {
        $(this).addClass("newcolor");
        $(this).dequeue();
      });
      $("div").animate({left:'-=200'},500);
      $("div").queue(function () {
        $(this).removeClass("newcolor");
        $(this).dequeue();
      });
      $("div").slideUp();
    });</script>
</body>
</html>

Demo:

Example: Set a queue array to delete the queue.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="start">Start</button>
  <button id="stop">Stop</button>
  <div></div>
<script>$("#start").click(function () {
      $("div").show("slow");
      $("div").animate({left:'+=200'},5000);
      $("div").queue(function () {
        $(this).addClass("newcolor");
        $(this).dequeue();
      });
      $("div").animate({left:'-=200'},1500);
      $("div").queue(function () {
        $(this).removeClass("newcolor");
        $(this).dequeue();
      });
      $("div").slideUp();
    });
    $("#stop").click(function () {
      $("div").queue("fx", []);
      $("div").stop();
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .queue().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.queue() – jQuery API

jQuery API

Skip to content
  • api

jQuery.queue()

Categories: Data | Utilities
Contents:
  • jQuery.queue( [ queueName ] )
    • jQuery.queue( [ queueName ] )
  • jQuery.queue( [ queueName ], newQueue )
    • jQuery.queue( [ queueName ], newQueue )
    • jQuery.queue( [ queueName ], callback() )

jQuery.queue( [ queueName ] ) Returns: Array

Description: Show the queue of functions to be executed on the matched elements.

  • version added: 1.3jQuery.queue( [ queueName ] )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

Note: This is a low-level method, you should probably use .queue() instead.

Example:

Show the length of the queue.

<!DOCTYPE html>
<html>
<head>
  <style>div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  span { color:red; }  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="show">Show Length of Queue</button>
  <span></span>
  <div></div>
<script>$("#show").click(function () {
      var n = jQuery.queue( $("div")[0], "fx" );
      $("span").text("Queue length is: " + n.length);
    });
    function runIt() {
      $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      $("div").slideToggle(1000);
      $("div").slideToggle("fast");
      $("div").animate({left:'-=200'},1500);
      $("div").hide("slow");
      $("div").show(1200);
      $("div").slideUp("normal", runIt);
    }
    runIt();</script>
</body>
</html>

Demo:

jQuery.queue( [ queueName ], newQueue ) Returns: jQuery

Description: Manipulate the queue of functions to be executed on the matched elements.

  • version added: 1.3jQuery.queue( [ queueName ], newQueue )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

    newQueueAn array of functions to replace the current queue contents.

  • version added: 1.3jQuery.queue( [ queueName ], callback() )

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

    callback()The new function to add to the queue.

Note: This is a low-level method, you should probably use .queue() instead.

Every element can have one to many queues of functions attached to it by jQuery. In most applications, only one queue (called fx) is used. Queues allow a sequence of actions to be called on an element asynchronously, without halting program execution.

The jQuery.queue() method allows us to directly manipulate this queue of functions. Calling jQuery.queue() with a callback is particularly useful; it allows us to place a new function at the end of the queue.

Note that when adding a function with jQuery.queue(), we should ensure that jQuery.dequeue() is eventually called so that the next function in line executes.

Examples:

Example: Queue a custom function.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Click here...
  <div></div>
<script>$(document.body).click(function () {
            $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      jQuery.queue( $("div")[0], function () {
        $(this).addClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").animate({left:'-=200'},500);
      jQuery.queue( $("div")[0], function () {
        $(this).removeClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").slideUp();
    });</script>
</body>
</html>

Demo:

Example: Set a queue array to delete the queue.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:3px; width:40px; height:40px;
        position:absolute; left:0px; top:30px;
        background:green; display:none; }
  div.newcolor { background:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="start">Start</button>
  <button id="stop">Stop</button>
  <div></div>
<script>$("#start").click(function () {
      $("div").show("slow");
      $("div").animate({left:'+=200'},5000);
      jQuery.queue( $("div")[0], function () {
        $(this).addClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").animate({left:'-=200'},1500);
      jQuery.queue( $("div")[0], function () {
        $(this).removeClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").slideUp();
    });
    $("#stop").click(function () {
      jQuery.queue( $("div")[0], "fx", [] );
      $("div").stop();
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.queue().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • James Padolsey
    The first argument to jQuery.queue, according the source, is an element, then queueName, and then a newQueue/callback.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.removeData() – jQuery API

jQuery API

Skip to content
  • api

jQuery.removeData()

Categories: Data | Utilities

jQuery.removeData( [ name ] ) Returns: jQuery

Description: Remove a previously-stored piece of data.

  • version added: 1.2.3jQuery.removeData( [ name ] )

    nameA string naming the piece of data to delete.

Note: This is a low-level method, you should probably use .removeData() instead.

The jQuery.removeData() method allows us to remove values that were previously set using jQuery.data(). When called with the name of a key, jQuery.removeData() deletes that particular value; when called with no arguments, all values are removed.

Example:

Set a data store for 2 names then remove one of them.

<!DOCTYPE html>
<html>
<head>
  <style>
        div { margin:2px; color:blue; }
        span { color:red; }
        </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>value1 before creation: <span></span></div>
        <div>value1 after creation: <span></span></div>
        <div>value1 after removal: <span></span></div>
        <div>value2 after removal: <span></span></div>
<script>
var div = $("div")[0];
$("span:eq(0)").text("" + $("div").data("test1"));
jQuery.data(div, "test1", "VALUE-1");
jQuery.data(div, "test2", "VALUE-2");
$("span:eq(1)").text("" + jQuery.data(div, "test1"));
jQuery.removeData(div, "test1");
$("span:eq(2)").text("" + jQuery.data(div, "test1"));
$("span:eq(3)").text("" + jQuery.data(div, "test2"));</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.removeData().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Dimensions – jQuery API

jQuery API

Skip to content
  • api

Dimensions

  • .height()

    CSS, Style Properties

    Get the current computed height for the first element in the set of matched elements.

  • .innerHeight()

    CSS, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • .innerWidth()

    CSS, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • .outerHeight()

    CSS, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding and border.

  • .outerWidth()

    CSS, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding and border.

  • .width()

    CSS, Style Properties

    Get the current computed width for the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Effects – jQuery API

jQuery API

Skip to content
  • api

Effects

The jQuery library provides several techniques for adding animation to a web page. These include simple, standard animations that are frequently used, and the ability to craft sophisticated custom effects. In this chapter, we’ll closely examine each of the effect methods, revealing all of the mechanisms jQuery has for providing visual feedback to the user.

  • .animate()

    Custom

    Perform a custom animation of a set of CSS properties.

  • .clearQueue()

    Custom, Data, Utilities

    Remove from the queue all items that have not yet been run.

  • .delay()

    Custom

    Set a timer to delay execution of subsequent items in the queue.

  • .dequeue()

    Custom, Data, Utilities

    Execute the next function on the queue for the matched elements.

  • .fadeIn()

    Fading

    Display the matched elements by fading them to opaque.

  • .fadeOut()

    Fading

    Hide the matched elements by fading them to transparent.

  • .fadeTo()

    Fading

    Adjust the opacity of the matched elements.

  • jQuery.fx.off

    Custom, Properties of the Global jQuery Object

    Globally disable all animations.

  • .hide()

    Basics

    Hide the matched elements.

  • .queue()

    Custom, Data, Utilities

    Show the queue of functions to be executed on the matched elements.

  • .show()

    Basics

    Display the matched elements.

  • .slideDown()

    Sliding

    Display the matched elements with a sliding motion.

  • .slideToggle()

    Sliding

    Display or hide the matched elements with a sliding motion.

  • .slideUp()

    Sliding

    Hide the matched elements with a sliding motion.

  • .stop()

    Custom

    Stop the currently-running animation on the matched elements.

  • .toggle()

    Basics, Mouse Events

    Bind two or more handlers to the matched elements, to be executed on alternate clicks.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Basics – jQuery API

jQuery API

Skip to content
  • api

Basics

  • .hide()

    Hide the matched elements.

  • .show()

    Display the matched elements.

  • .toggle()

    Mouse Events

    Bind two or more handlers to the matched elements, to be executed on alternate clicks.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.hide() – jQuery API

jQuery API

Skip to content
  • api

.hide()

Categories: Effects > Basics

.hide( ) Returns: jQuery

Description: Hide the matched elements.

  • version added: 1.0.hide()

  • version added: 1.0.hide( duration, [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

With no parameters, the .hide() method is the simplest way to hide an element:

$('.target').hide();

The matched elements will be hidden immediately, with no animation. This is roughly equivalent to calling .css('display', 'none'), except that the value of the display property is saved in jQuery's data cache so that display can later be restored to its initial value. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline.

When a duration is provided, .hide() becomes an animation method. The .hide() method animates the width, height, and opacity of the matched elements simultaneously. When these properties reach 0, the display style property is set to none to ensure that the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />
With the element initially shown, we can hide it slowly:
$('#clickme').click(function() {
  $('#book').hide('slow', function() {
    $.print('Animation complete.');
  });
});

Examples:

Example: Hides all paragraphs then the link on click.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <a href="#">Click to hide me too</a>
  <p>Here is another paragraph</p>
<script>

    $("p").hide();
    $("a").click(function () {
      $(this).hide();
      return true;
    });
</script>
</body>
</html>

Demo:

Example: Animates all shown paragraphs to hide slowly, completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { background:#dad; font-weight:bold; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Hide 'em</button>

  <p>Hiya</p>
  <p>Such interesting text, eh?</p>
<script>
    $("button").click(function () {
      $("p").hide("slow");
    });
</script>
</body>
</html>

Demo:

Example: Animates all spans (words in this case) to hide fastly, completing each animation within 200 milliseconds. Once each animation is done, it starts the next one.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { background:#def3ca; padding:3px; float:left; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="hidr">Hide</button>
  <button id="showr">Show</button>
  <div>

    <span>Once</span> <span>upon</span> <span>a</span>
    <span>time</span> <span>there</span> <span>were</span>
    <span>three</span> <span>programmers...</span>

  </div>
<script>
    $("#hidr").click(function () {
      $("span:last-child").hide("fast", function () {
        // use callee so don't have to name the function
        $(this).prev().hide("fast", arguments.callee);
      });
    });
    $("#showr").click(function () {
      $("span").show(2000);
    });

</script>
</body>
</html>

Demo:

Example: Hides the divs when clicked over 2 seconds, then removes the div element when its hidden. Try clicking on more than one box at a time.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { background:#ece0fb; width:30px;
        height:40px; margin:2px; float:left; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
<script>
    for (var i = 0; i < 5; i++) {
      $("<div>").appendTo(document.body);
    }
    $("div").click(function () {
      $(this).hide(2000, function () {
        $(this).remove();
      });
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .hide().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.show() – jQuery API

jQuery API

Skip to content
  • api

.show()

Categories: Effects > Basics

.show( ) Returns: jQuery

Description: Display the matched elements.

  • version added: 1.0.show()

  • version added: 1.0.show( duration, [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

With no parameters, the .show() method is the simplest way to display an element:

$('.target').show();

The matched elements will be revealed immediately, with no animation. This is roughly equivalent to calling .css('display', 'block'), except that the display property is restored to whatever it was initially. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline.

When a duration is provided, .show() becomes an animation method. The .show() method animates the width, height, and opacity of the matched elements simultaneously.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />
With the element initially hidden, we can show it slowly:
$('#clickme').click(function() {
  $('#book').show('slow', function() {
    // Animation complete.
  });
});

Examples:

Example: Animates all hidden paragraphs to show slowly, completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
      p { background:yellow; }
      </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Show it</button>

      <p style="display: none">Hello  2</p>
<script>
    $("button").click(function () {
    $("p").show("slow");
    });
    </script>
</body>
</html>

Demo:

Example: Animates all hidden divs to show fastly in order, completing each animation within 200 milliseconds. Once each animation is done, it starts the next one.

<!DOCTYPE html>
<html>
<head>
  <style>
          div { background:#def3ca; margin:3px; width:80px;
          display:none; float:left; text-align:center; }
          </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="showr">Show</button>
          <button id="hidr">Hide</button>
          <div>Hello 3,</div>

          <div>how</div>
          <div>are</div>
          <div>you?</div>
<script>
        $("#showr").click(function () {
        $("div:eq(0)").show("fast", function () {
        // use callee so don't have to name the function
        $(this).next().show("fast", arguments.callee);
        });
        });
        $("#hidr").click(function () {
        $("div").hide(2000);
        });

        </script>
</body>
</html>

Demo:

Example: Animates all span and input elements to show normally. Once the animation is done, it changes the text.

<!DOCTYPE html>
<html>
<head>
  <style>
              span { display:none; }
              div { display:none; }
              p { font-weight:bold; background-color:#fcd; }
              </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Do it!</button>
              <span>Are you sure? (type 'yes' if you are) </span>
              <div>
                <form>

                  <input type="text"  value="as;ldkfjalsdf"/>
                </form>
              </div>
              <p style="display:none;">I'm hidden...</p>
<script>
            function doIt() {
            $("span,div").show("normal");
            }
            $("button").click(doIt); // can pass in function name
            $("form").submit(function () {
            if ($("input").val() == "yes") {
            $("p").show(4000, function () {
            $(this).text("Ok, DONE! (now showing)");
            });
            }
            $("span,div").hide("normal");
            return false; // to stop the submit
            });

            </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .show().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.toggle() – jQuery API

jQuery API

Skip to content
  • api

.toggle()

Categories: Effects > Basics | Events > Mouse Events
Contents:
  • toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] )
    • .toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] )
  • toggle( [ duration ], [ callback ] )
    • .toggle( [ duration ], [ callback ] )
    • .toggle( showOrHide )

.toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] ) Returns: jQuery

Description: Bind two or more handlers to the matched elements, to be executed on alternate clicks.

  • version added: 1.0.toggle( handler(eventObject), handler(eventObject), [ handler(eventObject) ] )

    handler(eventObject)A function to execute every even time the element is clicked.

    handler(eventObject)A function to execute every odd time the element is clicked.

    handler(eventObject)Additional handlers to cycle through after clicks.

The .toggle() method binds a handler for the click event, so the rules outlined for the triggering of click apply here as well.

For example, consider the HTML:
<div id="target">
  Click here
</div>

Event handlers can then be bound to the <div>:

$('#target').toggle(function() {
  alert(First handler for .toggle() called.);
}, function() {
  alert(Second handler for .toggle() called.);
});

As the element is clicked repeatedly, the messages alternate:

First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.
Second handler for .toggle() called.
First handler for .toggle() called.

If more than two handlers are provided, .toggle() will cycle among all of them. For example, if there are three handlers, then the first handler will be called on the first click, the fourth click, the seventh click, and so on.

The .toggle() method is provided for convenience. It is relatively straightforward to implement the same behavior by hand, and this can be necessary if the assumptions built into .toggle() prove limiting. For example, .toggle() is not guaranteed to work correctly if applied twice to the same element. Since .toggle() internally uses a click handler to do its work, we must unbind click to remove a behavior attached with .toggle(), so other click handlers can be caught in the crossfire. The implementation also calls .preventDefault() on the event, so links will not be followed and buttons will not be clicked if .toggle() has been called on the element.

Examples:

Example: Click to toggle highlight on the list item.

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { margin:10px; list-style:inside circle; font-weight:bold; }
  li { cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
    <li>Go to the store</li>
    <li>Pick up dinner</li>
    <li>Debug crash</li>

    <li>Take a jog</li>
  </ul>
<script>
    $("li").toggle(
      function () {
        $(this).css({"list-style-type":"disc", "color":"blue"});
      },
      function () {
        $(this).css({"list-style-type":"disc", "color":"red"});
      },
      function () {
        $(this).css({"list-style-type":"", "color":""});
      }
    );

</script>
</body>
</html>

Demo:

Example: To toggle a style on table cells:

$("td").toggle(
  function () {
    $(this).addClass("selected");
  },
  function () {
    $(this).removeClass("selected");
  }
);

.toggle( [ duration ], [ callback ] ) Returns: jQuery

Description: Display or hide the matched elements.

  • version added: 1.0.toggle( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

  • version added: 1.3.toggle( showOrHide )

    showOrHideA Boolean indicating whether to show or hide the elements.

Examples:

Example: Toggles all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>
<script>

$("button").click(function () {
$("p").toggle();
});
</script>
</body>
</html>

Demo:

Example: Animates all paragraphs to be shown if they are hidden and hidden if they are visible, completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
p { background:#dad;
font-weight:bold;
font-size:16px; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Toggle 'em</button>

<p>Hiya</p>
<p>Such interesting text, eh?</p>
<script>
$("button").click(function () {
$("p").toggle("slow");
});
</script>
</body>
</html>

Demo:

Example: Shows all paragraphs, then hides them all, back and forth.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>
<script>

var flip = 0;
$("button").click(function () {
$("p").toggle( flip++ % 2 == 0 );
});
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .toggle().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Custom – jQuery API

jQuery API

Skip to content
  • api

Custom

These methods allow you to create effects that are not provided “out of the box” by jQuery.

  • .animate()

    Perform a custom animation of a set of CSS properties.

  • .clearQueue()

    Data, Utilities

    Remove from the queue all items that have not yet been run.

  • .delay()

    Set a timer to delay execution of subsequent items in the queue.

  • .dequeue()

    Data, Utilities

    Execute the next function on the queue for the matched elements.

  • jQuery.fx.off

    Properties of the Global jQuery Object

    Globally disable all animations.

  • .queue()

    Data, Utilities

    Show the queue of functions to be executed on the matched elements.

  • .stop()

    Stop the currently-running animation on the matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.animate() – jQuery API

jQuery API

Skip to content
  • api

.animate()

Categories: Effects > Custom

.animate( properties, [ duration ], [ easing ], [ callback ] ) Returns: jQuery

Description: Perform a custom animation of a set of CSS properties.

  • version added: 1.0.animate( properties, [ duration ], [ easing ], [ callback ] )

    propertiesA map of CSS properties that the animation will move toward.

    durationA string or number determining how long the animation will run.

    easingA string indicating which easing function to use for the transition.

    callbackA function to call once the animation is complete.

  • version added: 1.0.animate( properties, options )

    propertiesA map of CSS properties that the animation will move toward.

    optionsA map of additional options to pass to the method. Supported keys:

    • duration: A string or number determining how long the animation will run.
    • easing: A string indicating which easing function to use for the transition.
    • complete: A function to call once the animation is complete.
    • step: A function to be called after each step of the animation.
    • queue: A Boolean indicating whether to place the animation in the effects queue. If false, the animation will begin immediately.
    • specialEasing: A map of one or more of the CSS properties defined by the properties argument and their corresponding easing functions.

The .animate() method allows us to create animation effects on any numeric CSS property. The only required parameter is a map of CSS properties. This map is similar to the one that can be sent to the .css() method, except that the range of properties is more restrictive.

All animated properties are treated as a number of pixels unless otherwise specified. The units em and % can be specified where applicable.

In addition to numeric values, each property can take the strings 'show', 'hide', and 'toggle'. These shortcuts allow for custom hiding and showing animations that take into account the display type of the element.

Animated properties can also be relative. If a value is supplied with a leading += or -= sequence of characters, then the target value is computed by adding or subtracting the given number from the current value of the property.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123"
  style="position: relative; left: 10px;" />

We can animate the opacity, left offset, and height of the image simultaneously:

$('#clickme').click(function() {
  $('#book').animate({
    opacity: 0.25,
    left: '+=50',
    height: 'toggle'
  }, 5000, function() {
    // Animation complete.
  });
});

Note that we have specified toggle as the target value of the height property. Since the image was visible before, the animation shrinks the height to 0 to hide it. A second click then reverses this transition:

The opacity of the image is already at its target value, so this property is not animated by the second click. Since we specified the target value for left as a relative value, the image moves even farther to the right during this second animation.

The position attribute of the element must not be static if we wish to animate the left property as we do in the example.

The jQuery UI project extends the .animate() method by allowing some non-numeric styles such as colors to be animated. The project also includes mechanisms for specifying animations through CSS classes rather than individual attributes.

The remaining parameter of .animate() is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called swing, and one that progresses at a constant pace, called linear. More easing functions are available with the use of plug-ins, most notably the jQuery UI suite.

Per-property Easing

As of jQuery version 1.4, we can set per-property easing functions within a single .animate() call. In the first version of .animate(), each property can take an array as its value: The first member of the array is the CSS property and the second member is an easing function. If a per-property easing function is not defined for a particular property, it uses the value of the .animate() method's optional easing argument. If the easing argument is not defined, the default swing function is used.

We can, for example, simultaneously animate the width and height with the swing easing function and the opacity with the linear easing function:

$('#clickme').click(function() {
  $('#book').animate({
    width: ['toggle', 'swing'],
    height: ['toggle', 'swing'],
    opacity: 'toggle'
  }, 5000, 'linear', function() {
      $(this).after('<div>Animation complete.</div>');
  });
});

In the second version of .animate(), the options map can include the specialEasing property, which is itself a map of CSS properties and their corresponding easing functions. We can simultaneously animate the width using the linear easing function and the height using the easeOutBounce easing function.

$('#clickme').click(function() {
  $('#book').animate({
    width: 'toggle',
    height: 'toggle'
  }, {
    duration: 5000,
    specialEasing: {
      width: 'linear',
      height: 'easeOutBounce'
    },
    complete: function() {
      $(this).after('<div>Animation complete.</div>');
    }
  });
});

As previously noted, a plug-in is required for the easeOutBounce function.

Examples:

Example: Click the button to animate the div with a number of different properties.

<!DOCTYPE html>
<html>
<head>
  <style>
div {
background-color:#bca;
width:100px;
border:1px solid green;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="go">&raquo; Run</button>

<div id="block">Hello!</div>
<script>

// Using multiple unit types within one animation.
$("#go").click(function(){
  $("#block").animate({
    width: "70%",
    opacity: 0.4,
    marginLeft: "0.6in",
    fontSize: "3em",
    borderWidth: "10px"
  }, 1500 );
});
</script>
</body>
</html>

Demo:

Example: Shows a div animate with a relative move. Click several times on the buttons to see the relative animations queued up.

<!DOCTYPE html>
<html>
<head>
  <style>
div {
position:absolute;
background-color:#abc;
left:50px;
width:90px;
height:90px;
margin:5px;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="left">&laquo;</button> <button id="right">&raquo;</button>
<div class="block"></div>

<script>
$("#right").click(function(){
  $(".block").animate({"left": "+=50px"}, "slow");
});

$("#left").click(function(){
  $(".block").animate({"left": "-=50px"}, "slow");
});

</script>
</body>
</html>

Demo:

Example: Animates all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.

$("p").animate({
  "height": "toggle", "opacity": "toggle"

}, "slow");

Example: Animates all paragraph to a left style of 50 and opacity of 1 (opaque, visible), completing the animation within 500 milliseconds.

$("p").animate({
  "left": "50", "opacity": 1
}, 500);

Example: An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that provides this easing function. Note, this code will do nothing unless the paragraph element is hidden.

$("p").animate({
  "opacity": "show"

}, "slow", "easein");

Example: The first button shows how an unqueued animation works. It expands the div out to 90% width while the font-size is increasing. Once the font-size change is complete, the border animation will begin. The second button starts a traditional chained animation, where each animation will start once the previous animation on the element has completed.

<!DOCTYPE html>
<html>
<head>
  <style>div {
  background-color:#bca;
  width:200px;
  height:1.1em;
  text-align:center;
  border:2px solid green;
  margin:3px;
  font-size:14px;
}
button {
  font-size:14px;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="go1">&raquo; Animate Block1</button>
<button id="go2">&raquo; Animate Block2</button>
<button id="go3">&raquo; Animate Both</button>

<button id="go4">&raquo; Reset</button>
<div id="block1">Block1</div>
<div id="block2">Block2</div>
<script>

$("#go1").click(function(){
  $("#block1").animate( { width:"90%" }, { queue:false, duration:3000 } )
     .animate( { fontSize:"24px" }, 1500 )
     .animate( { borderRightWidth:"15px" }, 1500);
});

$("#go2").click(function(){
  $("#block2").animate( { width:"90%"}, 1000 )
     .animate( { fontSize:"24px" } , 1000 )
     .animate( { borderLeftWidth:"15px" }, 1000);
});

$("#go3").click(function(){
  $("#go1").add("#go2").click();
});

$("#go4").click(function(){
  $("div").css({width:"", fontSize:"", borderWidth:""});
});

</script>
</body>
</html>

Demo:

Example: Animates all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.

$("p").animate({
"height": "toggle", "opacity": "toggle"

}, { duration: "slow" });

Example: Animates all paragraph to a left style of 50 and opacity of 1 (opaque, visible), completing the animation within 500 milliseconds. It also will do it outside the queue, meaning it will automatically start without waiting for its turn.

$("p").animate({
left: "50px", opacity: 1
}, { duration: 500, queue: false });

Example: An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that provides this easing function.

$("p").animate({
"opacity": "show"

}, { "duration": "slow", "easing": "easein" });

Example: An example of using a callback function. The first argument is an array of CSS properties, the second specifies that the animation should take 1000 milliseconds to complete, the third states the easing type, and the fourth argument is an anonymous callback function.

$("p").animate({
height:200, width:400, opacity: .5
}, 1000, "linear", function(){alert("all done");} );

Comments

  • Please keep comments relevant to .animate().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • profulla
    I am using the following snippet for linear scrolling...
    $('#scrollable').animate({scrollTop:$('#someelement') .offset().top;}, 3000);
    But unable to grasp the concept behind scrollTop. Anybody can help me understand?
  • Ray
    the ";"showld not exist after thr word top,and the css name scrollTop should be wrapped in "",as "scrollTop"
  • MarkusMeineke
    Hi,
    I have a question about Example 2. The one with the box and the right and left buttons.
    When I click the right button twice, the two animations are running after each other.
    But I dont want that. I want to change the first animation from 50px to 100px without a stop.
    Is it possible?
    I hope you can understand my bad english.
    Best wishes
  • Gradius
    Can a text color be animated ?
  • Chionsas
    not with a default setup.
    you'll need http://plugins.jquery.com/project/color to do that.

    you could also possibly use some clever css trickery and fadeIn(), depending on circumstances :)
  • Roelof
    I sometimes have problems when using "animate()" with opacity.

    It worked for me again when I made it a fixed (or at least set) width (either px, em or %)

    PS: The new interface is a bit getting used to but the search is great (as is the CSS3 lay-out)!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.delay() – jQuery API

jQuery API

Skip to content
  • api

.delay()

Categories: Effects > Custom

.delay( duration, [ queueName ] ) Returns: jQuery

Description: Set a timer to delay execution of subsequent items in the queue.

  • version added: 1.4.delay( duration, [ queueName ] )

    durationAn integer indicating the number of milliseconds to delay execution of the next item in the queue.

    queueNameA string containing the name of the queue. Defaults to fx, the standard effects queue.

Added to jQuery in version 1.4, the .delay() method allows us to delay the execution of functions that follow it in the queue. It can be used with the standard effects queue or with a custom queue. Using the standard effects queue, we can, for example, set an 800-millisecond delay between the .slideUp() and .fadeIn() of <div id="foo">:

$('#foo').slideUp(300).delay(800).fadeIn(400);

When this statement is executed, the element slides up for 300 milliseconds and then pauses for 800 milliseconds before fading in for 400 milliseconds.

Example:

Animate the hiding and showing of two divs, delaying the first before showing it.

<!DOCTYPE html>
<html>
<head>
  <style>
div { width: 60px; height: 60px; float: left; }
.first { background-color: #3f3; }
.second { background-color: #33f;}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<p><button>Run</button></p>
<div class="first"></div>
<div class="second"></div>

<script>
    $("button").click(function() {
      $("div.first").slideUp(300).delay(800).fadeIn(400);
      $("div.second").slideUp(300).fadeIn(400);
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .delay().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Sitth
    Yes mates. Also need that in some apps as well. Thanks
  • Diego Guidi
    looks like standard "slow" and "fast" timing specifications are working, although they're not documented... anyway, cool :)
  • skaught
    bravo! this is [so far] my most favourite addition.
  • tuncayüner
    Very useful, thank you jQ!
  • nickinuse
    Would be nice if one could apply delay/pause to .each() and similar iterators. For now I figured out this hack:
    //this will fade out and remove table rows one by one with 1/2sec intervals
    var i=0
    $('tr').each(function(){
    $(this).delay(++i*500).fadeOut('slow', function(){$(this).remove()} );
    })
    mainly, the secret is to set delay of each element at a different value.
    Has someone figured out a better way?
  • Roma
    And how we can execute own function after delay?
    Like:
    $.delay(1000, function()
    {
    alert('aloha!');
    });
    Or we should use old style:
    setTimeout(function()
    {
    alert('aloha!');
    }, 1000);
  • bjerh
    You can always write your own function for doing so...

    This is what I'm using:

    $.fn.delay = function(time, callback){
    jQuery.fx.step.delay = function(){};
    return this.animate({delay:1}, time, callback);
    }
  • dowlare
    wow,we just hope for this!
  • webthese
    Great function... Thanks for jQuery team
  • Seth
    When I pass the queueName as a string it ignores the function all together and does not delay.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.fx.off – jQuery API

jQuery API

Skip to content
  • api

jQuery.fx.off

Categories: Effects > Custom | Properties > Properties of the Global jQuery Object

jQuery.fx.off Returns: Boolean

Description: Globally disable all animations.

  • version added: 1.3jQuery.fx.off

When this property is set to true, all animation methods will immediately set elements to their final state when called, rather than displaying an effect. This may be desirable for a couple reasons:

  • jQuery is being used on a low-resource device.
  • Users are encountering accessibility problems with the animations (see the article Turn Off Animation for more information).

Animations can be turned back on by setting the property to false.

Example:

Toggle animation on and off

<!DOCTYPE html>
<html>
<head>
  <style>
    div { width:50px; height:30px; margin:5px; float:left;
          background:green; }
    </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><input type="button" value="Run"/> <button>Toggle fx</button></p>
<div></div>
<script>
var toggleFx = function() {
  $.fx.off = !$.fx.off;
};
toggleFx();

$("button").click(toggleFx)

$("input").click(function(){
  $("div").toggle("slow");
});
  </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.fx.off.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.stop() – jQuery API

jQuery API

Skip to content
  • api

.stop()

Categories: Effects > Custom

.stop( [ clearQueue ], [ jumpToEnd ] ) Returns: jQuery

Description: Stop the currently-running animation on the matched elements.

  • version added: 1.2.stop( [ clearQueue ], [ jumpToEnd ] )

    clearQueueA Boolean indicating whether to remove queued animation as well. Defaults to false.

    jumpToEndA Boolean indicating whether to complete the current animation immediately. Defaults to false.

When .stop() is called on an element, the currently-running animation (if any) is immediately stopped. If, for instance, an element is being hidden with .slideUp() when .stop() is called, the element will now still be displayed, but will be a fraction of its previous height. Callback functions are not called.

If more than one animation method is called on the same element, the later animations are placed in the effects queue for the element. These animations will not begin until the first one completes. When .stop() is called, the next animation in the queue begins immediately. If the clearQueue parameter is provided with a value of true, then the rest of the animations in the queue are removed and never run.

If the jumpToEnd property is provided with a value of true, the current animation stops, but the element is immediately given its target values for each CSS property. In our above .slideUp() example, the element would be immediately hidden. The callback function is then immediately called, if provided.

The usefulness of the .stop() method is evident when we need to animate an element on mouseenter and mouseleave:

<div id="hoverme">
  Hover me
  <img id="hoverme" src="book.png" alt="" width="100" height="123" />
</div>

We can create a nice fade effect without the common problem of multiple queued animations by adding .stop(true, true) to the chain:

$('#hoverme-stop-2').hover(function() {
  $(this).find('img').stop(true, true).fadeOut();
}, function() {
  $(this).find('img').stop(true, true).fadeIn();
});

Animations may be stopped globally by setting the property $.fx.off to true. When this is done, all animation methods will immediately set elements to their final state when called, rather than displaying an effect.

Example:

Click the Go button once to start the animation, then click the STOP button to stop it where it's currently positioned. Another option is to click several buttons to queue them up and see that stop just kills the currently playing one.

<!DOCTYPE html>
<html>
<head>
  <style>div {
position: absolute;
background-color: #abc;
left: 0px;
top:30px;
width: 60px;
height: 60px;
margin: 5px;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="go">Go</button>
<button id="stop">STOP!</button>
<button id="back">Back</button>
<div class="block"></div>
<script>
// Start animation
$("#go").click(function(){
$(".block").animate({left: '+=100px'}, 2000);
});

// Stop animation when button is clicked
$("#stop").click(function(){
$(".block").stop();
});

// Start animation in the opposite direction
$("#back").click(function(){
$(".block").animate({left: '-=100px'}, 2000);
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .stop().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Fading – jQuery API

jQuery API

Skip to content
  • api

Fading

These methods adjust the opacity of elements.

  • .fadeIn()

    Display the matched elements by fading them to opaque.

  • .fadeOut()

    Hide the matched elements by fading them to transparent.

  • .fadeTo()

    Adjust the opacity of the matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.fadeIn() – jQuery API

jQuery API

Skip to content
  • api

.fadeIn()

Categories: Effects > Fading

.fadeIn( [ duration ], [ callback ] ) Returns: jQuery

Description: Display the matched elements by fading them to opaque.

  • version added: 1.0.fadeIn( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

The .fadeIn() method animates the opacity of the matched elements.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
      Click here
    </div>
    <img id="book" src="book.png" alt="" width="100" height="123" />
    With the element initially hidden, we can show it slowly:
    $('#clickme').click(function() {
      $('#book').fadeIn('slow', function() {
        // Animation complete
      });
    });

Examples:

Example: Animates hidden divs to fade in one by one, completing each animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
    span { color:red; cursor:pointer; }
    div { margin:3px; width:80px; display:none;
      height:80px; float:left; }
      div#one { background:#f00; }
      div#two { background:#0f0; }
      div#three { background:#00f; }
    </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>Click here...</span>

    <div id="one"></div>
    <div id="two"></div>
    <div id="three"></div>
<script>
      $(document.body).click(function () {
        $("div:hidden:first").fadeIn("slow");
      });
    </script>
</body>
</html>

Demo:

Example: Fades a red block in over the text. Once the animation is done, it quickly fades in more text on top.

<!DOCTYPE html>
<html>
<head>
  <style>
      p { position:relative; width:400px; height:90px; }
      div { position:absolute; width:400px; height:65px;
        font-size:36px; text-align:center;
        color:yellow; background:red;
        padding-top:25px;
        top:0; left:0; display:none; }
        span { display:none; }
      </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
        Let it be known that the party of the first part
        and the party of the second part are henceforth
        and hereto directed to assess the allegations
        for factual correctness... (<a href="#">click!</a>)
        <div><span>CENSORED!</span></div>

      </p>
<script>
        $("a").click(function () {
          $("div").fadeIn(3000, function () {
            $("span").fadeIn(100);
          });
          return false;
        });

      </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .fadeIn().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.fadeOut() – jQuery API

jQuery API

Skip to content
  • api

.fadeOut()

Categories: Effects > Fading

.fadeOut( [ duration ], [ callback ] ) Returns: jQuery

Description: Hide the matched elements by fading them to transparent.

  • version added: 1.0.fadeOut( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

The .fadeOut() method animates the opacity of the matched elements. Once the opacity reaches 0, the display style property is set to none, so the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />

With the element initially shown, we can hide it slowly:

$('#clickme').click(function() {
  $('#book').fadeOut('slow', function() {
    // Animation complete.
  });
});

Examples:

Example: Animates all paragraphs to fade out, completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { font-size:150%; cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
  If you click on this paragraph
  you'll see it just fade away.
  </p>
<script>
  $("p").click(function () {
  $("p").fadeOut("slow");
  });
  </script>
</body>
</html>

Demo:

Example: Fades out spans in one section that you click on.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { cursor:pointer; }
  span.hilite { background:yellow; }
  div { display:inline; color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <h3>Find the modifiers - <div></div></h3>
  <p>
  If you <span>really</span> want to go outside
  <span>in the cold</span> then make sure to wear
  your <span>warm</span> jacket given to you by
  your <span>favorite</span> teacher.
  </p>
<script>

  $("span").click(function () {
  $(this).fadeOut(1000, function () {
  $("div").text("'" + $(this).text() + "' has faded!");
  $(this).remove();
  });
  });
  $("span").hover(function () {
  $(this).addClass("hilite");
  }, function () {
  $(this).removeClass("hilite");
  });

  </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .fadeOut().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.fadeTo() – jQuery API

jQuery API

Skip to content
  • api

.fadeTo()

Categories: Effects > Fading

.fadeTo( duration, opacity, [ callback ] ) Returns: jQuery

Description: Adjust the opacity of the matched elements.

  • version added: 1.0.fadeTo( duration, opacity, [ callback ] )

    durationA string or number determining how long the animation will run.

    opacityA number between 0 and 1 denoting the target opacity.

    callbackA function to call once the animation is complete.

The .fadeTo() method animates the opacity of the matched elements.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, the default duration of 400 milliseconds is used. Unlike the other effect methods, .fadeTo() requires that duration be explicitly specified.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
    Click here
  </div>
  <img id="book" src="book.png" alt="" width="100" height="123" />
  With the element initially shown, we can dim it slowly:
  $('#clickme').click(function() {
    $('#book').fadeTo('slow', 0.5, function() {
      // Animation complete.
    });
  });

With duration set to 0, this method just changes the opacity CSS property, so .fadeTo(0, opacity) is the same as .css('opacity', opacity).

Examples:

Example: Animates first paragraph to fade to an opacity of 0.33 (33%, about one third visible), completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
Click this paragraph to see it fade.
</p>

<p>
Compare to this one that won't fade.
</p>
<script>
$("p:first").click(function () {
$(this).fadeTo("slow", 0.33);
});
</script>
</body>
</html>

Demo:

Example: Fade div to a random opacity on each click, completing the animation within 200 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
p { width:80px; margin:0; padding:5px; }
div { width:40px; height:40px; position:absolute; }
div#one { top:0; left:0; background:#f00; }
div#two { top:20px; left:20px; background:#0f0; }
div#three { top:40px; left:40px; background:#00f; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>And this is the library that John built...</p>

<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
<script>
$("div").click(function () {
$(this).fadeTo("fast", Math.random());
});
</script>
</body>
</html>

Demo:

Example: Find the right answer! The fade will take 250 milliseconds and change various styles when it completes.

<!DOCTYPE html>
<html>
<head>
  <style>
div, p { width:80px; height:40px; top:0; margin:0;
position:absolute; padding-top:8px; }
p { background:#fcc; text-align:center; }
div { background:blue; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Wrong</p>
<div></div>
<p>Wrong</p>
<div></div>

<p>Right!</p>
<div></div>
<script>
var getPos = function (n) {
return (Math.floor(n) * 90) + "px";
};
$("p").each(function (n) {
var r = Math.floor(Math.random() * 3);
var tmp = $(this).text();
$(this).text($("p:eq(" + r + ")").text());
$("p:eq(" + r + ")").text(tmp);
$(this).css("left", getPos(n));
});
$("div").each(function (n) {
      $(this).css("left", getPos(n));
    })
.css("cursor", "pointer")
.click(function () {
      $(this).fadeTo(250, 0.25, function () {
            $(this).css("cursor", "")
                   .prev().css({"font-weight": "bolder",
                                "font-style": "italic"});
          });
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .fadeTo().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Sliding – jQuery API

jQuery API

Skip to content
  • api

Sliding

  • .slideDown()

    Display the matched elements with a sliding motion.

  • .slideToggle()

    Display or hide the matched elements with a sliding motion.

  • .slideUp()

    Hide the matched elements with a sliding motion.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.slideDown() – jQuery API

jQuery API

Skip to content
  • api

.slideDown()

Categories: Effects > Sliding

.slideDown( [ duration ], [ callback ] ) Returns: jQuery

Description: Display the matched elements with a sliding motion.

  • version added: 1.0.slideDown( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

The .slideDown() method animates the height of the matched elements. This causes lower parts of the page to slide down, making way for the revealed items.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />

With the element initially hidden, we can show it slowly:

$('#clickme').click(function() {
  $('#book').slideDown('slow', function() {
    // Animation complete.
  });
});

Examples:

Example: Animates all divs to slide down and show themselves over 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
div { background:#de9a44; margin:3px; width:80px;
height:40px; display:none; float:left; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Click me!
<div></div>
<div></div>
<div></div>
<script>
$(document.body).click(function () {
if ($("div:first").is(":hidden")) {
$("div").slideDown("slow");
} else {
$("div").hide();
}
});

</script>
</body>
</html>

Demo:

Example: Animates all inputs to slide down, completing the animation within 1000 milliseconds. Once the animation is done, the input look is changed especially if it is the middle input which gets the focus.

<!DOCTYPE html>
<html>
<head>
  <style>
div { background:#cfd; margin:3px; width:50px;
text-align:center; float:left; cursor:pointer;
border:2px outset black; font-weight:bolder; }
input { display:none; width:120px; float:left;
margin:10px; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>Push!</div>
<input type="text" />
<input type="text" class="middle" />

<input type="text" />
<script>
$("div").click(function () {
$(this).css({ borderStyle:"inset", cursor:"wait" });
$("input").slideDown(1000,function(){
$(this).css("border", "2px red inset")
.filter(".middle")
 .css("background", "yellow")
 .focus();
$("div").css("visibility", "hidden");
});
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .slideDown().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.slideToggle() – jQuery API

jQuery API

Skip to content
  • api

.slideToggle()

Categories: Effects > Sliding

.slideToggle( [ duration ], [ callback ] ) Returns: jQuery

Description: Display or hide the matched elements with a sliding motion.

  • version added: 1.0.slideToggle( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

The .slideToggle() method animates the height of the matched elements. This causes lower parts of the page to slide up or down, appearing to reveal or conceal the items. If the element is initially displayed, it will be hidden; if hidden, it will be shown. The display property is saved and restored as needed. If an element has a display value of inline, then is hidden and shown, it will once again be displayed inline. When the height reaches 0 after a hiding animation, the display style property is set to none to ensure that the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />

We will cause .slideToggle() to be called when another element is clicked:

$('#clickme').click(function() {
  $('#book').slideToggle('slow', function() {
    // Animation complete.
  });
});

With the element initially shown, we can hide it slowly with the first click:

A second click will show the element once again:

Examples:

Example: Animates all paragraphs to slide up or down, completing the animation within 600 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { width:400px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Toggle</button>

  <p>
    This is the paragraph to end all paragraphs.  You
    should feel <em>lucky</em> to have seen such a paragraph in
    your life.  Congratulations!
  </p>
<script>
    $("button").click(function () {
      $("p").slideToggle("slow");
    });
</script>
</body>
</html>

Demo:

Example: Animates divs between dividers with a toggle that makes some appear and some disappear.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { background:#b977d1; margin:3px; width:60px;
        height:60px; float:left; }
  div.still { background:#345; width:5px; }
  div.hider { display:none; }
  span { color:red; }
  p { clear: left; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
<div class="still"></div>
<div style="display:none;">
</div><div class="still"></div>
<div></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div></div>
<p><button id="aa">Toggle</button> There have been <span>0</span> toggled divs.</p>
<script>
  $("#aa").click(function () {
    $("div:not(.still)").slideToggle("slow", function () {
      var n = parseInt($("span").text(), 10);
      $("span").text(n + 1);
    });
  });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .slideToggle().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.slideUp() – jQuery API

jQuery API

Skip to content
  • api

.slideUp()

Categories: Effects > Sliding

.slideUp( [ duration ], [ callback ] ) Returns: jQuery

Description: Hide the matched elements with a sliding motion.

  • version added: 1.0.slideUp( [ duration ], [ callback ] )

    durationA string or number determining how long the animation will run.

    callbackA function to call once the animation is complete.

The .slideUp() method animates the height of the matched elements. This causes lower parts of the page to slide up, appearing to conceal the items. Once the height reaches 0, the display style property is set to none to ensure that the element no longer affects the layout of the page.

Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings 'fast' and 'slow' can be supplied to indicate durations of 200 and 600 milliseconds, respectively. If any other string is supplied, or if the duration parameter is omitted, the default duration of 400 milliseconds is used.

If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but this is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.

We can animate any element, such as a simple image:

<div id="clickme">
  Click here
</div>
<img id="book" src="book.png" alt="" width="100" height="123" />

With the element initially shown, we can hide it slowly:

$('#clickme').click(function() {
  $('#book').slideUp('slow', function() {
    // Animation complete.
  });
});

Examples:

Example: Animates all divs to slide up, completing the animation within 400 milliseconds.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { background:#3d9a44; margin:3px; width:80px;
    height:40px; float:left; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Click me!
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <div></div>
<script>
  $(document.body).click(function () {
    if ($("div:first").is(":hidden")) {
      $("div").show("slow");
    } else {
      $("div").slideUp();
    }
  });

  </script>
</body>
</html>

Demo:

Example: Animates the parent paragraph to slide up, completing the animation within 200 milliseconds. Once the animation is done, it displays an alert.

<!DOCTYPE html>
<html>
<head>
  <style>
 div { margin:2px; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
  <button>Hide One</button>
  <input type="text" value="One" />

</div>
<div>
  <button>Hide Two</button>
  <input type="text" value="Two" />

</div>
<div>
  <button>Hide Three</button>
  <input type="text" value="Three" />

</div>
<div id="msg"></div>
<script>
  $("button").click(function () {
    $(this).parent().slideUp("slow", function () {
      $("#msg").text($("button", this).text() + " has completed.");
    });
  });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .slideUp().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Events – jQuery API

jQuery API

Skip to content
  • api

Events

These methods are used to register behaviors to take effect when the user interacts with the browser, and to further manipulate those registered behaviors.

  • .bind()

    Event Handler Attachment

    Attach a handler to an event for the elements.

  • .blur()

    Form Events, Forms

    Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.

  • .change()

    Form Events, Forms

    Bind an event handler to the "change" JavaScript event, or trigger that event on an element.

  • .click()

    Mouse Events

    Bind an event handler to the "click" JavaScript event, or trigger that event on an element.

  • .dblclick()

    Mouse Events

    Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.

  • .die()

    Event Handler Attachment

    Remove an event handler previously attached using .live() from the elements.

  • .error()

    Browser Events

    Bind an event handler to the "error" JavaScript event.

  • event.currentTarget

    Event Object

    The current DOM element within the event bubbling phase.

  • event.data

    Event Object

    Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound.

  • event.isDefaultPrevented()

    Event Object

    Returns whether event.preventDefault() was ever called on this event object.

  • event.isImmediatePropagationStopped()

    Event Object

    Returns whether event.stopImmediatePropagation() was ever called on this event object.

  • event.isPropagationStopped()

    Event Object

    Returns whether event.stopPropagation() was ever called on this event object.

  • event.pageX

    Event Object

    The mouse position relative to the left edge of the document.

  • event.pageY

    Event Object

    The mouse position relative to the top edge of the document.

  • event.preventDefault

    Event Object

    If this method is called, the default action of the event will not be triggered.

  • event.relatedTarget

    Event Object

    The other DOM element involved in the event, if any.

  • event.result

    Event Object

    This attribute contains the last value returned by an event handler that was triggered by this event, unless the value was undefined.

  • event.stopImmediatePropagation()

    Event Object

    Prevents other event handlers from being called.

  • event.stopPropagation()

    Event Object

    This method prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.

  • event.target

    Event Object

    The DOM element that initiated the event.

  • event.timeStamp

    Event Object

    This attribute returns the number of milliseconds since January 1, 1970, when the event is triggered.

  • event.type

    Event Object

    Describes the nature of the event.

  • event.which

    Event Object

    For key or button events, this attribute indicates the specific button or key that was pressed.

  • .focus()

    Form Events, Forms

    Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.

  • .focusin()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusin" JavaScript event.

  • .focusin()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusin" JavaScript event.

  • .focusout()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusout" JavaScript event.

  • .focusout()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusout" JavaScript event.

  • .hover()

    Mouse Events

    Bind two handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.

  • .keydown()

    Keyboard Events

    Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.

  • .keypress()

    Keyboard Events

    Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.

  • .keyup()

    Keyboard Events

    Bind an event handler to the "keyup" JavaScript event, or trigger that event on an element.

  • .live()

    Event Handler Attachment

    Attach a handler to the event for all elements which match the current selector, now or in the future.

  • .load()

    Document Loading

    Bind an event handler to the "load" JavaScript event.

  • .mousedown()

    Mouse Events

    Bind an event handler to the "mousedown" JavaScript event, or trigger that event on an element.

  • .mouseenter()

    Mouse Events

    Bind an event handler to be fired when the mouse enters an element, or trigger that handler on an element.

  • .mouseleave()

    Mouse Events

    Bind an event handler to be fired when the mouse leaves an element, or trigger that handler on an element.

  • .mousemove()

    Mouse Events

    Bind an event handler to the "mousemove" JavaScript event, or trigger that event on an element.

  • .mouseout()

    Mouse Events

    Bind an event handler to the "mouseout" JavaScript event, or trigger that event on an element.

  • .mouseover()

    Mouse Events

    Bind an event handler to the "mouseover" JavaScript event, or trigger that event on an element.

  • .mouseup()

    Mouse Events

    Bind an event handler to the "mouseup" JavaScript event, or trigger that event on an element.

  • .one()

    Event Handler Attachment

    Attach a handler to an event for the elements. The handler is executed at most once.

  • jQuery.proxy()

    Event Handler Attachment, Utilities

    Takes a function and returns a new one that will always have a particular scope.

  • .ready()

    Document Loading

    Specify a function to execute when the DOM is fully loaded.

  • .resize()

    Browser Events

    Bind an event handler to the "resize" JavaScript event, or trigger that event on an element.

  • .scroll()

    Browser Events

    Bind an event handler to the "scroll" JavaScript event, or trigger that event on an element.

  • .select()

    Form Events, Forms

    Bind an event handler to the "select" JavaScript event, or trigger that event on an element.

  • .submit()

    Form Events, Forms

    Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

  • .toggle()

    Basics, Mouse Events

    Bind two or more handlers to the matched elements, to be executed on alternate clicks.

  • .trigger()

    Event Handler Attachment

    Execute all handlers and behaviors attached to the matched elements for the given event type.

  • .triggerHandler()

    Event Handler Attachment

    Execute all handlers attached to an element for an event.

  • .unbind()

    Event Handler Attachment

    Remove a previously-attached event handler from the elements.

  • .unload()

    Document Loading

    Bind an event handler to the "unload" JavaScript event.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Browser Events – jQuery API

jQuery API

Skip to content
  • api

Browser Events

  • .error()

    Bind an event handler to the "error" JavaScript event.

  • .resize()

    Bind an event handler to the "resize" JavaScript event, or trigger that event on an element.

  • .scroll()

    Bind an event handler to the "scroll" JavaScript event, or trigger that event on an element.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.error() – jQuery API

jQuery API

Skip to content
  • api

.error()

Categories: Events > Browser Events

.error( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "error" JavaScript event.

  • version added: 1.0.error( handler(eventObject) )

    handler(eventObject)A function to execute when the event is triggered.

This method is a shortcut for .bind('error', handler).

The error event is sent to elements, such as images, that are referenced by a document and loaded by the browser. It is called if the element was not loaded correctly.

For example, consider a page with a simple image:

<img src="missing.png" alt="Book" id="book" />

The event handler can be bound to the image:

$('#book').error(function() {
  alert('Handler for .error() called.')
});

If the image cannot be loaded (for example, because it is not present at the supplied URL), the alert is displayed:

Handler for .error() called.

This event may not be correctly fired when the page is served locally. Since error relies on normal HTTP status codes, it will generally not be triggered if the URL uses the file: protocol.

Examples:

Example: To keep a server-side log of JavaScript errors, you might want to:

$(window).error(function(msg, url, line){
  jQuery.post("js_error_log.php", { msg: msg, url: url, line: line });
});

Example: To hide JavaScript errors from the user, you can try:

$(window).error(function(){
  return true;
});

Example: To hide the "broken image" icons for your IE users, you can try:

$("img").error(function(){
  $(this).hide();
});

Comments

  • Please keep comments relevant to .error().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.resize() – jQuery API

jQuery API

Skip to content
  • api

.resize()

Categories: Events > Browser Events

.resize( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "resize" JavaScript event, or trigger that event on an element.

  • version added: 1.0.resize( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.resize()

This method is a shortcut for .bind('resize', handler) in the first variation, and .trigger('resize') in the second.

The resize event is sent to the window element when the size of the browser window changes:

$(window).resize(function() {
  $('#log').append('<div>Handler for .resize() called.</div>');
});

Now whenever the browser window's size is changed, the message is appended to <div id="log"> one or more times, depending on the browser.

Code in a resize handler should never rely on the number of times the handler is called. Depending on implementation, resize events can be sent continuously as the resizing is in progress (the typical behavior in Internet Explorer and WebKit-based browsers such as Safari and Chrome), or only once at the end of the resize operation (the typical behavior in Firefox).

Example:

To see the window width while (or after) it is resized , try:

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="window-width"><p>Window Width:</p></div>

<script>var $window = $(window), $div = $('#window-width');
  $window.resize(function(){
    $div.append('<div>' + $window.width() + '</div>');
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .resize().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.scroll() – jQuery API

jQuery API

Skip to content
  • api

.scroll()

Categories: Events > Browser Events

.scroll( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "scroll" JavaScript event, or trigger that event on an element.

  • version added: 1.0.scroll( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.scroll()

This method is a shortcut for .bind('scroll', handler) in the first variation, and .trigger('scroll') in the second.

The scroll event is sent to an element when the user scrolls to a different place in the element. It applies to window objects, but also to scrollable frames and elements with the overflow CSS property set to scroll (or auto when the element's explicit height is less than the height of its contents).

For example, consider the HTML:

<div id="target" style="overflow: scroll; width: 200px; height: 100px;">
  Lorem ipsum dolor sit amet, consectetur adipisicing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna
  aliqua. Ut enim ad minim veniam, quis nostrud exercitation
  ullamco laboris nisi ut aliquip ex ea commodo consequat.
  Duis aute irure dolor in reprehenderit in voluptate velit
  esse cillum dolore eu fugiat nulla pariatur. Excepteur
  sint occaecat cupidatat non proident, sunt in culpa qui
  officia deserunt mollit anim id est laborum.
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The style definition is present to make the target element small enough to be scrollable:

The scroll event handler can be bound to this element:

$('#target').scroll(function() {
  $('#log').append('<div>Handler for .scroll() called.</div>');
});

Now when the user scrolls the text up or down, one or more messages are appended to <div id="log"></div>:

Handler for .scroll() called.

We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').scroll();
});

After this code executes, clicks on Trigger the handler will also append the message.

A scroll event is sent whenever the element's scroll position changes, regardless of the cause. A mouse click or drag on the scroll bar, dragging inside the element, pressing the arrow keys, or using the mouse's scroll wheel could cause this event.

Example:

To do something when your page is scrolled:

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  p { color:green; }
  span { color:red; display:none; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>Try scrolling the iframe.</div>
  <p>Paragraph - <span>Scroll happened!</span></p>
<script>
    $("p").clone().appendTo(document.body);
    $("p").clone().appendTo(document.body);
    $("p").clone().appendTo(document.body);
    $(window).scroll(function () {
      $("span").css("display", "inline").fadeOut("slow");
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .scroll().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Document Loading – jQuery API

jQuery API

Skip to content
  • api

Document Loading

  • .load()

    Bind an event handler to the "load" JavaScript event.

  • .ready()

    Specify a function to execute when the DOM is fully loaded.

  • .unload()

    Bind an event handler to the "unload" JavaScript event.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.load() – jQuery API

jQuery API

Skip to content
  • api

.load()

Categories: Events > Document Loading

.load( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "load" JavaScript event.

  • version added: 1.0.load( handler(eventObject) )

    handler(eventObject)A function to execute when the event is triggered.

This method is a shortcut for .bind('load', handler).

The load event is sent to an element when it and all sub-elements have been completely loaded. This event can be sent to any element associated with a URL: images, scripts, frames, iframes, and the body of the document itself.

It is possible that the load event will not be triggered if the image is loaded from the browser cache. To account for this possibility, we can test the value of the image's .complete property.

For example, consider a page with a simple image:

<img src="book.png" alt="Book" id="book" />

The event handler can be bound to the image:

$('#book').load(function() {
  // Handler for .load() called.
});

As soon as the image has been loaded, the handler is called.

In general, it is not necessary to wait for all images to be fully loaded. If code can be executed earlier, it is usually best to place it in a handler sent to the .ready() method.

The Ajax module also has a method named .load(). Which one is fired depends on the set of arguments passed.

Examples:

Example: Run a function when the page is fully loaded including graphics.

$(window).load(function () {
  // run code
});

Example: Add the class bigImg to all images with height greater then 100 upon each image load.

$('img.userIcon').load(function(){
  if($(this).height() > 100) {
    $(this).addClass('bigImg');
  }
});

Comments

  • Please keep comments relevant to .load().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Vladimir Kuznetsov
    Is it enough to just check the property «complete» to make sure that the image is loaded? Some times ago I read that Gecko-based browsers require to check the properties «naturalWidth» or «naturalHeight». They will be exactly equal to zero for not loaded yet images.
  • egilli
    Also works fine with iframes;

    $('iframe').load(function() {
    var iframeId = $(this).attr("id");
    var iframeHeight = $(this).contents().find("body").height();
    $(this).height(iframeHeight);
    });

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.ready() – jQuery API

jQuery API

Skip to content
  • api

.ready()

Categories: Events > Document Loading

.ready( handler ) Returns: jQuery

Description: Specify a function to execute when the DOM is fully loaded.

  • version added: 1.0.ready( handler )

    handlerA function to execute after the DOM is ready.

While JavaScript provides the load event for executing code when a page is rendered, this event does not get triggered until all assets such as images have been completely received. In most cases, the script can be run as soon as the DOM hierarchy has been fully constructed. The handler passed to .ready() is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other event handlers and run other jQuery code. When using scripts that rely on the value of CSS style properties, it's important to reference external stylesheets or embed style elements before referencing the scripts.

In cases where code relies on loaded assets (for example, if the dimensions of an image are required), the code should be placed in a handler for the load event instead.

The .ready() method is generally incompatible with the <body onload=""> attribute. If load must be used, either do not use .ready() or use jQuery's .load() method to attach load event handlers to the window or to more specific items, like images.

All three of the following syntaxes are equivalent:

  • $(document).ready(handler)
  • $().ready(handler) (this is not recommended)
  • $(handler)

The .ready() method can only be called on a jQuery object matching the current document, so the selector can be omitted.

The .ready() method is typically used with an anonymous function:

$(document).ready(function() {
  // Handler for .ready() called.
});

If .ready() is called after the DOM has been initialized, the new handler passed in will be executed immediately.

Aliasing the jQuery Namespace

When using another JavaScript library, we may wish to call $.noConflict() to avoid namespace difficulties. When this function is called, the $ shortcut is no longer available, forcing us to write jQuery each time we would normally write $. However, the handler passed to the .ready() method can take an argument, which is passed the global jQuery object. This means we can rename the object within the context of our .ready() handler without affecting other code:

jQuery(document).ready(function($) {
  // Code using $ as usual goes here.
});

Example:

Display a message when the DOM is loaded.

<!DOCTYPE html>
<html>
<head>
  <style>p { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
  <script>
  $(document).ready(function () {
  $("p").text("The DOM is now loaded and can be manipulated.");
});
  </script>

</head>
<body>
    <p>Not loaded yet.</p>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .ready().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.unload() – jQuery API

jQuery API

Skip to content
  • api

.unload()

Categories: Events > Document Loading

.unload( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "unload" JavaScript event.

  • version added: 1.0.unload( handler(eventObject) )

    handler(eventObject)A function to execute when the event is triggered.

This method is a shortcut for .bind('unload', handler).

The unload event is sent to the window element when the user navigates away from the page. This could mean one of many things. The user could have clicked on a link to leave the page, or typed in a new URL in the address bar. The forward and back buttons will trigger the event. Closing the browser window will cause the event to be triggered. Even a page reload will first create an unload event.

The exact handling of the unload event has varied from version to version of browsers. For example, some versions of Firefox trigger the event when a link is followed, but not when the window is closed. In practical usage, behavior should be tested on all supported browsers, and contrasted with the proprietary beforeunload event.

Any unload event handler should be bound to the window object:

$(window).unload(function() {
  alert('Handler for .unload() called.');
});

After this code executes, the alert will be displayed whenever the browser leaves the current page. It is not possible to cancel the unload event with .preventDefault(). This event is available so that scripts can perform cleanup when the user leaves the page.

Example:

To display an alert when a page is unloaded:

$(window).unload( function () { alert("Bye now!"); } );

Comments

  • Please keep comments relevant to .unload().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • bluemanta
    Is it necessary to add the beforeUnload() in jQuery?
    Or if there is something could instead it yet? thank you.
  • Lukas Renggli
    The description seems to be missing here.
  • Karl Swedberg
    thanks. fixed.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Event Handler Attachment – jQuery API

jQuery API

Skip to content
  • api

Event Handler Attachment

  • .bind()

    Attach a handler to an event for the elements.

  • .die()

    Remove an event handler previously attached using .live() from the elements.

  • .live()

    Attach a handler to the event for all elements which match the current selector, now or in the future.

  • .one()

    Attach a handler to an event for the elements. The handler is executed at most once.

  • jQuery.proxy()

    Utilities

    Takes a function and returns a new one that will always have a particular scope.

  • .trigger()

    Execute all handlers and behaviors attached to the matched elements for the given event type.

  • .triggerHandler()

    Execute all handlers attached to an element for an event.

  • .unbind()

    Remove a previously-attached event handler from the elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.bind() – jQuery API

jQuery API

Skip to content
  • api

.bind()

Categories: Events > Event Handler Attachment

.bind( eventType, [ eventData ], handler(eventObject) ) Returns: jQuery

Description: Attach a handler to an event for the elements.

  • version added: 1.0.bind( eventType, [ eventData ], handler(eventObject) )

    eventTypeA string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.

    eventDataA map of data that will be passed to the event handler.

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.4.bind( events )

    eventsA map of one or more JavaScript event types and functions to execute for them.

The .bind() method is the primary means of attaching behavior to a document. All JavaScript event types, such as focus, mouseover, and resize, are allowed for eventType.

The jQuery library provides shortcut methods for binding the standard event types, such as .click() for .bind('click'). A description of each can be found in the discussion of its shortcut method: blur, focus, focusin, focusout, load, resize, scroll, unload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error

Any string is legal for eventType; if the string is not the name of a native JavaScript event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using .trigger() or .triggerHandler().

If the eventType string contains a period (.) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call .bind('click.name', handler), the string click is the event type, and the string name is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of .unbind() for more information.

When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.

A basic usage of .bind() is:

$('#foo').bind('click', function() {
  alert('User clicked on "foo."');
});

This code will cause the element with an ID of foo to respond to the click event. When a user clicks inside this element thereafter, the alert will be shown.

Multiple Events

Multiple event types can be bound at once by including each one separated by a space:

$('#foo').bind('mouseenter mouseleave', function() {
  $(this).toggleClass('entered');
});

The effect of this on <div id="foo"> (when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <div> and remove the class when the mouse leaves.

As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing a map of event type/handler pairs:

$('#foo').bind({
  click: function() {
    // do something on click
  },
  mouseenter: function() {
    // do something on mouseenter
  }
});

Event Handlers

The handler parameter takes a callback function, as shown above. Within the handler, the keyword this refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal $() function. For example:

$('#foo').bind('click', function() {
  alert($(this).text());
});

After this code is executed, when the user clicks inside the element with an ID of foo, its text contents will be shown as an alert.

The Event object

The handler callback function can also take parameters. When the function is called, the JavaScript event object will be passed to the first parameter.

The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. View the full Event Object.

Returning false from a handler is equivalent to calling both .preventDefault() and .stopPropagation() on the event object.

Using the event object in a handler looks like this:

$(document).ready(function() {
  $('#foo').bind('click', function(event) {
    alert('The mouse cursor is at ('
      + event.pageX + ', ' + event.pageY + ')');
  });
});

Note the parameter added to the anonymous function. This code will cause a click on the element with ID foo to report the page coordinates of the mouse cursor at the time of the click.

Passing Event Data

The optional eventData parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that both refer to the same external variable:

var message = 'Spoon!';
$('#foo').bind('click', function() {
  alert(message);
});
message = 'Not in the face!';
$('#bar').bind('click', function() {
  alert(message);
});

Because the handlers are closures that both have message in their environment, both will display the message Not in the face! when triggered. The variable's value has changed. To sidestep this, we can pass the message in using eventData:

var message = 'Spoon!';
$('#foo').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});
message = 'Not in the face!';
$('#bar').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});

This time the variable is not referred to directly within the handlers; instead, the variable is passed in by value through eventData, which fixes the value at the time the event is bound. The first handler will now display Spoon! while the second will alert Not in the face!

Note that objects are passed to functions by reference, which further complicates this scenario.

If eventData is present, it is the second argument to the .bind() method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.

See the .trigger() method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.

As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.

Examples:

Example: Handle click and double-click for the paragraph. Note: the coordinates are window relative, so in this case relative to the demo iframe.

<!DOCTYPE html>
<html>
<head>
  <style>
p { background:yellow; font-weight:bold; cursor:pointer;
padding:5px; }
p.over { background: #ccc; }
span { color:red; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Click or double click here.</p>
<span></span>
<script>
$("p").bind("click", function(event){
var str = "( " + event.pageX + ", " + event.pageY + " )";
$("span").text("Click happened! " + str);
});
$("p").bind("dblclick", function(){
$("span").text("Double-click happened in " + this.nodeName);
});
$("p").bind("mouseenter mouseleave", function(event){
$(this).toggleClass("over");
});

</script>
</body>
</html>

Demo:

Example: To display each paragraph's text in an alert box whenever it is clicked:

$("p").bind("click", function(){
alert( $(this).text() );
});

Example: You can pass some extra data before the event handler:

function handler(event) {
alert(event.data.foo);
}
$("p").bind("click", {foo: "bar"}, handler)

Example: To cancel a default action and prevent it from bubbling up, return false:

$("form").bind("submit", function() { return false; })

Example: To cancel only the default action by using the preventDefault method.

$("form").bind("submit", function(event) {
event.preventDefault();
});

Example: Stop only an event from bubbling by using the stopPropagation method.

$("form").bind("submit", function(event) {
if( event.stopPropagation ) { event.stopPropagation(); } //For 'Good' browsers
else { event.cancelBubble = true; } //For IE
});

Example: Can bind custom events too.

<!DOCTYPE html>
<html>
<head>
  <style>
p { color:red; }
span { color:blue; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Has an attached custom event.</p>
<button>Trigger custom event</button>
<span style="display:none;"></span>
<script>

$("p").bind("myCustomEvent", function(e, myName, myValue){
$(this).text(myName + ", hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent", [ "John" ]);
});

</script>
</body>
</html>

Demo:

Example: Bind multiple events simultaneously.

$("div.test").bind({
  click: function(){
    $(this).addClass("active");
  },
  mouseenter: function(){
    $(this).addClass("inside");
  },
  mouseleave: function(){
    $(this).removeClass("inside");
  }
});

Comments

  • Please keep comments relevant to .bind().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Tyron
    Is there any way to pass event data when using the "bind multiple events simultaneously" syntax?
  • Raj
    Hi there..
    Iv got myself into a mess trying to bind events to dynamically created elements
    Im using flyDOM plugin to add divs with a particular class
    i want to bind a click event to those divs
    ..
    yes as you can assume i tried binding it when its created..
    Baaad idea ..

    Is there any way this can be done ??
  • Andir
    Check out .live(). I think that's what you're looking for.

    http://api.jquery.com/live/
  • Andir
    May be a dumb request, but would it be (or is it) possible to assign multiple events at once?
    $(obj).bind("change, click", evtFunction);
  • Karl Swedberg
    Not a dumb request at all! It just wasn't very well documented. I added a couple paragraphs above to show how that works.
  • Niels R.
    You made a small typo (missing a single quote) in the second code example of that piece of text: $('#foo).bind
  • Karl Swedberg
    thanks. fixed.
  • Darrell Estabrook
    I can never remember the eventTypes. From the old jQuery documentation on bind(), possible event values are:

    blur, focus, load, resize, scroll, unload, beforeunload, click, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, error, ready
  • Karl Swedberg
    Yes, that should be added to the description above. Thanks for noting it in the meantime.
    [edit]: Added!
  • Prestaul
    They've also added a way to specify "scope" (this is what they are calling the executing context for the callback) as an optional fourth argument. For example:

    $('#doStuff').bind('click', that.handleDoStuff, that);

    will execute handleDoStuff with "this" assigned to "that" rather than #doStuff.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.die() – jQuery API

jQuery API

Skip to content
  • api

.die()

Categories: Events > Event Handler Attachment

.die( eventType, [ handler ] ) Returns: jQuery

Description: Remove an event handler previously attached using .live() from the elements.

  • version added: 1.3.die( eventType, [ handler ] )

    eventTypeA string containing a JavaScript event type, such as click or keydown.

    handlerThe function that is to be no longer executed.

Any handler that has been attached with .live() can be removed with .die(). This method is analogous to .unbind(), which is used to remove handlers attached with .bind(). See the discussions of .live() and .unbind() for further details.

Examples:

Example: Can bind and unbind events to the colored button.

<!DOCTYPE html>
<html>
<head>
  <style>
button { margin:5px; }
button#theone { color:red; background:yellow; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="theone">Does nothing...</button>
<button id="bind">Bind Click</button>
<button id="unbind">Unbind Click</button>

<div style="display:none;">Click!</div>
<script>

function aClick() {
  $("div").show().fadeOut("slow");
}
$("#bind").click(function () {
  $("#theone").live("click", aClick)
              .text("Can Click!");
});
$("#unbind").click(function () {
  $("#theone").die("click", aClick)
              .text("Does nothing...");
});

</script>
</body>
</html>

Demo:

Example: To unbind all live events from all paragraphs, write:

$("p").die()

Example: To unbind all live click events from all paragraphs, write:

$("p").die( "click" )

Example: To unbind just one previously bound handler, pass the function in as the second argument:

var foo = function () {
// code to handle some kind of event
};

$("p").live("click", foo); // ... now foo will be called when paragraphs are clicked ...

$("p").die("click", foo); // ... foo will no longer be called.

Comments

  • Please keep comments relevant to .die().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.live() – jQuery API

jQuery API

Skip to content
  • api

.live()

Categories: Events > Event Handler Attachment

.live( eventType, handler ) Returns: jQuery

Description: Attach a handler to the event for all elements which match the current selector, now or in the future.

  • version added: 1.3.live( eventType, handler )

    eventTypeA string containing a JavaScript event type, such as "click" or "keydown"

    handlerA function to execute at the time the event is triggered.

  • version added: 1.4.live( eventType, [ eventData ], handler )

    eventTypeA string containing a JavaScript event type, such as "click" or "keydown"

    eventDataA map of data that will be passed to the event handler.

    handlerA function to execute at the time the event is triggered.

This method is a variation on the basic .bind() method for attaching event handlers to elements. When .bind() is called, the elements that the jQuery object refers to get the handler attached; elements that get introduced later do not, so they would require another .bind() call. For instance, consider the HTML:

<body>
  <div class="clickme">
    Click here
  </div>
</body>

We can bind a simple click handler to this element:

$('.clickme').bind('click', function() {
  // Bound handler called.
});

When the element is clicked, then the message gets printed. However, suppose that after this, another element is added:

$('body').append('<div class="clickme">Another target</div>');

This new element also matches the selector .clickme, but since it was added after the call to .bind(), clicks on it will do nothing.

The .live() method provides an alternative to this behavior. If we bind a click handler to the target element using this method:

$('.clickme').live('click', function() {
  // Live handler called.
});

And then later add a new element:

$('body').append('<div class="clickme">Another target</div>');

Then clicks on the new element will also trigger the handler.

Event Delegation

The .live() method is able to affect elements that have not yet been added to the DOM through the use of event delegation: a handler bound to an ancestor element is responsible for events that are triggered on its descendants. The handler passed to .live() is never bound to an element; instead, .live() binds a special handler to the root of the DOM tree. In our example, when the new element is clicked, the following steps occur:

  1. A click event is generated and passed to the <div> for handling.
  2. No handler is directly bound to the <div>, so the event bubbles up the DOM tree.
  3. The event bubbles up until it reaches the root of the tree, which is where .live() binds its special handlers by default.
  4. The special click handler bound by .live() executes.
  5. This handler tests the target of the event object to see whether it should continue. This test is performed by checking if $(event.target).closest('.clickme') is able to locate a matching element.
  6. If a matching element is found, the original handler is called on it.

Because the test in step 5 is not performed until the event occurs, elements can be added at any time and still respond to events.

Caveats

The .live() technique is useful, but due to its special approach cannot be simply substituted for .bind() in all cases. Specific differences include:

  • As of jQuery 1.4, the .live() method supports custom events as well as all JavaScript events. Two exceptions: Since focus and blur aren't actually bubbling events, we need to use focusin and focusout instead. In version 1.3.x, however, only the following JavaScript events (in addition to custom events) could be bound with .live(): click, dblclick, keydown, keypress, keyup, mousedown, mousemove, mouseout, mouseover, and mouseup.
  • DOM traversal methods are not fully supported for finding elements to send to .live(). Rather, the .live() method should always be called directly after a selector, as in the example above.
  • To stop further handlers from executing after one bound using .live(), the handler must return false. Calling .stopPropagation() will not accomplish this.

    • See the discussion for .bind() for more information on event binding.

    As of jQuery 1.4, the optional eventData parameter allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. See the .bind() method's "Passing Event Data" discussion for more information.

    Examples:

    Example: Click a paragraph to add another. Note that live binds the click event to all paragraphs - even new ones.

    <!DOCTYPE html>
<html>
<head>
  <style>
  p { background:yellow; font-weight:bold; cursor:pointer;
      padding:5px; }
  p.over { background: #ccc; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Click me!</p>

  <span></span>
<script>
    $("p").live("click", function(){
      $(this).after("<p>Another paragraph!</p>");
    });
</script>
</body>
</html>

    Demo:

    Example: To display each paragraph's text in an alert box whenever it is clicked:

    $("p").live("click", function(){
  alert( $(this).text() );
});

    Example: To cancel a default action and prevent it from bubbling up, return false:

    $("a").live("click", function() { return false; })

    Example: To cancel only the default action by using the preventDefault method.

    $("a").live("click", function(event){
  event.preventDefault();
});

    Example: Can bind custom events too.

    <!DOCTYPE html>
<html>
<head>
  <style>
  p { color:red; }
  span { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Has an attached custom event.</p>
  <button>Trigger custom event</button>
  <span style="display:none;"></span>
<script>

    $("p").live("myCustomEvent", function(e, myName, myValue){
      $(this).text("Hi there!");
      $("span").stop().css("opacity", 1)
               .text("myName = " + myName)
               .fadeIn(30).fadeOut(1000);
    });
    $("button").click(function () {
      $("p").trigger("myCustomEvent");
    });

</script>
</body>
</html>

    Demo:

    Comments

    • Please keep comments relevant to .live().
    • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
    • Please report bugs on the bug tracker or the jQuery Forum.
    • Request support on the jQuery Forum
    • rasmuslknabe
      I can't get "change" to work in IE8 either!? - The documentation clearly states that it's supported as far as i can se though...
    • Rasmus L. Knabe
      Sorry.. ment "change" using live()...
    • Guu
      Does this version support namespaced events like .live'click.name', fn) as bind() function does?
    • Gunnar Lium
      Is live('change', function().... supposed to work in Internet Explorer? According http://jquery14.com/day-01/jquery-14 it sould be supported. I can not get the following simple test to work (it works fine in Opera and Firefox):

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
      <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
      <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
      <title>Test</title>
      </head>
      <body>
      <script type="text/javascript">
      jQuery(document).ready(function($) {
      $('#demo').live('change', function() {
      alert('test');
      });
      });
      </script>
      <h1>jQuery-testing</h1>
      <input type="text" id="demo" />
      </body>
      </html>
    • Matias Larsson
      I'm also having trouble getting "change" to work in IE8. Works great in Fx, Cr and Safari.

      I'll create a ticket and post to jquery-dev if I can't find one.

      Update: It's already on jquery-dev http://groups.google.com/group/jquery-dev/brows...

      Update2: Added Trac ticket: http://dev.jquery.com/ticket/5851
    • Hadrian
      In 1.4 you can pass an object of many events to bind(). Why didn't live() get the same feature?
    • Thom Patterson
      Can someone please explain how to add context to live events? It was mentioned in the release notes: http://jquery14.com/day-01/jquery-14

      "live/die now work with context"

      I have a project that would currently suffers from a performance bottlenexk
    • Tim Molendijk
      It's tricky and undocumented, but the context of a jQuery object needs to be supplied as a DOM element. Only then the context will be different from the default (document):

      $('li', $('ul').get(0)).live('click', ...);
      - or -
      $li = $('li');
      $li.context = $('ul').get(0);
      $li.live('click', ...);
    • Thom Patterson
      Sorry, accidentally posted too soon.

      I have a project that is currently experiencing performance problems with live events at the document level. By moving them down to a closer ancestor of my dynamic content I expect performance would improve.
    • bigredswitch
      what about selector driven live events, as in the semi-eponymous livequery

      that is:
      $('.foo').live(function(){
      // do something
      })

    jQuery API

      • New or Changed in 1.4
      • Raw XML API Dump
      • Dynamic API Browser
      • jQuery API Book

    Browse the jQuery API

      • All
      • Ajax
        • Global Ajax Event Handlers
        • Helper Functions
        • Low-Level Interface
        • Shorthand Methods
      • Attributes
      • Core
      • CSS
      • Data
      • Dimensions
      • Effects
        • Basics
        • Custom
        • Fading
        • Sliding
      • Events
        • Browser Events
        • Document Loading
        • Event Handler Attachment
        • Event Object
        • Form Events
        • Keyboard Events
        • Mouse Events
      • Forms
      • Manipulation
        • Class Attribute
        • Copying
        • DOM Insertion
        • DOM Insertion, Around
        • DOM Insertion, Inside
        • DOM Insertion, Outside
        • DOM Removal
        • DOM Replacement
        • General Attributes
        • Style Properties
      • Miscellaneous
        • Collection Manipulation
        • Data Storage
        • DOM Element Methods
        • Setup Methods
      • Offset
      • Plugin Authoring
      • Properties
        • Properties of jQuery Object Instances
        • Properties of the Global jQuery Object
      • Selectors
        • Attribute
        • Basic
        • Basic Filter
        • Child Filter
        • Content Filter
        • Form
        • Hierarchy
        • Visibility Filter
      • Traversing
        • Filtering
        • Miscellaneous Traversing
        • Tree Traversal
      • Utilities


.one() – jQuery API

jQuery API

Skip to content
  • api

.one()

Categories: Events > Event Handler Attachment

.one( eventType, [ eventData ], handler(eventObject) ) Returns: jQuery

Description: Attach a handler to an event for the elements. The handler is executed at most once.

  • version added: 1.1.one( eventType, [ eventData ], handler(eventObject) )

    eventTypeA string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.

    eventDataA map of data that will be passed to the event handler.

    handler(eventObject)A function to execute at the time the event is triggered.

This method is identical to .bind(), except that the handler is unbound after its first invocation. For example:

$('#foo').one('click', function() {
  alert('This will be displayed only once.');
});

After the code is executed, a click on the element with ID foo will display the alert. Subsequent clicks will do nothing. This code is equivalent to:

$('#foo').bind('click', function(event) {
  alert('This will be displayed only once.');
  $(this).unbind(event);
});

In other words, explicitly calling .unbind() from within a regularly-bound handler has exactly the same effect.

Examples:

Example: Tie a one-time click to each div.

<!DOCTYPE html>
<html>
<head>
  <style>
div { width:60px; height:60px; margin:5px; float:left;
background:green; border:10px outset;
cursor:pointer; }
p { color:red; margin:0; clear:left; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
<div></div>
<div></div>
<div></div>

<div></div>
<p>Click a green square...</p>
<script>
var n = 0;
$("div").one("click", function(){
var index = $("div").index(this);
$(this).css({ borderStyle:"inset",
    cursor:"auto" });
$("p").text("Div at index #" + index + " clicked." +
  "  That's " + ++n + " total clicks.");
});

</script>
</body>
</html>

Demo:

Example: To display the text of all paragraphs in an alert box the first time each of them is clicked:

$("p").one("click", function(){
alert( $(this).text() );
});

Comments

  • Please keep comments relevant to .one().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.proxy() – jQuery API

jQuery API

Skip to content
  • api

jQuery.proxy()

Categories: Events > Event Handler Attachment | Utilities

jQuery.proxy( function, scope ) Returns: Function

Description: Takes a function and returns a new one that will always have a particular scope.

  • version added: 1.4jQuery.proxy( function, scope )

    functionThe function whose scope will be changed.

    scopeThe object to which the scope of the function should be set.

  • version added: 1.4jQuery.proxy( scope, name )

    scopeThe object to which the scope of the function should be set.

    nameThe name of the function whose scope will be changed (should be a property of the 'scope' object.

This method is most useful for attaching event handlers to an element where the scope is pointing back to a different object. Additionally, jQuery makes sure that even if you bind the function returned from jQuery.proxy() it will still unbind the correct function, if passed the original.

Example:

Enforce the scope of the function.

var obj = {
  name: "John",
  test: function() {
    alert( this.name );
    $("#test").unbind("click", obj.test);
  }
};

$("#test").click( jQuery.proxy( obj, "test" ) );

// This also works:
// $("#test").click( jQuery.proxy( obj.test, obj ) );

Comments

  • Please keep comments relevant to jQuery.proxy().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • David
    How about adding arguments like this:

    proxy = function( fn, scope ) {
    return function() {
    return fn.apply( ( scope || window ), Array.prototype.slice.call( arguments ) );
    };
    },
  • dvjh
    var obj = {
    name: "John",
    test: function(e, param1, param2){
    console.log("obj arguments.length = " + arguments.length);
    console.log(param1 + " " + this.name + " !" + "\n" + param2);
    console.log("e.target = " + e.target);
    console.log("e.currentTarget = " + e.currentTarget);
    }
    };

    $("#affiche").click(function(e){
    $.proxy(obj.test(e, "Hello", "jQuery is the Number One !"),obj);
    });
  • Prestaul
    Your event handlers will be called with the same arguments that they've always been called with. All that .proxy() gives you is the ability to set the execution context (the "this") of those callbacks. To get the element that triggered the event you'll use event.currentTarget.

    function Foo() {
    $('button').click($.proxy(this.handleClick, this));
    }
    Foo.prototype = {
    handleClick: function(event) {
    assert(this instanceof Foo); // true
    assert(event.currentTarget.is('button')); // true
    }
    };
  • kkaefer
    I think the word "scope" isn't the correct way of describing what this function does. "Scope" usually refers to the entirety of all variables the current function has access to (in the case of lexical scoping that JavaScript uses, this includes -- simplified -- all identifiers that were defined before/above the current line of code. What this function actually does is to change `this`, also known as the context.
  • azoff
    ditto. that's why I call it "context" in my plugin :)
  • azoff
    In case anyone is interested, I added the ability to pass extra arguments (currying) to jQuery.proxy by means of an extension. You can grab the file here (production | development) and read more about it here. The function signature is exactly the same but I overloaded it to accept any arguments (less the first two) as the arguments to pass to the bound function.
  • dvjh
    $(function(){
    var obj = {
    name: "John",
    test: function(param1, param2){
    alert(param1 + " " + this.name + " ! \n" + param2);
    $("#affiche").unbind("click", obj.test);
    }
    };

    $("#affiche").click($.proxy(obj.test("hello", "jQuery is the best js library in the world"), obj));

    /*
    * with Firebug console.log($.proxy(obj.test, obj)) is
    * function(){
    * return a.apply(d || this, arguments);
    * }
    */
    });
  • Guest
    $ ( '. result'). load ( 'http://jquery.com/'); how we can use here? Can I use!
  • William K
    This should be extended so you can also pass in extra arguments to the function (which will get appended to the existing arguments)
  • Celtric
    Something like $("#test").click( jQuery.proxy( obj, "test", [arg1, arg2, ...] ) ); being equivalent to obj.test(arg1, arg2, ...);

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.trigger() – jQuery API

jQuery API

Skip to content
  • api

.trigger()

Categories: Events > Event Handler Attachment

.trigger( eventType, extraParameters ) Returns: jQuery

Description: Execute all handlers and behaviors attached to the matched elements for the given event type.

  • version added: 1.0.trigger( eventType, extraParameters )

    eventTypeA string containing a JavaScript event type, such as click or submit.

    extraParametersAn array of additional parameters to pass along to the event handler.

Any event handlers attached with .bind() or one of its shortcut methods are triggered when the corresponding event occurs. They can be fired manually, however, with the .trigger() method. A call to .trigger() executes the handlers in the same order they would be if the event were triggered naturally by the user:

$('#foo').bind('click', function() {
      alert($(this).text());
    });
    $('#foo').trigger('click');

While .trigger() simulates an event activation, complete with a synthesized event object, it does not perfectly replicate a naturally-occurring event.

When we define a custom event type using the .bind() method, the second argument to .trigger() can become useful. For example, suppose we have bound a handler for the custom event to our element instead of the built-in click event as we did above:

$('#foo').bind('custom', function(event, param1, param2) {
  alert(param1 + "\n" + param2);
});
$('#foo').trigger('custom', ['Custom', 'Event']);

The event object is always passed as the first parameter to an event handler, but if additional parameters are specified during a .trigger() call as they are here, these parameters will be passed along to the handler as well.

Note the difference between the extra parameters we're passing here and the eventData parameter to the .bind() method. Both are mechanisms for passing information to an event handler, but the extraParameters argument to .trigger() allows information to be determined at the time the event is triggered, while the eventData argument to .bind() requires the information to be already computed at the time the handler is bound.

Examples:

Example: Clicks to button #2 also trigger a click for button #1.

<!DOCTYPE html>
<html>
<head>
  <style>

button { margin:10px; }
div { color:blue; font-weight:bold; }
span { color:red; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Button #1</button>
<button>Button #2</button>
<div><span>0</span> button #1 clicks.</div>

<div><span>0</span> button #2 clicks.</div>
<script>
$("button:first").click(function () {
update($("span:first"));
});
$("button:last").click(function () {
$("button:first").trigger('click');

update($("span:last"));
});

function update(j) {
var n = parseInt(j.text(), 10);
j.text(n + 1);
}
</script>
</body>
</html>

Demo:

Example: To submit the first form without using the submit() function, try:

$("form:first").trigger("submit")

Example: To submit the first form without using the submit() function, try:

var event = jQuery.Event("submit");
$("form:first").trigger(event);
if ( event.isDefaultPrevented() ) {
// Perform an action...
}

Example: To pass arbitrary data to an event:

$("p").click( function (event, a, b) {
// when a normal click fires, a and b are undefined
// for a trigger like below a refers to "foo" and b refers to "bar"

} ).trigger("click", ["foo", "bar"]);

Example: To pass arbitrary data through an event object:

var event = jQuery.Event("logged");
event.user = "foo";
event.pass = "bar";
$("body").trigger(event);

Example: Alternate way to pass data through an event object:

$("body").trigger({
type:"logged",
user:"foo",
pass:"bar"

});

Comments

  • Please keep comments relevant to .trigger().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.triggerHandler() – jQuery API

jQuery API

Skip to content
  • api

.triggerHandler()

Categories: Events > Event Handler Attachment

.triggerHandler( eventType, extraParameters ) Returns: Object

Description: Execute all handlers attached to an element for an event.

  • version added: 1.2.triggerHandler( eventType, extraParameters )

    eventTypeA string containing a JavaScript event type, such as click or submit.

    extraParametersAn array of additional parameters to pass along to the event handler.

The .triggerHandler() method behaves similarly to .trigger(), with the following exceptions:

  • The .triggerHandler() method does not cause the default behavior of an event to occur (such as a form submission).
  • While .trigger() will operate on all elements matched by the jQuery object, .triggerHandler() only affects the first matched element.
  • Events created with .triggerHandler() do not bubble up the DOM hierarchy; if they are not handled by the target element directly, they do nothing.
  • Instead of returning the jQuery object (to allow chaining), .triggerHandler() returns whatever value was returned by the last handler it caused to be executed. If no handlers are triggered, it returns undefined

For more information on this method, see the discussion for .trigger().

Example:

If you called .triggerHandler() on a focus event - the browser's default focus action would not be triggered, only the event handlers bound to the focus event.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="old">.trigger("focus")</button>
<button id="new">.triggerHandler("focus")</button><br/><br/>

<input type="text" value="To Be Focused"/>
<script>

$("#old").click(function(){
$("input").trigger("focus");
});
$("#new").click(function(){
$("input").triggerHandler("focus");
});
$("input").focus(function(){
$("<span>Focused!</span>").appendTo("body").fadeOut(1000);
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .triggerHandler().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.unbind() – jQuery API

jQuery API

Skip to content
  • api

.unbind()

Categories: Events > Event Handler Attachment

.unbind( eventType, handler(eventObject) ) Returns: jQuery

Description: Remove a previously-attached event handler from the elements.

  • version added: 1.0.unbind( eventType, handler(eventObject) )

    eventTypeA string containing a JavaScript event type, such as click or submit.

    handler(eventObject)The function that is to be no longer executed.

  • version added: 1.0.unbind( event )

    eventA JavaScript event object as passed to an event handler.

Any handler that has been attached with .bind() can be removed with .unbind(). In the simplest case, with no arguments, .unbind() removes all handlers attached to the elements:

$('#foo').unbind();

This version removes the handlers regardless of type. To be more precise, we can pass an event type:

$('#foo').unbind('click');

By specifying the click event type, only handlers for that event type will be unbound. This approach can still have negative ramifications if other scripts might be attaching behaviors to the same element, however. Robust and extensible applications typically demand the two-argument version for this reason:

var handler = function() {
  alert('The quick brown fox jumps over the lazy dog.');
};
$('#foo').bind('click', handler);
$('#foo').unbind('click', handler);

By naming the handler, we can be assured that no other functions are caught in the crossfire. Note that the following will not work:

$('#foo').bind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});

$('#foo').unbind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});

Even though the two functions are identical in content, they are created separately and so JavaScript is free to keep them as distinct function objects. To unbind a particular handler, we need a reference to that function and not a different one that happens to do the same thing.

Using Namespaces

Instead of maintaining references to handlers in order to unbind them, we can namespace the events and use this capability to narrow the scope of our unbinding actions. As shown in the discussion for the .bind() method, namespaces are defined by using a period (.) character when binding a handler:

$('#foo').bind('click.myEvents', handler);

When a handler is bound in this fashion, we can still unbind it the normal way:

$('#foo').unbind('click');

However, if we want to avoid affecting other handlers, we can be more specific:

$('#foo').unbind('click.myEvents');

If multiple namespaced handlers are bound, we can unbind them at once:

$('#foo').unbind('click.myEvents.yourEvents');

This syntax is similar to that used for CSS class selectors; they are not hierarchical. This method call is thus the same as:

$('#foo').unbind('click.yourEvents.myEvents');

We can also unbind all of the handlers in a namespace, regardless of event type:

$('#foo').unbind('.myEvents');

It is particularly useful to attach namespaces to event bindings when we are developing plug-ins or otherwise writing code that may interact with other event-handling code in the future.

Using the Event Object

The second form of the .unbind() method is used when we wish to unbind a handler from within itself. For example, suppose we wish to trigger an event handler only three times:

var timesClicked = 0;
$('#foo').bind('click', function(event) {
  alert('The quick brown fox jumps over the lazy dog.');
  timesClicked++;
  if (timesClicked >= 3) {
    $(this).unbind(event);
  }
});

The handler in this case must take a parameter, so that we can capture the event object and use it to unbind the handler after the third click. The event object contains the context necessary for .unbind() to know which handler to remove. This example is also an illustration of a closure. Since the handler refers to the timesClicked variable, which is defined outside the function, incrementing the variable has an effect even between invocations of the handler.

Examples:

Example: Can bind and unbind events to the colored button.

<!DOCTYPE html>
<html>
<head>
  <style>
button { margin:5px; }
button#theone { color:red; background:yellow; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="theone">Does nothing...</button>
<button id="bind">Bind Click</button>
<button id="unbind">Unbind Click</button>

<div style="display:none;">Click!</div>
<script>

function aClick() {
$("div").show().fadeOut("slow");
}
$("#bind").click(function () {
// could use .bind('click', aClick) instead but for variety...
$("#theone").click(aClick)
  .text("Can Click!");
});
$("#unbind").click(function () {
$("#theone").unbind('click', aClick)
  .text("Does nothing...");
});

</script>
</body>
</html>

Demo:

Example: To unbind all events from all paragraphs, write:

$("p").unbind()

Example: To unbind all click events from all paragraphs, write:

$("p").unbind( "click" )

Example: To unbind just one previously bound handler, pass the function in as the second argument:

var foo = function () {
// code to handle some kind of event
};

$("p").bind("click", foo); // ... now foo will be called when paragraphs are clicked ...

$("p").unbind("click", foo); // ... foo will no longer be called.

Comments

  • Please keep comments relevant to .unbind().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Aivo Paas
    It would also be useful to have .unbind(events) where events is a map of event names and functions. Just like .bind(events) in 1.4
  • bigredswitch
    you know what would be awesome? .rebind() ... esp for namespaced events

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Event Object – jQuery API

jQuery API

Skip to content
  • api

Event Object

jQuery’s event system normalizes the event object according to W3C standards. The event object is guaranteed to be passed to the event handler. Most properties from the original event are copied over and normalized to the new event object.

The jQuery.Event constructor is exposed and can be used when calling trigger. You don’t need to use the ”new” operator, it is optional.

Check trigger’s documentation to see how to combine it with your own event object.

Example:

Create a new jQuery.Event object without the ”new” operator.

var e = jQuery.Event("click");

Create a new jQuery.Event object with the ”new” operator (optional).

var e = new jQuery.Event("click");

  • event.currentTarget

    The current DOM element within the event bubbling phase.

  • event.data

    Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound.

  • event.isDefaultPrevented()

    Returns whether event.preventDefault() was ever called on this event object.

  • event.isImmediatePropagationStopped()

    Returns whether event.stopImmediatePropagation() was ever called on this event object.

  • event.isPropagationStopped()

    Returns whether event.stopPropagation() was ever called on this event object.

  • event.pageX

    The mouse position relative to the left edge of the document.

  • event.pageY

    The mouse position relative to the top edge of the document.

  • event.preventDefault

    If this method is called, the default action of the event will not be triggered.

  • event.relatedTarget

    The other DOM element involved in the event, if any.

  • event.result

    This attribute contains the last value returned by an event handler that was triggered by this event, unless the value was undefined.

  • event.stopImmediatePropagation()

    Prevents other event handlers from being called.

  • event.stopPropagation()

    This method prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.

  • event.target

    The DOM element that initiated the event.

  • event.timeStamp

    This attribute returns the number of milliseconds since January 1, 1970, when the event is triggered.

  • event.type

    Describes the nature of the event.

  • event.which

    For key or button events, this attribute indicates the specific button or key that was pressed.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.currentTarget – jQuery API

jQuery API

Skip to content
  • api

event.currentTarget

Categories: Events > Event Object

event.currentTarget Returns: Element

Description: The current DOM element within the event bubbling phase.

  • version added: 1.3event.currentTarget

This property will always be equal to the this of the function.

Example:

Alert that currentTarget matches the `this` keyword.

$("p").click(function(event) {
  alert( event.currentTarget === this ); // true
});

Comments

  • Please keep comments relevant to event.currentTarget.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.data – jQuery API

jQuery API

Skip to content
  • api

event.data

Categories: Events > Event Object

event.data Returns: Anything

Description: Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound.

  • version added: 1.1event.data

Example:

The description of the example.

$("a").each(function(i) {
  $(this).bind('click', {index:i}, function(e){
     alert('my index is ' + e.data.index);
  });
});

Comments

  • Please keep comments relevant to event.data.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.isDefaultPrevented() – jQuery API

jQuery API

Skip to content
  • api

event.isDefaultPrevented()

Categories: Events > Event Object

event.isDefaultPrevented() Returns: Boolean

Description: Returns whether event.preventDefault() was ever called on this event object.

  • version added: 1.3event.isDefaultPrevented()

Example:

Checks whether event.preventDefault() was called.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>$("a").click(function(event){
  alert( event.isDefaultPrevented() ); // false
  event.preventDefault();
  alert( event.isDefaultPrevented() ); // true
});  </script>
</body>
</html>

Demo:

Result:

Comments

  • Please keep comments relevant to event.isDefaultPrevented().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.isImmediatePropagationStopped() – jQuery API

jQuery API

Skip to content
  • api

event.isImmediatePropagationStopped()

Categories: Events > Event Object

event.isImmediatePropagationStopped() Returns: Boolean

Description: Returns whether event.stopImmediatePropagation() was ever called on this event object.

  • version added: 1.3event.isImmediatePropagationStopped()

This property was introduced in DOM level 3.

Example:

Checks whether event.stopImmediatePropagation() was called.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>$("p").click(function(event){
  alert( event.isImmediatePropagationStopped() );
  event.stopImmediatePropagation();
  alert( event.isImmediatePropagationStopped() );
});  </script>
</body>
</html>

Demo:

Result:

Comments

  • Please keep comments relevant to event.isImmediatePropagationStopped().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.isPropagationStopped() – jQuery API

jQuery API

Skip to content
  • api

event.isPropagationStopped()

Categories: Events > Event Object

event.isPropagationStopped() Returns: Boolean

Description: Returns whether event.stopPropagation() was ever called on this event object.

  • version added: 1.3event.isPropagationStopped()

Example:

Checks whether event.stopPropagation() was called

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>$("p").click(function(event){
  alert( event.isPropagationStopped() );
  event.stopPropagation();
  alert( event.isPropagationStopped() );
});  </script>
</body>
</html>

Demo:

Result:

Comments

  • Please keep comments relevant to event.isPropagationStopped().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.pageX – jQuery API

jQuery API

Skip to content
  • api

event.pageX

Categories: Events > Event Object

event.pageX Returns: Number

Description: The mouse position relative to the left edge of the document.

  • version added: 1.0.4event.pageX

Example:

Show the mouse position relative to the left and top edges of the document (within the iframe).

<!DOCTYPE html>
<html>
<head>
  <style>body {background-color: #eef; }
div { padding: 20px; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="log"></div>
<script>$(document).bind('mousemove',function(e){
            $("#log").text("e.pageX: " + e.pageX + ", e.pageY: " + e.pageY);
}); </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to event.pageX.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.pageY – jQuery API

jQuery API

Skip to content
  • api

event.pageY

Categories: Events > Event Object

event.pageY Returns: Number

Description: The mouse position relative to the top edge of the document.

  • version added: 1.0.4event.pageY

Example:

Show the mouse position relative to the left and top edges of the document (within this iframe).

<!DOCTYPE html>
<html>
<head>
  <style>body {background-color: #eef; }
div { padding: 20px; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="log"></div>
<script>$(document).bind('mousemove',function(e){
            $("#log").text("e.pageX: " + e.pageX + ", e.pageY: " + e.pageY);
}); </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to event.pageY.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.preventDefault – jQuery API

jQuery API

Skip to content
  • api

event.preventDefault

Categories: Events > Event Object

event.preventDefault() Returns: undefined

Description: If this method is called, the default action of the event will not be triggered.

  • version added: 1.0event.preventDefault()

For example, clicked anchors will not take the browser to a new URL. We can use event.isDefaultPrevented() to determine if this method has been called by an event handler that was triggered by this event.

Example:

Cancel the default action (navigation) of the click.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <a href="http://jquery.com">default click action is prevented</a>
<script>$("a").click(function(event){
  event.preventDefault();
  // do something
});  </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to event.preventDefault.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • cactuspants
    The API listing page (http://api.jquery.com/) shows this method as `event.preventDefault` rather than `event.preventDefault()` like other methods.
  • Karl Swedberg
    thanks. fixed.
  • Castles
    demo missing an "a" tag
  • Karl Swedberg
    Thanks for the report. It's in there now.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.relatedTarget – jQuery API

jQuery API

Skip to content
  • api

event.relatedTarget

Categories: Events > Event Object

event.relatedTarget Returns: Element

Description: The other DOM element involved in the event, if any.

  • version added: 1.1.4event.relatedTarget

For mouseout, indicates the element being entered; for mousein, indicates the element being exited.

Example:

On mouseout of anchors, alert the element type being entered.

$("a").mouseout(function(event) {
  alert(event.relatedTarget.nodeName); // "DIV"
});

Comments

  • Please keep comments relevant to event.relatedTarget.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.result – jQuery API

jQuery API

Skip to content
  • api

event.result

Categories: Events > Event Object

event.result Returns: Object

Description: This attribute contains the last value returned by an event handler that was triggered by this event, unless the value was undefined.

  • version added: 1.3event.result

Example:

Alert previous handler's return value

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>$("p").click(function(event) {
  return "hey"
});
$("p").click(function(event) {
  alert( event.result );
});  </script>
</body>
</html>

Demo:

Result:

"hey"

Comments

  • Please keep comments relevant to event.result.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.stopImmediatePropagation() – jQuery API

jQuery API

Skip to content
  • api

event.stopImmediatePropagation()

Categories: Events > Event Object

event.stopImmediatePropagation()

Description: Keeps the rest of the handlers from being executed.

  • version added: 1.3event.stopImmediatePropagation()

This method also stops the bubbling by implicitly calling event.stopPropagation(). Use event.isImmediatePropagationStopped() to know whether this method was ever called (on that event object).

Example:

Prevents other event handlers from being called.

<!DOCTYPE html>
<html>
<head>
  <style>
p { height: 30px; width: 150px; background-color: #ccf; }
div {height: 30px; width: 150px; background-color: #cfc; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>paragraph</p>
<div>division</div>
<script>
$("p").click(function(event){
  event.stopImmediatePropagation();
});
$("p").click(function(event){
  // This function won't be executed
  $(this).css("background-color", "#f00");
});
$("div").click(function(event) {
  // This function will be executed
    $(this).css("background-color", "#f00");
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to event.stopImmediatePropagation().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • juli
    how to take away stopImmediatePropagation

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.stopPropagation() – jQuery API

jQuery API

Skip to content
  • api

event.stopPropagation()

Categories: Events > Event Object

event.stopPropagation()

Description: This method prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.

  • version added: 1.0event.stopPropagation()

We can use .isPropagationStopped() to determine if this method has been called by an event handler that was triggered by this event.

This method works for custom events triggered with trigger(), as well.

Note that this will not prevent other handlers on the same element from running. Use the method event.isPropagationStopped() to know whether this method was ever called (on that event object).

Example:

Kill the bubbling on the click event.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>$("p").click(function(event){
  event.stopPropagation();
  // do something
});  </script>
</body>
</html>

Demo:

Result:

Comments

  • Please keep comments relevant to event.stopPropagation().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.target – jQuery API

jQuery API

Skip to content
  • api

event.target

Categories: Events > Event Object

event.target Returns: Element

Description: The DOM element that initiated the event.

  • version added: 1.0event.target

This can be the element that registered for the event or a child of it. It is often useful to compare event.target to this in order to determine if the event is being handled due to event bubbling. This property is very useful in event delegation, when events bubble.

Examples:

Example: Display the tag's name on click

<!DOCTYPE html>
<html>
<head>
  <style>
span, strong, p {
  padding: 8px; display: block; border: 1px solid #999;  }
    </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div id="log"></div>
<div>
  <p>
    <strong><span>click</span></strong>
  </p>
</div>
<script>$("body").click(function(event) {
  $("#log").html("clicked: " + event.target.nodeName);
});  </script>
</body>
</html>

Demo:

Example: Implements a simple event delegation: The click handler is added to an unordered list, and the children of its li children are hidden. Clicking one of the li children toggles (see toggle()) their children.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<ul>
  <li>item 1
    <ul>
      <li>sub item 1-a</li>
      <li>sub item 1-b</li>
    </ul>
  </li>
  <li>item 2
    <ul>
      <li>sub item 2-a</li>
      <li>sub item 2-b</li>
    </ul>
  </li>
</ul>
<script>function handler(event) {
  var $target = $(event.target);
  if( $target.is("li") ) {
    $target.children().toggle();
  }
}
$("ul").click(handler).find("ul > li").hide();</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to event.target.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.timeStamp – jQuery API

jQuery API

Skip to content
  • api

event.timeStamp

Categories: Events > Event Object

event.timeStamp Returns: Number

Description: This attribute returns the number of milliseconds since January 1, 1970, when the event is triggered.

  • version added: 1.2.6event.timeStamp

Example:

Alert the time since click handler last executed.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<script>var last;
$(document.body).click(function(event) {
   if( last )
      alert( "time since last event " + event.timeStamp - last );
   last = event.timeStamp;
});  </script>
</body>
</html>

Demo:

Result:

Comments

  • Please keep comments relevant to event.timeStamp.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • juli
    how it works

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.type – jQuery API

jQuery API

Skip to content
  • api

event.type

Categories: Events > Event Object

event.type Returns: String

Description: Describes the nature of the event.

  • version added: 1.0event.type

Example:

On all anchor clicks, alert the event type.

$("a").click(function(event) {
  alert(event.type); // "click"
});

Comments

  • Please keep comments relevant to event.type.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


event.which – jQuery API

jQuery API

Skip to content
  • api

event.which

Categories: Events > Event Object

event.which Returns: String

Description: For key or button events, this attribute indicates the specific button or key that was pressed.

  • version added: 1.1.3event.which

event.which normalizes event.keyCode and event.charCode. It is recommended to watch event.which for keyboard key input. For more detail, read about event.charCode on the MDC.

Example:

Log what key was depressed.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<input id="whichkey" value="type something">
<div id="log"></div>
<script>$('#whichkey').bind('keydown',function(e){
  $('#log').html(e.type + ': ' +  e.which );
});  </script>
</body>
</html>

Demo:

Result:

"keydown" 74

Comments

  • Please keep comments relevant to event.which.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Form Events – jQuery API

jQuery API

Skip to content
  • api

Form Events

  • .blur()

    Forms

    Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.

  • .change()

    Forms

    Bind an event handler to the "change" JavaScript event, or trigger that event on an element.

  • .focus()

    Forms

    Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.

  • .select()

    Forms

    Bind an event handler to the "select" JavaScript event, or trigger that event on an element.

  • .submit()

    Forms

    Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.blur() – jQuery API

jQuery API

Skip to content
  • api

.blur()

Categories: Events > Form Events | Forms

.blur( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.

  • version added: 1.0.blur( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.blur()

This method is a shortcut for .bind('blur', handler) in the first variation, and .trigger('blur') in the second.

The blur event is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as <input>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Field 1" />
  <input type="text" value="Field 2" />
</form>
<div id="other">
  Trigger the handler
</div>
The event handler can be bound to the first input field:
$('#target').blur(function() {
  alert('Handler for .blur() called.');
});

Now if the first field has the focus and we click elsewhere, or tab away from it, the alert is displayed:

Handler for .blur() called.

We can trigger the event when another element is clicked:

$('#other').click(function() {
  $('#target').blur();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The blur event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the blur event will not work consistently across browsers.

Example:

To trigger the blur event on all paragraphs:

$("p").blur();

Comments

  • Please keep comments relevant to .blur().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.change() – jQuery API

jQuery API

Skip to content
  • api

.change()

Categories: Events > Form Events | Forms

.change( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "change" JavaScript event, or trigger that event on an element.

  • version added: 1.0.change( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.change()

This method is a shortcut for .bind('change', handler) in the first variation, and .trigger('change') in the second.

The change event is sent to an element when its value changes. This event is limited to <input type="text"> fields, <textarea> boxes and <select> elements. For select boxes, the event is fired immediately when the user makes a selection with the mouse, but for the other element types the event is deferred until the element loses focus.

For example, consider the HTML:

<form>
  <input class="target" type="text" value="Field 1" />
  <select class="target">
    <option value="option1" selected="selected">Option 1</option>
    <option value="option2">Option 2</option>
  </select>
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the text input and the select box:

$('.target').change(function() {
  alert('Handler for .change() called.');
});

Now when the second option is selected from the dropdown, the alert is displayed. It is also displayed if we change the text in the field and then click away. If the field loses focus without the contents having changed, though, the event is not triggered. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('.target').change();
});

After this code executes, clicks on Trigger the handler will also alert the message. The message will be displayed twice, because the handler has been bound to the change event on both of the form elements.

As of jQuery 1.4 the change event now bubbles, and works identically to all other browsers, in Internet Explorer.

Examples:

Example: Attaches a change event to the select that gets the text for each selected option and writes them in the div. It then triggers the event for the initial text draw.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <select name="sweets" multiple="multiple">
    <option>Chocolate</option>
    <option selected="selected">Candy</option>

    <option>Taffy</option>
    <option selected="selected">Caramel</option>
    <option>Fudge</option>
    <option>Cookie</option>

  </select>
  <div></div>
<script>
    $("select").change(function () {
          var str = "";
          $("select option:selected").each(function () {
                str += $(this).text() + " ";
              });
          $("div").text(str);
        })
        .change();
</script>
</body>
</html>

Demo:

Example: To add a validity test to all text input elements:

$("input[type='text']").change( function() {
  // check input ($(this).val()) for validity here
});

Comments

  • Please keep comments relevant to .change().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Kane
    In IE there has an problem, if had default selected in select, it will fire change before mouse select the option。

    <select name="" id="test">
    <option value="1">1</option>
    <option value="2" selected="selected">2</option>
    <option value="3">3</option>
    </select>

    <select name="" id="test2">
    <option value="1">1</option>
    <option value="2">2</option>
    <option value="3">3</option>
    </select>

    <script type="text/javascript">
    $(function(){
    $("#test,#test2").change(function(){
    alert($(this).val());
    })
    })
    </script>
  • pwc1011
    Seems like this would eliminate the need for a plugin like dirtyForm?

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.focus() – jQuery API

jQuery API

Skip to content
  • api

.focus()

Categories: Events > Form Events | Forms

.focus( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.

  • version added: 1.0.focus( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.focus()

  • This method is a shortcut for .bind('focus', handler) in the first variation, and .trigger('focus') in the second.
  • The focus event is sent to an element when it gains focus. This event is implicitly applicable to a limited set of elements, such as form elements (<input>, <select>, etc.) and links (<a href>). In recent browser versions, the event can be extended to include all element types by explicitly setting the element's tabindex property. An element can gain focus via keyboard commands, such as the Tab key, or by mouse clicks on the element.
  • Elements with focus are usually highlighted in some way by the browser, for example with a dotted line surrounding the element. The focus is used to determine which element is the first to receive keyboard-related events.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Field 1" />
  <input type="text" value="Field 2" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the first input field:

$('#target').focus(function() {
  alert('Handler for .focus() called.');
});

Now if we click on the first field, or tab to it from another field, the alert is displayed:

Handler for .focus() called.

We can trigger the event when another element is clicked:

$('#other').click(function() {
  $('#target').focus();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The focus event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the focus event will not work consistently across browsers.

Triggering the focus on hidden elements causes an error in Internet Explorer. Take care to only call .focus() without parameters on elements that are visible.

Examples:

Example: Fire focus.

<!DOCTYPE html>
<html>
<head>
  <style>span {display:none;}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><input type="text" /> <span>focus fire</span></p>

<p><input type="password" /> <span>focus fire</span></p>
<script>
    $("input").focus(function () {
         $(this).next("span").css('display','inline').fadeOut(1000);
    });
</script>
</body>
</html>

Demo:

Example: To stop people from writing in text input boxes, try:

$("input[type=text]").focus(function(){
  $(this).blur();
});

Example: To focus on a login input box with id 'login' on page startup, try:

$(document).ready(function(){
  $("#login").focus();
});

Comments

  • Please keep comments relevant to .focus().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.select() – jQuery API

jQuery API

Skip to content
  • api

.select()

Categories: Events > Form Events | Forms

.select( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "select" JavaScript event, or trigger that event on an element.

  • version added: 1.0.select( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.select()

This method is a shortcut for .bind('select', handler) in the first variation, and .trigger('select') in the second.

The select event is sent to an element when the user makes a text selection inside it. This event is limited to <input type="text"> fields and <textarea> boxes.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the text input:

$('#target').select(function() {
  alert('Handler for .select() called.');
});

Now when any portion of the text is selected, the alert is displayed. Merely setting the location of the insertion point will not trigger the event. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').select();
});

After this code executes, clicks on the Trigger button will also alert the message:

Handler for .select() called.

In addition, the default select action on the field will be fired, so the entire text field will be selected.

The method for retrieving the current selected text differs from one browser to another. A number of jQuery plug-ins offer cross-platform solutions.

Examples:

Example: To do something when text in input boxes is selected:

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; }
  div { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>

    Click and drag the mouse to select text in the inputs.
  </p>
  <input type="text" value="Some text" />
  <input type="text" value="to test on" />

  <div></div>
<script>
    $(":input").select( function () {
      $("div").text("Something was selected").show().fadeOut(1000);
    });
</script>
</body>
</html>

Demo:

Example: To trigger the select event on all input elements, try:

$("input").select();

Comments

  • Please keep comments relevant to .select().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.submit() – jQuery API

jQuery API

Skip to content
  • api

.submit()

Categories: Events > Form Events | Forms

.submit( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

  • version added: 1.0.submit( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.submit()

This method is a shortcut for .bind('submit', handler) in the first variation, and .trigger('submit') in the second.

The submit event is sent to an element when the user is attempting to submit a form. It can only be attached to <form> elements. Forms can be submitted either by clicking an explicit <input type="submit">, <input type="image">, or <button type="submit">, or by pressing Enter when certain form element has focus.

Depending on the browser, the Enter key may only cause a form submission if the form has exactly one text field, or only when there is a submit button present. The interface should not rely on a particular behavior for this key unless the issue is forced by observing the keypress event for presses of the Enter key.

For example, consider the HTML:

<form id="target" action="destination.html">
  <input type="text" value="Hello there" />
  <input type="submit" value="Go" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the form:

$('#target').submit(function() {
  alert('Handler for .submit() called.');
  return false;
});

Now when the form is submitted, the message is alerted. This happens prior to the actual submission, so we can cancel the submit action by calling .preventDefault() on the event object or by returning false from our handler. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').submit();
});

After this code executes, clicks on Trigger the handler will also display the message. In addition, the default submit action on the form will be fired, so the form will be submitted.

The JavaScript submit event does not bubble in Internet Explorer. However, scripts that rely on event delegation with the submit event will work consistently across browsers as of jQuery 1.4, which has normalized the event's behavior.

Examples:

Example: If you'd like to prevent forms from being submitted unless a flag variable is set, try:

<!DOCTYPE html>
<html>
<head>
  <style>

  p { margin:0; color:blue; }
  div,p { margin-left:10px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Type 'correct' to validate.</p>
  <form action="javascript:alert('success!');">
    <div>
      <input type="text" />

      <input type="submit" />
    </div>
  </form>
  <span></span>
<script>

    $("form").submit(function() {
      if ($("input:first").val() == "correct") {
        $("span").text("Validated...").show();
        return true;
      }
      $("span").text("Not valid!").show().fadeOut(1000);
      return false;
    });
</script>
</body>
</html>

Demo:

Example: If you'd like to prevent forms from being submitted unless a flag variable is set, try:

$("form").submit( function () {
  return this.some_flag_variable;
} );

Example: To trigger the submit event on the first form on the page, try:

$("form:first").submit();

Comments

  • Please keep comments relevant to .submit().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Keyboard Events – jQuery API

jQuery API

Skip to content
  • api

Keyboard Events

  • .focusin()

    Mouse Events

    Bind an event handler to the "focusin" JavaScript event.

  • .focusout()

    Mouse Events

    Bind an event handler to the "focusout" JavaScript event.

  • .keydown()

    Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.

  • .keypress()

    Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.

  • .keyup()

    Bind an event handler to the "keyup" JavaScript event, or trigger that event on an element.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.focusin() – jQuery API

jQuery API

Skip to content
  • api

.focusin()

Categories: Events > Keyboard Events | Events > Mouse Events

.focusin( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "focusin" JavaScript event.

  • version added: 1.4.focusin( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

This method is a shortcut for .bind('focusin', handler).

The focusin event is sent to an element when it, or any element inside of it, gains focus. This is distinct from the focus event in that it supports detecting the focus event on parent elements.

This event will likely be used together with the focusout event.

Example:

Watch for a focus to occur within the paragraphs on the page.

<!DOCTYPE html>
<html>
<head>
  <style>span {display:none;}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><input type="text" /> <span>focusin fire</span></p>
<p><input type="password" /> <span>focusin fire</span></p>
<script>
    $("p").focusin(function() {
         $(this).find("span").css('display','inline').fadeOut(1000);
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .focusin().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • chinese
    i see it .

    Mozilla/5.0 (Windows; U; Windows NT 5.1; zh-CN; rv:1.9.1.7) Gecko/20091221 Firefox/3.5.7
  • Karl Swedberg
    Thanks, all. Fixed the problems: wasn't pointing to a new enough jQuery 1.4 and should have been $(this).find("span") rather than $(this).next("span").
  • kalle17
    Maybe it should be
    $(this).next("span").css('display','inline').fadeIn(1000);
    cuz all spans here are invisible due to css rule?
  • carlo
    The example don't work with Opera 10.10
  • Seth
    Not seeing anything happen when I focus on either form element.
  • Francois-Guillaume Ribreau
    I got the same problem. (Firefox 3.5.7 Mac)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.focusout() – jQuery API

jQuery API

Skip to content
  • api

.focusout()

Categories: Events > Keyboard Events | Events > Mouse Events

.focusout( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "focusout" JavaScript event.

  • version added: 1.4.focusout( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

This method is a shortcut for .bind('focusout', handler).

The focusout event is sent to an element when it, or any element inside of it, loses focus. This is distinct from the blur event in that it supports detecting the loss of focus from parent elements (in other words, it supports events bubbling).

This event will likely be used together with the focusin event.

Example:

Watch for a loss of focus to occur within the paragraphs on the page.

<!DOCTYPE html>
<html>
<head>
  <style>span {display:none;}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><input type="text" /> <span>focusout fire</span></p>
<p><input type="password" /> <span>focusout fire</span></p>
<script>
$("p").focusout(function() {
  $(this).find("span").css('display','inline').fadeOut(1000);
});
    </script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .focusout().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Gustavo Guichard
    But what's the difference between focusout() and blur()?
  • azoff
    focusout() and focusin() support event bubbling, focus() and blur() do not. Also, focusin() and focusout() are supported by jQuery.live()
  • BMCouto
    I'm not understanding the difference between focusin()/focusout() and focus()/blur(). What exactly is new here?
  • Adam B
    Demo is broken.

    $(this).next("span").css('display','inline').fadeOut(1000);

    Should read

    $(this).find("span").css('display','inline').fadeOut(1000);

    .next s/b .find
  • Karl Swedberg
    Thanks (and thanks, Konard)! Fixed.
  • Konard
    Demo is not working

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.keydown() – jQuery API

jQuery API

Skip to content
  • api

.keydown()

Categories: Events > Keyboard Events

.keydown( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.

  • version added: 1.0.keydown( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.keydown()

This method is a shortcut for .bind('keydown', handler) in the first variation, and .trigger('keydown') in the second.

The keydown event is sent to an element when the user first presses a key on the keyboard. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

$('#target').keydown(function() {
  alert('Handler for .keydown() called.');
});

Now when the insertion point is inside the field and a key is pressed, the alert is displayed:

Handler for .keydown() called.

We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').keydown();
});

After this code executes, clicks on Trigger the handler will also alert the message.

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which key was pressed, we can examine the event object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the .which property so we can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, .keypress() may be a better choice.

Example:

Show the event object for the keydown handler when a key is pressed in the input.

<!DOCTYPE html>
<html>
<head>
  <style>
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
  width: 100%;
}
.print-output-line {
  white-space: pre;
  padding: 5px;
  font-family: monaco, monospace;
  font-size: .7em;
}

</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
  <fieldset>
    <label for="target">Type Something:</label>
    <input id="target" type="text" />
  </fieldset>
</form>
<button id="other">
  Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>
<script>
var xTriggered = 0;
$('#target').keydown(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keydown() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keydown();
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .keydown().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.keypress() – jQuery API

jQuery API

Skip to content
  • api

.keypress()

Categories: Events > Keyboard Events

.keypress( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.

  • version added: 1.0.keypress( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.keypress()

This method is a shortcut for .bind('keypress', handler) in the first variation, and .trigger('keypress') in the second.

The keypress event is sent to an element when the browser registers keyboard input. This is similar to the keydown event, except in the case of key repeats. If the user presses and holds a key, a keydown event is triggered once, but separate keypress events are triggered for each inserted character. In addition, modifier keys (such as Shift) cause keydown events but not keypress events.

A keypress event handler can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
    <fieldset>
      <input id="target" type="text" value="Hello there" />
    </fieldset>
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

$('#target').keypress(function() {
  alert('Handler for .keypress() called.');
});

Now when the insertion point is inside the field and a key is pressed, the alert is displayed:

Handler for .keypress() called.

The message repeats if the key is held down. We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').keypress();
});

After this code executes, clicks on Trigger the handler will also alert the message.

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which character was entered, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the .which attribute so we can reliably use it to retrieve the character code.

Note that keydown and keyup provide a code indicating which key is pressed, while keypress indicates which character was entered. For example, a lowercase "a" will be reported as 65 by keydown and keyup, but as 97 by keypress. An uppercase "A" is reported as 97 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, .keydown() or .keyup() is a better choice.

Example:

Show the event object for the keypress handler when a key is pressed in the input.

<!DOCTYPE html>
<html>
<head>
  <style>
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
  width: 100%;
}
.print-output-line {
  white-space: pre;
  padding: 5px;
  font-family: monaco, monospace;
  font-size: .7em;
}

</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
  <fieldset>
    <label for="target">Type Something:</label>
    <input id="target" type="text" />
  </fieldset>
</form>
<button id="other">
  Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>
<script>
var xTriggered = 0;
$('#target').keypress(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keypress() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keypress();
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .keypress().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.keyup() – jQuery API

jQuery API

Skip to content
  • api

.keyup()

Categories: Events > Keyboard Events

.keyup( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "keyup" JavaScript event, or trigger that event on an element.

  • version added: 1.0.keyup( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.keyup()

This method is a shortcut for .bind('keyup', handler) in the first variation, and .trigger('keyup') in the second.

The keyup event is sent to an element when the user releases a key on the keyboard. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.

For example, consider the HTML:

<form>
  <input id="target" type="text" value="Hello there" />
</form>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to the input field:

$('#target').keyup(function() {
  alert('Handler for .keyup() called.');
});

Now when the insertion point is inside the field and a key is pressed and released, the alert is displayed:

Handler for .keyup() called.

We can trigger the event manually when another element is clicked:

$('#other').click(function() {
  $('#target').keyup();
});

After this code executes, clicks on Trigger the handler will also alert the message.

If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the document object. Because of event bubbling, all key presses will make their way up the DOM to the document object unless explicitly stopped.

To determine which key was pressed, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the .which attribute so we can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, .keypress() may be a better choice.

Example:

Show the event object for the keyup handler when a key is released in the input.

<!DOCTYPE html>
<html>
<head>
  <style>
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
  width: 100%;
}
.print-output-line {
  white-space: pre;
  padding: 5px;
  font-family: monaco, monospace;
  font-size: .7em;
}

</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
  <fieldset>
    <label for="target">Type Something:</label>
    <input id="target" type="text" />
  </fieldset>
</form>
<button id="other">
  Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>
<script>
var xTriggered = 0;
$('#target').keyup(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keyup() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keyup();
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .keyup().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Mouse Events – jQuery API

jQuery API

Skip to content
  • api

Mouse Events

  • .click()

    Bind an event handler to the "click" JavaScript event, or trigger that event on an element.

  • .dblclick()

    Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.

  • .focusin()

    Keyboard Events

    Bind an event handler to the "focusin" JavaScript event.

  • .focusout()

    Keyboard Events

    Bind an event handler to the "focusout" JavaScript event.

  • .hover()

    Bind two handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.

  • .mousedown()

    Bind an event handler to the "mousedown" JavaScript event, or trigger that event on an element.

  • .mouseenter()

    Bind an event handler to be fired when the mouse enters an element, or trigger that handler on an element.

  • .mouseleave()

    Bind an event handler to be fired when the mouse leaves an element, or trigger that handler on an element.

  • .mousemove()

    Bind an event handler to the "mousemove" JavaScript event, or trigger that event on an element.

  • .mouseout()

    Bind an event handler to the "mouseout" JavaScript event, or trigger that event on an element.

  • .mouseover()

    Bind an event handler to the "mouseover" JavaScript event, or trigger that event on an element.

  • .mouseup()

    Bind an event handler to the "mouseup" JavaScript event, or trigger that event on an element.

  • .toggle()

    Basics

    Bind two or more handlers to the matched elements, to be executed on alternate clicks.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.click() – jQuery API

jQuery API

Skip to content
  • api

.click()

Categories: Events > Mouse Events

.click( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "click" JavaScript event, or trigger that event on an element.

  • version added: 1.0.click( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.click()

This method is a shortcut for .bind('click', handler) in the first variation, and .trigger('click') in the second.

The click event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event.

For example, consider the HTML:
<div id="target">
  Click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$('#target').click(function() {
  alert('Handler for .click() called.');
});

Now if we click on this element, the alert is displayed:

Handler for .click() called.

We can also trigger the event when a different element is clicked:

$('#other').click(function() {
  $('#target').click();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The click event is only triggered after this exact series of events:

  • The mouse button is depressed while the pointer is inside the element.
  • The mouse button is released while the pointer is inside the element.

This is usually the desired sequence before taking an action. If this is not required, the mousedown or mouseup event may be more suitable.

Examples:

Example: To hide paragraphs on a page when they are clicked:

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:red; margin:5px; cursor:pointer; }
  p.hilite { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>First Paragraph</p>

  <p>Second Paragraph</p>
  <p>Yet one more Paragraph</p>
<script>
    $("p").click(function () {
      $(this).slideUp();
    });
    $("p").hover(function () {
      $(this).addClass("hilite");
    }, function () {
      $(this).removeClass("hilite");
    });
</script>
</body>
</html>

Demo:

Example: To trigger the click event on all of the paragraphs on the page:

$("p").click();

Comments

  • Please keep comments relevant to .click().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • bobbykjack
    According to my testing, under Firefox 3, this event also fires on a submit button when that button's form is submitted, even if it's submitted via the keyboard. This is quite non-intuitive, so be sure it doesn't catch you out!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.dblclick() – jQuery API

jQuery API

Skip to content
  • api

.dblclick()

Categories: Events > Mouse Events

.dblclick( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.

  • version added: 1.0.dblclick( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.dblclick()

This method is a shortcut for .bind('dblclick', handler) in the first variation, and .trigger('dblclick') in the second. The dblclick event is sent to an element when the element is double-clicked. Any HTML element can receive this event. For example, consider the HTML:

<div id="target">
  Double-click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$('#target').dblclick(function() {
  alert('Handler for .dblclick() called.');
});

Now if we double-click on this element, the alert is displayed:

Handler for .dblclick() called.

We can also trigger the event when a different element is clicked:

$('#other').click(function() {
  $('#target').dblclick();
});

After this code executes, (single) clicks on Trigger the handler will also alert the message.

The dblclick event is only triggered after this exact series of events:

  • The mouse button is depressed while the pointer is inside the element.
  • The mouse button is released while the pointer is inside the element.
  • The mouse button is depressed again while the pointer is inside the element, within a time window that is system-dependent.
  • The mouse button is released while the pointer is inside the element.

It is inadvisable to bind handlers to both the click and dblclick events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two click events and others only one. If an interface that reacts differently to single- and double-clicks cannot be avoided, then the dblclick event should be simulated within the click handler. We can achieve this by saving a timestamp in the handler, and then comparing the current time to the saved timestamp on subsequent clicks. If the difference is small enough, we can treat the click as a double-click.

Examples:

Example: To bind a "Hello World!" alert box the dblclick event on every paragraph on the page:

$("p").dblclick( function () { alert("Hello World!"); });

Example: Double click to toggle background color.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { background:blue;
        color:white;
        height:100px;
        width:150px;
 }
  div.dbl { background:yellow;color:black; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div><span>Double click the block</span>
<script>
    var divdbl = $("div:first");
    divdbl.dblclick(function () {
      divdbl.toggleClass('dbl');
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .dblclick().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.hover() – jQuery API

jQuery API

Skip to content
  • api

.hover()

Categories: Events > Mouse Events
Contents:
  • hover( handlerIn(eventObject), handlerOut(eventObject) )
    • .hover( handlerIn(eventObject), handlerOut(eventObject) )
  • hover( handlerInOut(eventObject) )
    • .hover( handlerInOut(eventObject) )

.hover( handlerIn(eventObject), handlerOut(eventObject) ) Returns: jQuery

Description: Bind two handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.

  • version added: 1.0.hover( handlerIn(eventObject), handlerOut(eventObject) )

    handlerIn(eventObject)A function to execute when the mouse pointer enters the element.

    handlerOut(eventObject)A function to execute when the mouse pointer leaves the element.

The .hover() method binds handlers for both mouseenter and mouseleave events. We can use it to simply apply behavior to an element during the time the mouse is within the element.

Calling $(selector).hover(handlerIn, handlerOut) is shorthand for:

$(selector).mouseenter(handlerIn).mouseleave(handlerOut);

See the discussions for .mouseenter() and .mouseleave() for more details.

Examples:

Example: To add a special style to list items that are being hovered over, try:

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { margin-left:20px; color:blue; }
  li { cursor:default; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
    <li>Milk</li>
    <li>Bread</li>
    <li class='fade'>Chips</li>

    <li class='fade'>Socks</li>
  </ul>
<script>
    $("li").hover(
      function () {
        $(this).append($("<span> ***</span>"));
      },
      function () {
        $(this).find("span:last").remove();
      }
    );

  //li with fade class
   $("li.fade").hover(function(){$(this).fadeOut(100);$(this).fadeIn(500);});

</script>
</body>
</html>

Demo:

Example: To add a special style to table cells that are being hovered over, try:

$("td").hover(
  function () {
    $(this).addClass("hover");
  },
  function () {
    $(this).removeClass("hover");
  }
);

Example: To unbind the above example use:

$("td").unbind('mouseenter mouseleave');

.hover( handlerInOut(eventObject) ) Returns: jQuery

Description: Bind a single handler to the matched elements, to be executed when the mouse pointer enters or leaves the elements.

  • version added: 1.4.hover( handlerInOut(eventObject) )

    handlerInOut(eventObject)A function to execute when the mouse pointer enters or leaves the element.

The .hover() method, when passed a single function, will execute that handler for both mouseenter and mouseleave events. This allows the user to use jQuery's various toggle methods within the handler.

Calling $(selector).hover(handlerInOut) is shorthand for:

$(selector).bind("mouseenter mouseleave",handlerInOut);

See the discussions for .mouseenter() and .mouseleave() for more details.

Example:

Slide the next sibling LI up or down on hover, and toggle a class.

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { margin-left:20px; color:blue; }
  li { cursor:default; }
  li.active { background:black;color:white; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
    <li>Milk</li>
    <li>White</li>
    <li>Carrots</li>
    <li>Orange</li>
    <li>Broccoli</li>
    <li>Green</li>
  </ul>
<script>
    $("li")
    .filter(":odd")
    .hide()
     .end()
    .filter(":even")
    .hover(
      function () {
        $(this).toggleClass("active").next().slideToggle();
      }
    );

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .hover().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Andrée Hansson
    What the docs are not clear with (except for one of the examples), is that it now can take only one argument, and that function will be bound to both mouseenter/mouseleave, great for example when toggling a class on an element (with .toggleClass).

    -- Edit: Added to the docs.
  • Leon Sutton
    Assuming the internal logic actually uses the 'mouseenter' and 'mouseleave' events respectively, unbinding this behavior is as simple as $(element).unbind('mouseenter mouseleave') ... right?
  • Leon Sutton
    Yeah ... perhaps I should read the *whole* page before I post a comment, huh? :|

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mousedown() – jQuery API

jQuery API

Skip to content
  • api

.mousedown()

Categories: Events > Mouse Events

.mousedown( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "mousedown" JavaScript event, or trigger that event on an element.

  • version added: 1.0.mousedown( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mousedown()

This method is a shortcut for .bind('mousedown', handler) in the first variation, and .trigger('mousedown') in the second.

The mousedown event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed. Any HTML element can receive this event.

For example, consider the HTML:

<div id="target">
  Click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$('#target').mousedown(function() {
  alert('Handler for .mousedown() called.');
});

Now if we click on this element, the alert is displayed:

Handler for .mousedown() called.

We can also trigger the event when a different element is clicked:

$('#other').click(function() {
  $('#target').mousedown();
});

After this code executes, clicks on Trigger the handler will also alert the message.

The mousedown event is sent when any mouse button is clicked. To act only on specific buttons, we can use the event object's which property. Not all browsers support this property (Internet Explorer uses button instead), but jQuery normalizes the property so that it is safe to use in any browser. The value of which will be 1 for the left button, 2 for the middle button, or 3 for the right button.

This event is primarily useful for ensuring that the primary button was used to begin a drag operation; if ignored, strange results can occur when the user attempts to use a context menu. While the middle and right buttons can be detected with these properties, this is not reliable. In Opera and Safari, for example, right mouse button clicks are not detectable by default.

If the user clicks on an element, drags away from it, and releases the button, this is still counted as a mousedown event. This sequence of actions is treated as a "canceling" of the button press in most user interfaces, so it is usually better to use the click event unless we know that the mousedown event is preferable for a particular situation.

Example:

Show texts when mouseup and mousedown event triggering.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Press mouse and release here.</p>

<script>
    $("p").mouseup(function(){
      $(this).append('<span style="color:#F00;">Mouse up.</span>');
    }).mousedown(function(){
      $(this).append('<span style="color:#00F;">Mouse down.</span>');
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mousedown().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mouseenter() – jQuery API

jQuery API

Skip to content
  • api

.mouseenter()

Categories: Events > Mouse Events

.mouseenter( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to be fired when the mouse enters an element, or trigger that handler on an element.

  • version added: 1.0.mouseenter( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mouseenter()

This method is a shortcut for .bind('mouseenter', handler) in the first variation, and .trigger('mouseenter') in the second.

The mouseenter JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseenter(function() {
  $('#log').append('<div>Handler for .mouseenter() called.</div>');
});

Now when the mouse pointer moves over the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseenter();
});

After this code executes, clicks on Trigger the handler will also append the message.

The mouseenter event differs from mouseover in the way it handles event bubbling. If mouseover were used in this example, then when the mouse pointer moved over the Inner element, the handler would be triggered. This is usually undesirable behavior. The mouseenter event, on the other hand, only triggers its handler when the mouse enters the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse enters the Outer element, but not the Inner element.

Example:

Show texts when mouseenter and mouseout event triggering. mouseover fires when the pointer moves into the child element as well, while mouseenter fires only when the pointer moves into the bound element.

<!DOCTYPE html>
<html>
<head>
  <style>
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<script>
    var i = 0;
    $("div.overout").mouseover(function(){
      $("p:first",this).text("mouse over");
      $("p:last",this).text(++i);
    }).mouseout(function(){
      $("p:first",this).text("mouse out");
    });

    var n = 0;
    $("div.enterleave").mouseenter(function(){
      $("p:first",this).text("mouse enter");
      $("p:last",this).text(++n);
    }).mouseleave(function(){
      $("p:first",this).text("mouse leave");
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mouseenter().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mouseleave() – jQuery API

jQuery API

Skip to content
  • api

.mouseleave()

Categories: Events > Mouse Events

.mouseleave( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to be fired when the mouse leaves an element, or trigger that handler on an element.

  • version added: 1.0.mouseleave( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mouseleave()

This method is a shortcut for .bind('mouseleave', handler) in the first variation, and .trigger('mouseleave') in the second.

The mouseleave JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseleave(function() {
  $('#log').append('<div>Handler for .mouseleave() called.</div>');
});

Now when the mouse pointer moves out of the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseleave();
});

After this code executes, clicks on Trigger the handler will also append the message.

The mouseleave event differs from mouseout in the way it handles event bubbling. If mouseout were used in this example, then when the mouse pointer moved out of the Inner element, the handler would be triggered. This is usually undesirable behavior. The mouseleave event, on the other hand, only triggers its handler when the mouse leaves the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse leaves the Outer element, but not the Inner element.

Example:

Show number of times mouseout and mouseleave events are triggered. mouseout fires when the pointer moves out of child element as well, while mouseleave fires only when the pointer moves out of the bound element.

<!DOCTYPE html>
<html>
<head>
  <style>
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<script>
    var i = 0;
    $("div.overout").mouseover(function(){
      $("p:first",this).text("mouse over");
    }).mouseout(function(){
      $("p:first",this).text("mouse out");
      $("p:last",this).text(++i);
    });

    var n = 0;
    $("div.enterleave").mouseenter(function(){
      $("p:first",this).text("mouse enter");
    }).mouseleave(function(){
      $("p:first",this).text("mouse leave");
      $("p:last",this).text(++n);
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mouseleave().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mousemove() – jQuery API

jQuery API

Skip to content
  • api

.mousemove()

Categories: Events > Mouse Events

.mousemove( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "mousemove" JavaScript event, or trigger that event on an element.

  • version added: 1.0.mousemove( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mousemove()

This method is a shortcut for .bind('mousemove', handler) in the first variation, and .trigger('mousemove') in the second.

The mousemove event is sent to an element when the mouse pointer moves inside the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="target">
  Move here
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to the target:

$('#target').mousemove(function(event) {
  var msg = 'Handler for .mousemove() called at ' + event.pageX + ', ' + event.pageY;
  $('#log').append('<div> + msg + '</div>');
});

Now when the mouse pointer moves within the target button, the messages are appended to <div id="log">:

Handler for .mousemove() called at (399, 48)
Handler for .mousemove() called at (398, 46)
Handler for .mousemove() called at (397, 44)
Handler for .mousemove() called at (396, 42)

We can also trigger the event when the second button is clicked:

$('#other').click(function() {
  $('#target').mousemove();
});

After this code executes, clicks on the Trigger button will also append the message:

Handler for .mousemove() called at (undefined, undefined)

When tracking mouse movement, we usually need to know the actual position of the mouse pointer. The event object that is passed to the handler contains some information about the mouse coordinates. Properties such as .clientX, .offsetX, and .pageX are available, but support for them differs between browsers. Fortunately, jQuery normalizes the .pageX and .pageY attributes so that they can be used in all browsers. These attributes provide the X and Y coordinates of the mouse pointer relative to the top-left corner of the page, as illustrated in the example output above.

We need to remember that the mousemove event is triggered whenever the mouse pointer moves, even for a pixel. This means that hundreds of events can be generated over a very small amount of time. If the handler has to do any significant processing, or if multiple handlers for the event exist, this can be a serious performance drain on the browser. It is important, therefore, to optimize mousemove handlers as much as possible, and to unbind them as soon as they are no longer needed.

A common pattern is to bind the mousemove handler from within a mousedown hander, and to unbind it from a corresponding mouseup handler. If implementing this sequence of events, remember that the mouseup event might be sent to a different HTML element than the mousemove event was. To account for this, the mouseup handler should typically be bound to an element high up in the DOM tree, such as <body>.

Example:

Show the mouse coordinates when the mouse is moved over the yellow div. Coordinates are relative to the window, which in this case is the iframe.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:220px; height:170px; margin;10px; margin-right:50px;
        background:yellow; border:2px groove; float:right; }
  p { margin:0; margin-left:10px; color:red; width:220px;
      height:120px; padding-top:70px;
      float:left; font-size:14px; }
  span { display:block; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    Try scrolling too.
    <span>Move the mouse over the div.</span>
    <span>&nbsp;</span>
  </p>

  <div></div>
<script>
    $("div").mousemove(function(e){
      var pageCoords = "( " + e.pageX + ", " + e.pageY + " )";
      var clientCoords = "( " + e.clientX + ", " + e.clientY + " )";
      $("span:first").text("( e.pageX, e.pageY ) - " + pageCoords);
      $("span:last").text("( e.clientX, e.clientY ) - " + clientCoords);
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mousemove().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mouseout() – jQuery API

jQuery API

Skip to content
  • api

.mouseout()

Categories: Events > Mouse Events

.mouseout( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "mouseout" JavaScript event, or trigger that event on an element.

  • version added: 1.0.mouseout( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mouseout()

This method is a shortcut for .bind('mouseout', handler) in the first variation, and .trigger('mouseout') in the second.

The mouseout event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseout(function() {
  $('#log').append('Handler for .mouseout() called.');
});

Now when the mouse pointer moves out of the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseout();
});

After this code executes, clicks on Trigger the handler will also append the message.

This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves out of the Inner element in this example, a mouseout event will be sent to that, then trickle up to Outer. This can trigger the bound mouseout handler at inopportune times. See the discussion for .mouseleave() for a useful alternative.

Example:

Show the number of times mouseout and mouseleave events are triggered. mouseout fires when the pointer moves out of the child element as well, while mouseleave fires only when the pointer moves out of the bound element.

<!DOCTYPE html>
<html>
<head>
  <style>
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<script>
    var i = 0;
    $("div.overout").mouseout(function(){
      $("p:first",this).text("mouse out");
      $("p:last",this).text(++i);
    }).mouseover(function(){
      $("p:first",this).text("mouse over");
    });

    var n = 0;
    $("div.enterleave").bind("mouseenter",function(){
      $("p:first",this).text("mouse enter");
    }).bind("mouseleave",function(){
      $("p:first",this).text("mouse leave");
      $("p:last",this).text(++n);
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mouseout().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mouseover() – jQuery API

jQuery API

Skip to content
  • api

.mouseover()

Categories: Events > Mouse Events

.mouseover( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "mouseover" JavaScript event, or trigger that event on an element.

  • version added: 1.0.mouseover( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mouseover()

This method is a shortcut for .bind('mouseover', handler) in the first variation, and .trigger('mouseover') in the second.

The mouseover event is sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.

For example, consider the HTML:

<div id="outer">
  Outer
  <div id="inner">
    Inner
  </div>
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

The event handler can be bound to any element:

$('#outer').mouseover(function() {
  $('#log').append('<div>Handler for .mouseover() called.</div>');
});

Now when the mouse pointer moves over the Outer <div>, the message is appended to <div id="log">. We can also trigger the event when another element is clicked:

$('#other').click(function() {
  $('#outer').mouseover();
});

After this code executes, clicks on Trigger the handler will also append the message.

This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves over the Inner element in this example, a mouseover event will be sent to that, then trickle up to Outer. This can trigger our bound mouseover handler at inopportune times. See the discussion for .mouseenter() for a useful alternative.

Example:

Show the number of times mouseover and mouseenter events are triggered. mouseover fires when the pointer moves into the child element as well, while mouseenter fires only when the pointer moves into the bound element.

<!DOCTYPE html>
<html>
<head>
  <style>
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<script>
    var i = 0;
    $("div.overout").mouseover(function(){
      $("p:first",this).text("mouse over");
      $("p:last",this).text(++i);
    }).mouseout(function(){
      $("p:first",this).text("mouse out");
    });

    var n = 0;
    $("div.enterleave").bind("mouseenter",function(){
      $("p:first",this).text("mouse enter");
      $("p:last",this).text(++n);
    }).bind("mouseleave",function(){
      $("p:first",this).text("mouse leave");
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mouseover().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.mouseup() – jQuery API

jQuery API

Skip to content
  • api

.mouseup()

Categories: Events > Mouse Events

.mouseup( handler(eventObject) ) Returns: jQuery

Description: Bind an event handler to the "mouseup" JavaScript event, or trigger that event on an element.

  • version added: 1.0.mouseup( handler(eventObject) )

    handler(eventObject)A function to execute each time the event is triggered.

  • version added: 1.0.mouseup()

This method is a shortcut for .bind('mouseup', handler) in the first variation, and .trigger('mouseup') in the second.

The mouseup event is sent to an element when the mouse pointer is over the element, and the mouse button is released. Any HTML element can receive this event.

For example, consider the HTML:

<div id="target">
  Click here
</div>
<div id="other">
  Trigger the handler
</div>

The event handler can be bound to any <div>:

$('#target').mouseup(function() {
  alert('Handler for .mouseup() called.');
});

Now if we click on this element, the alert is displayed:

Handler for .mouseup() called.

We can also trigger the event when a different element is clicked:

$('#other').click(function() {
  $('#target').mouseup();
});

After this code executes, clicks on Trigger the handler will also alert the message.

If the user clicks outside an element, drags onto it, and releases the button, this is still counted as a mouseup event. This sequence of actions is not treated as a button press in most user interfaces, so it is usually better to use the click event unless we know that the mouseup event is preferable for a particular situation.

Example:

Show texts when mouseup and mousedown event triggering.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Press mouse and release here.</p>

<script>
    $("p").mouseup(function(){
      $(this).append('<span style="color:#F00;">Mouse up.</span>');
    }).mousedown(function(){
      $(this).append('<span style="color:#00F;">Mouse down.</span>');
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .mouseup().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Forms – jQuery API

jQuery API

Skip to content
  • api

Forms

  • .blur()

    Form Events

    Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.

  • .change()

    Form Events

    Bind an event handler to the "change" JavaScript event, or trigger that event on an element.

  • .focus()

    Form Events

    Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.

  • jQuery.param()

    Collection Manipulation, Helper Functions

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • .select()

    Form Events

    Bind an event handler to the "select" JavaScript event, or trigger that event on an element.

  • .serialize()

    Helper Functions

    Encode a set of form elements as a string for submission.

  • .serializeArray()

    Helper Functions

    Encode a set of form elements as an array of names and values.

  • .submit()

    Form Events

    Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

  • .val()

    Attributes, General Attributes

    Get the current value of the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Manipulation – jQuery API

jQuery API

Skip to content
  • api

Manipulation

All of the methods in this chapter manipulate the DOM in some manner. A few of them simply change one of the attributes of an element (also listed in the Attributes category), while others set an element’s style properties (also listed in the CSS category). Still others modify entire elements (or groups of elements) themselves—inserting, copying, removing, and so on. All of these methods are referred to as “setters,” as they change the values of properties.
A few of these methods—such as .attr(), .html(), and .val()—also act as “getters,” retrieving information from DOM elements for later use.

  • .addClass()

    Attributes, CSS, Class Attribute

    Adds the specified class(es) to each of the set of matched elements.

  • .after()

    DOM Insertion, Outside

    Insert content, specified by the parameter, after each element in the set of matched elements.

  • .append()

    DOM Insertion, Inside

    Insert content, specified by the parameter, to the end of each element in the set of matched elements.

  • .appendTo()

    DOM Insertion, Inside

    Insert every element in the set of matched elements to the end of the target.

  • .attr()

    Attributes, General Attributes

    Get the value of an attribute for the first element in the set of matched elements.

  • .before()

    DOM Insertion, Outside

    Insert content, specified by the parameter, before each element in the set of matched elements.

  • .clone()

    Copying

    Create a copy of the set of matched elements.

  • .css()

    CSS, Style Properties

    Get the value of a style property for the first element in the set of matched elements.

  • .detach()

    DOM Removal

    Remove the set of matched elements from the DOM.

  • .empty()

    DOM Removal

    Remove all child nodes of the set of matched elements from the DOM.

  • .hasClass()

    Attributes, CSS, Class Attribute

    Determine whether any of the matched elements are assigned the given class.

  • .height()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements.

  • .html()

    Attributes, DOM Insertion

    Get the HTML contents of the first element in the set of matched elements.

  • .innerHeight()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • .innerWidth()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • .insertAfter()

    DOM Insertion, Outside

    Insert every element in the set of matched elements after the target.

  • .insertBefore()

    DOM Insertion, Outside

    Insert every element in the set of matched elements before the target.

  • .offset()

    CSS, Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • .outerHeight()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding and border.

  • .outerWidth()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding and border.

  • .position()

    CSS, Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • .prepend()

    DOM Insertion, Inside

    Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.

  • .prependTo()

    DOM Insertion, Inside

    Insert every element in the set of matched elements to the beginning of the target.

  • .remove()

    DOM Removal

    Remove the set of matched elements from the DOM.

  • .removeAttr()

    Attributes, General Attributes

    Remove an attribute from each element in the set of matched elements.

  • .removeClass()

    Attributes, CSS, Class Attribute

    Remove one or all classes from each element in the set of matched elements.

  • .replaceAll()

    DOM Replacement

    A selector expression indicating which element(s) to replace.

  • .replaceWith()

    DOM Replacement

    Replace each element in the set of matched elements with the provided new content.

  • .scrollLeft()

    CSS, Offset, Style Properties

    Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • .scrollTop()

    CSS, Offset, Style Properties

    Get the current vertical position of the scroll bar for the first element in the set of matched elements.

  • .text()

    Attributes, DOM Insertion, Inside, General Attributes

    Get the combined text contents of each element in the set of matched elements, including their descendants.

  • .text()

    Attributes, DOM Insertion, Inside, General Attributes

    Get the combined text contents of each element in the set of matched elements, including their descendants.

  • .toggleClass()

    Attributes, CSS, Class Attribute

    Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

  • .unwrap()

    DOM Insertion, Around, DOM Removal

    Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

  • .unwrap()

    DOM Insertion, Around, DOM Removal

    Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

  • .val()

    Attributes, Forms, General Attributes

    Get the current value of the first element in the set of matched elements.

  • .width()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements.

  • .wrap()

    DOM Insertion, Around

    Wrap an HTML structure around each element in the set of matched elements.

  • .wrapAll()

    DOM Insertion, Around

    Wrap an HTML structure around all elements in the set of matched elements.

  • .wrapInner()

    DOM Insertion, Around

    Wrap an HTML structure around the content of each element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Class Attribute – jQuery API

jQuery API

Skip to content
  • api

Class Attribute

These methods inspect and manipulate the CSS classes assigned to elements.

  • .addClass()

    Attributes, CSS

    Adds the specified class(es) to each of the set of matched elements.

  • .hasClass()

    Attributes, CSS

    Determine whether any of the matched elements are assigned the given class.

  • .removeClass()

    Attributes, CSS

    Remove one or all classes from each element in the set of matched elements.

  • .toggleClass()

    Attributes, CSS

    Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Copying – jQuery API

jQuery API

Skip to content
  • api

Copying

This method allows us to make copies of elements.

  • .clone()

    Create a copy of the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.clone() – jQuery API

jQuery API

Skip to content
  • api

.clone()

Categories: Manipulation > Copying

.clone( [ withDataAndEvents ] ) Returns: jQuery

Description: Create a copy of the set of matched elements.

  • version added: 1.0.clone( [ withDataAndEvents ] )

    withDataAndEventsA Boolean indicating whether event handlers should be copied along with the elements. As of jQuery 1.4 element data will be copied as well.

The .clone() method, when used in conjunction with one of the insertion methods, is a convenient way to duplicate elements on a page. Consider the following HTML:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

As shown in the discussion for .append(), normally when we insert an element somewhere in the DOM, it is moved from its old location. So, given the code:

$('.hello').appendTo('.goodbye');

The resulting DOM structure would be:

<div class="container">
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

To prevent this and instead create a copy of the element, we could write the following:

$('.hello').clone().appendTo('.goodbye');

This would produce:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">
    Goodbye
    <div class="hello">Hello</div>
  </div>
</div>

Note that when using the .clone() method, we can modify the cloned elements or their contents before (re-)inserting them into the document.

Normally, any event handlers bound to the original element are not copied to the clone. The optional withDataAndEvents parameter allows us to change this behavior, and to instead make copies of all of the event handlers as well, bound to the new copy of the element. As of jQuery 1.4, all element data (attached by the .data() method) is also copied to the new copy.

Example:

Clones all b elements (and selects the clones) and prepends them to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <b>Hello</b><p>, how are you?</p>
<script>$("b").clone().prependTo("p");</script>
</body>
</html>

Demo:

Result:

<b>Hello</b><p><b>Hello</b>, how are you?</p>

Comments

  • Please keep comments relevant to .clone().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Insertion – jQuery API

jQuery API

Skip to content
  • api

DOM Insertion

  • .html()

    Attributes

    Get the HTML contents of the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Insertion, Around – jQuery API

jQuery API

Skip to content
  • api

DOM Insertion, Around

These methods allow us to insert new content surrounding existing content.

  • .unwrap()

    DOM Removal

    Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

  • .wrap()

    Wrap an HTML structure around each element in the set of matched elements.

  • .wrapAll()

    Wrap an HTML structure around all elements in the set of matched elements.

  • .wrapInner()

    Wrap an HTML structure around the content of each element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.unwrap() – jQuery API

jQuery API

Skip to content
  • api

.unwrap()

Categories: Manipulation > DOM Insertion, Around | Manipulation > DOM Removal

.unwrap() Returns: jQuery

Description: Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

  • version added: 1.4.unwrap()

The .unwrap() method removes the element's parent. This is effectively the inverse of the .wrap() method. The matched elements (and their siblings, if any) replace their parents within the DOM structure.

Example:

Wrap/unwrap a div around each of the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>wrap/unwrap</button>
<p>Hello</p>
<p>cruel</p>
<p>World</p>
<script>
$("button").toggle(function(){
  $("p").wrap("<div></div>");
}, function(){
  $("p").unwrap();
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .unwrap().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • sun
    uhm, shouldn't this allow to pass a selector? What if there are multiple parents/wrappers and you only know a wrapping id or class?
  • "Cowboy" Ben Alman
    FYI, If you're interested in how this method came to be, check out
    jQuery unwrap: The opposite of .wrap, pretty much
  • Karl Swedberg
    Thanks for the note! Button added!
  • Elektronik-Lexikon
    There needs to be a button in the demo!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.wrap() – jQuery API

jQuery API

Skip to content
  • api

.wrap()

Categories: Manipulation > DOM Insertion, Around

.wrap( wrappingElement ) Returns: jQuery

Description: Wrap an HTML structure around each element in the set of matched elements.

  • version added: 1.0.wrap( wrappingElement )

    wrappingElementAn HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements.

  • version added: 1.4.wrap( wrappingFunction )

    wrappingFunctionA callback function which generates a structure to wrap around the matched elements.

The .wrap() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around each of the elements in the set of matched elements.

Consider the following HTML:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

Using .wrap(), we can insert an HTML structure around the inner <div> elements like so:

$('.inner').wrap('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around each matched element:

<div class="container">
  <div class="new">
    <div class="inner">Hello</div>
  </div>
  <div class="new">
    <div class="inner">Goodbye</div>
  </div>
</div>

The second version of this method allows us to instead specify a callback function. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the corresponding element. For example:

$('.inner').wrap(function() {
  return '<div class="' + $(this).text() + '" />';
});

This will cause each <div> to have a class corresponding to the text it wraps:

<div class="container">
  <div class="Hello">
    <div class="inner">Hello</div>
  </div>
  <div class="Goodbye">
    <div class="inner">Goodbye</div>
  </div>
</div>

Examples:

Example: Wrap a new div around all of the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrap("<div></div>");</script>
</body>
</html>

Demo:

Example: Wraps a newly created tree of objects around the spans. Notice anything in between the spans gets left out like the <strong> (red text) in this example. Even the white space between spans is left out. Click View Source to see the original html.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border:2px blue solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  strong { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>Span Text</span>
  <strong>What about me?</strong>
  <span>Another One</span>
<script>$("span").wrap("<div><div><p><em><b></b></em></p></div></div>");</script>
</body>
</html>

Demo:

Example: Wrap a new div around all of the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrap(document.createElement("div"));</script>
</body>
</html>

Demo:

Example: Wrap a jQuery object double depth div around all of the paragraphs. Notice it doesn't move the object but just clones it to wrap around its target.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; margin:2px; padding:2px; }
  .doublediv { border-color:red; }
  p { background:yellow; margin:4px; font-size:14px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
  <div class="doublediv"><div></div></div>
<script>$("p").wrap($(".doublediv"));</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .wrap().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Neil Craig
    I love the new function hookup, very handy if you have complex structures that needs to surround your target element. I intend to use it with my own jQuery UI widgets.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.wrapAll() – jQuery API

jQuery API

Skip to content
  • api

.wrapAll()

Categories: Manipulation > DOM Insertion, Around

.wrapAll( wrappingElement ) Returns: jQuery

Description: Wrap an HTML structure around all elements in the set of matched elements.

  • version added: 1.2.wrapAll( wrappingElement )

    wrappingElementAn HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements.

The .wrapAll() function can take any string or object that could be passed to the $() function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around all of the elements in the set of matched elements, as a single group.

Consider the following HTML:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

Using .wrapAll(), we can insert an HTML structure around the inner <div> elements like so:

$('.inner').wrapAll('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around all matched elements:

<div class="container">
  <div class="new">
    <div class="inner">Hello</div>
    <div class="inner">Goodbye</div>
  </div>
</div>

Examples:

Example: Wrap a new div around all of the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapAll("<div></div>");</script>
</body>
</html>

Demo:

Example: Wraps a newly created tree of objects around the spans. Notice anything in between the spans gets left out like the <strong> (red text) in this example. Even the white space between spans is left out. Click View Source to see the original html.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border:2px blue solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  strong { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>Span Text</span>
  <strong>What about me?</strong>
  <span>Another One</span>
<script>$("span").wrapAll("<div><div><p><em><b></b></em></p></div></div>");</script>
</body>
</html>

Demo:

Example: Wrap a new div around all of the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapAll(document.createElement("div"));</script>
</body>
</html>

Demo:

Example: Wrap a jQuery object double depth div around all of the paragraphs. Notice it doesn't move the object but just clones it to wrap around its target.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border: 2px solid blue; margin:2px; padding:2px; }
  .doublediv { border-color:red; }
  p { background:yellow; margin:4px; font-size:14px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
  <div class="doublediv"><div></div></div>
<script>$("p").wrapAll($(".doublediv"));</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .wrapAll().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.wrapInner() – jQuery API

jQuery API

Skip to content
  • api

.wrapInner()

Categories: Manipulation > DOM Insertion, Around

.wrapInner( wrappingElement ) Returns: jQuery

Description: Wrap an HTML structure around the content of each element in the set of matched elements.

  • version added: 1.2.wrapInner( wrappingElement )

    wrappingElementAn HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the content of the matched elements.

  • version added: 1.4.wrapInner( wrappingFunction )

    wrappingFunctionA callback function which generates a structure to wrap around the content of the matched elements.

The .wrapInner() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around the content of each of the elements in the set of matched elements.

Consider the following HTML:

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

Using .wrapInner(), we can insert an HTML structure around the content of each inner <div> elements like so:

$('.inner').wrapInner('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around the content of each matched element:

<div class="container">
  <div class="inner">
    <div class="new">Hello</div>
  </div>
  <div class="inner">
    <div class="new">Goodbye</div>
  </div>
</div>

The second version of this method allows us to instead specify a callback function. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the content of the corresponding element. For example:

$('.inner').wrapInner(function() {
  return '<div class="' + this.nodeValue + '" />';
});

This will cause each <div> to have a class corresponding to the text it wraps:

<div class="container">
  <div class="inner">
    <div class="Hello">Hello</div>
  </div>
  <div class="inner">
    <div class="Goodbye">Goodbye</div>
  </div>
</div>

Examples:

Example: Selects all paragraphs and wraps a bold tag around each of its contents.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:#bbf; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner("<b></b>");</script>
</body>
</html>

Demo:

Example: Wraps a newly created tree of objects around the inside of the body.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border:2px green solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Plain old text, or is it?
<script>$("body").wrapInner("<div><div><p><em><b></b></em></p></div></div>");</script>
</body>
</html>

Demo:

Example: Selects all paragraphs and wraps a bold tag around each of its contents.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:#9f9; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner(document.createElement("b"));</script>
</body>
</html>

Demo:

Example: Selects all paragraphs and wraps a jQuery object around each of its contents.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { background:#9f9; }
  .red { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner($("<span class='red'></span>"));</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .wrapInner().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • NickT
    Here's an example I like - I have a table with rows of test builds and test run times (in hours) in column 4. To make it easier to compare by build, I've added a simple bar graph to each time value:

    $("#tClientTestBuilds td:nth-child(4)").wrapInner(function() {
    return "<div style='background-color:#2C3D5A;color:white;width:" +
    5 * this.nodeValue + "px'> </div>";
    });
  • xxx
    "Using .wrapInner(), we can insert an HTML structure around the inner <div> elements like so:"

    That should have "contents of " in it somewhere I think!
  • Karl Swedberg
    Yes, indeed. Thanks for the report. Fixed.
  • sun
    A clarification on the difference to .wrap() would be great to see here; ideally, in the initial description already, possibly enhanced by a code example.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Insertion, Inside – jQuery API

jQuery API

Skip to content
  • api

DOM Insertion, Inside

These methods allow us to insert new content inside an existing element.

  • .append()

    Insert content, specified by the parameter, to the end of each element in the set of matched elements.

  • .appendTo()

    Insert every element in the set of matched elements to the end of the target.

  • .prepend()

    Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.

  • .prependTo()

    Insert every element in the set of matched elements to the beginning of the target.

  • .text()

    Attributes, General Attributes

    Get the combined text contents of each element in the set of matched elements, including their descendants.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.append() – jQuery API

jQuery API

Skip to content
  • api

.append()

Categories: Manipulation > DOM Insertion, Inside

.append( content ) Returns: jQuery

Description: Insert content, specified by the parameter, to the end of each element in the set of matched elements.

  • version added: 1.0.append( content )

    contentAn element, HTML string, or jQuery object to insert at the end of each element in the set of matched elements.

  • version added: 1.4.append( function(index, html) )

    function(index, html)A function that returns an HTML string to insert at the end of each element in the set of matched elements. Receives the index position of the element in the set and the old HTML value of the element as arguments.

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once:

$('.inner').append('<p>Test</p>');

Each inner <div> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    Hello
    <p>Test</p>
  </div>
  <div class="inner">
    Goodbye
    <p>Test</p>
  </div>
</div>

We can also select an element on the page and insert it into another:

$('.container').append($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Examples:

Example: Appends some HTML to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>I would like to say: </p>
<script>$("p").append("<strong>Hello</strong>");</script>
</body>
</html>

Demo:

Example: Appends an Element to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>I would like to say: </p>
<script>$("p").append(document.createTextNode("Hello"));</script>
</body>
</html>

Demo:

Example: Appends a jQuery object (similar to an Array of DOM Elements) to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <strong>Hello world!!!</strong><p>I would like to say: </p>
<script>$("p").append( $("strong") );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .append().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.appendTo() – jQuery API

jQuery API

Skip to content
  • api

.appendTo()

Categories: Manipulation > DOM Insertion, Inside

.appendTo( target ) Returns: jQuery

Description: Insert every element in the set of matched elements to the end of the target.

  • version added: 1.0.appendTo( target )

    targetA selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the end of the element(s) specified by this parameter.

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once:

$('<p>Test</p>').appendTo('.inner');

Each inner <div> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    Hello
    <p>Test</p>
  </div>
  <div class="inner">
    Goodbye
    <p>Test</p>
  </div>
</div>

We can also select an element on the page and insert it into another:

$('h2').append($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
  <h2>Greetings</h2>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Example:

Appends all spans to the element with the ID "foo"

<!DOCTYPE html>
<html>
<head>
  <style>#foo { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>I have nothing more to say... </span>

  <div id="foo">FOO! </div>
<script>$("span").appendTo("#foo"); // check append() examples</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .appendTo().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • R-Enemy
    This may be a noob question, but I haven't been able to find a good answer.

    By using appendTo, can you access the element later with jQuery("#id")?

    Example:
    <div id="container"></div>
    <script>
    $("<div/>",{id:'div1'}).appendTo("#container");
    $("#div1").html('Hello'); //does this work?
    </script>

    I've had issues with this:
    <script>
    $("#container").html('<div id="div1"></div>");
    $("#div1").html("Hello"); //fails
    </script>

    I'm guessing the latter approach fails because div1 doesn't really exist in the DOM. So, the root of my question: Does appendTo() or append() add the element/html to the DOM?
  • Aivo Paas
    Where the doc says:
    We can also select an element on the page and insert it into another:
    $('h2').append($('.container'));

    There should be:
    $('h2').appendTo($('.container'));

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.prepend() – jQuery API

jQuery API

Skip to content
  • api

.prepend()

Categories: Manipulation > DOM Insertion, Inside

.prepend( content ) Returns: jQuery

Description: Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.

  • version added: 1.0.prepend( content )

    contentAn element, HTML string, or jQuery object to insert at the beginning of each element in the set of matched elements.

  • version added: 1.4.prepend( function(index, html) )

    function(index, html)A function that returns an HTML string to insert at the beginning of each element in the set of matched elements. Receives the index position of the element in the set and the old HTML value of the element as arguments.

The .prepend() and .prependTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .prepend(), the selector expression preceding the method is the container into which the content is inserted. With .prependTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once:

$('.inner').prepend('<p>Test</p>');

Each <div class="inner"> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    <p>Test</p>
    Hello
  </div>
  <div class="inner">
    <p>Test</p>
    Goodbye
  </div>
</div>

We can also select an element on the page and insert it into another:

$('.container').prepend($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Examples:

Example: Prepends some HTML to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>there friend!</p>

  <p>amigo!</p>
<script>$("p").prepend("<b>Hello </b>");</script>
</body>
</html>

Demo:

Example: Prepends a DOM Element to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>is what I'd say</p>
  <p>is what I said</p>
<script>$("p").prepend(document.createTextNode("Hello "));</script>
</body>
</html>

Demo:

Example: Prepends a jQuery object (similar to an Array of DOM Elements) to all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p> is what was said.</p><b>Hello</b>
<script>$("p").prepend( $("b") );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .prepend().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • drumania
    YEAH! now comments!

    sory , is too much exciting!! ja

    I love jquery!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.prependTo() – jQuery API

jQuery API

Skip to content
  • api

.prependTo()

Categories: Manipulation > DOM Insertion, Inside

.prependTo( target ) Returns: jQuery

Description: Insert every element in the set of matched elements to the beginning of the target.

  • version added: 1.0.prependTo( target )

    targetA selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the beginning of the element(s) specified by this parameter.

The .prepend() and .prependTo() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .prepend(), the selector expression preceding the method is the container into which the content is inserted. With .prependTo(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.

Consider the following HTML:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once:

$('<p>Test</p>').prependTo('.inner');

Each inner <div> element gets this new content:

<h2>Greetings</h2>
<div class="container">
  <div class="inner">
    <p>Test</p>
    Hello
  </div>
  <div class="inner">
    <p>Test</p>
    Goodbye
  </div>
</div>

We can also select an element on the page and insert it into another:

$('h2').prependTo($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Example:

Prepends all spans to the element with the ID "foo"

<!DOCTYPE html>
<html>
<head>
  <style>div { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="foo">FOO!</div>

  <span>I have something to say... </span>
<script>$("span").prependTo("#foo"); // check prepend() examples</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .prependTo().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Insertion, Outside – jQuery API

jQuery API

Skip to content
  • api

DOM Insertion, Outside

These methods allow us to insert new content outside an existing element.

  • .after()

    Insert content, specified by the parameter, after each element in the set of matched elements.

  • .before()

    Insert content, specified by the parameter, before each element in the set of matched elements.

  • .insertAfter()

    Insert every element in the set of matched elements after the target.

  • .insertBefore()

    Insert every element in the set of matched elements before the target.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.after() – jQuery API

jQuery API

Skip to content
  • api

.after()

Categories: Manipulation > DOM Insertion, Outside

.after( content ) Returns: jQuery

Description: Insert content, specified by the parameter, after each element in the set of matched elements.

  • version added: 1.0.after( content )

    contentAn element, HTML string, or jQuery object to insert after each element in the set of matched elements.

  • version added: 1.4.after( function )

    functionA function that returns an HTML string to insert after each element in the set of matched elements.

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once:

$('.inner').after('<p>Test</p>');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
  <p>Test</p>
</div>

We can also select an element on the page and insert it after another:

$('.container').after($('h2'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned):

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

In jQuery 1.4 before and after will also work on disconnected DOM nodes. For example if you were to do:

$("
").after"
");

Then you would end up with a jQuery set that contains a div and a paragraph (in that order).

Examples:

Example: Inserts some HTML after all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>I would like to say: </p>
<script>$("p").after("<b>Hello</b>");</script>
</body>
</html>

Demo:

Example: Inserts a DOM element after all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>I would like to say: </p>
<script>$("p").after( document.createTextNode("Hello") );</script>
</body>
</html>

Demo:

Example: Inserts a jQuery object (similar to an Array of DOM Elements) after all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <b>Hello</b><p>I would like to say: </p>
<script>$("p").after( $("b") );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .after().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.before() – jQuery API

jQuery API

Skip to content
  • api

.before()

Categories: Manipulation > DOM Insertion, Outside

.before( content ) Returns: jQuery

Description: Insert content, specified by the parameter, before each element in the set of matched elements.

  • version added: 1.0.before( content )

    contentAn element, HTML string, or jQuery object to insert before each element in the set of matched elements.

  • version added: 1.4.before( function )

    functionA function that returns an HTML string to insert before each element in the set of matched elements.

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once:

$('.inner').before('<p>Test</p>');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <p>Test</p>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another:

$('.container').before($('h2'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned):

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

In jQuery 1.4 before and after will also work on disconnected DOM nodes. For example if you were to do:

$("
").before("
");

Then you would end up with a jQuery set that contains a paragraph and a div (in that order).

Examples:

Example: Inserts some HTML before all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p> is what I said...</p>
<script>$("p").before("<b>Hello</b>");</script>
</body>
</html>

Demo:

Example: Inserts a DOM element before all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p> is what I said...</p>
<script>$("p").before( document.createTextNode("Hello") );</script>
</body>
</html>

Demo:

Example: Inserts a jQuery object (similar to an Array of DOM Elements) before all paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p> is what I said...</p><b>Hello</b>
<script>$("p").before( $("b") );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .before().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.insertAfter() – jQuery API

jQuery API

Skip to content
  • api

.insertAfter()

Categories: Manipulation > DOM Insertion, Outside

.insertAfter( target ) Returns: jQuery

Description: Insert every element in the set of matched elements after the target.

  • version added: 1.0.insertAfter( target )

    targetA selector, element, HTML string, or jQuery object; the matched set of elements will be inserted after the element(s) specified by this parameter.

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once:

$('<p>Test</p>').insertAfter('.inner');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
  <p>Test</p>
</div>

We can also select an element on the page and insert it after another:

$('h2').insertAfter($('.container'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned):

<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Example:

Inserts all paragraphs after an element with id of "foo". Same as $("#foo").after("p")

<!DOCTYPE html>
<html>
<head>
  <style>#foo { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p> is what I said... </p><div id="foo">FOO!</div>
<script>$("p").insertAfter("#foo"); // check after() examples</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .insertAfter().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.insertBefore() – jQuery API

jQuery API

Skip to content
  • api

.insertBefore()

Categories: Manipulation > DOM Insertion, Outside

.insertBefore( target ) Returns: jQuery

Description: Insert every element in the set of matched elements before the target.

  • version added: 1.0.insertBefore( target )

    targetContent after which the selected element(s) is inserted.

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.

Consider the following HTML:

<div class="container">
  <h2>Greetings</h2>
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once:

$('<p>Test</p>').insertBefore('.inner');

Each inner <div> element gets this new content:

<div class="container">
  <h2>Greetings</h2>
  <p>Test</p>
  <div class="inner">Hello</div>
  <p>Test</p>
  <div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another:

$('h2').insertBefore($('.container'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned):

<h2>Greetings</h2>
<div class="container">
  <div class="inner">Hello</div>
  <div class="inner">Goodbye</div>
</div>

If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.

Example:

Inserts all paragraphs before an element with id of "foo". Same as $("#foo").before("p")

<!DOCTYPE html>
<html>
<head>
  <style>#foo { background:yellow; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="foo">FOO!</div><p>I would like to say: </p>
<script>$("p").insertBefore("#foo"); // check before() examples</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .insertBefore().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Removal – jQuery API

jQuery API

Skip to content
  • api

DOM Removal

These methods allow us to delete elements from the DOM.

  • .detach()

    Remove the set of matched elements from the DOM.

  • .empty()

    Remove all child nodes of the set of matched elements from the DOM.

  • .remove()

    Remove the set of matched elements from the DOM.

  • .unwrap()

    DOM Insertion, Around

    Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.detach() – jQuery API

jQuery API

Skip to content
  • api

.detach()

Categories: Manipulation > DOM Removal

.detach( [ selector ] ) Returns: jQuery

Description: Remove the set of matched elements from the DOM.

  • version added: 1.4.detach( [ selector ] )

    selectorA selector expression that filters the set of matched elements to be removed.

The .detach() method is the same as .remove(), except that .detach() keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.

Example:

Detach all paragraphs from the DOM

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; margin:6px 0; } p.off { background: black; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  how are
  <p>you?</p>
  <button>Attach/detach paragraphs</button>
<script>
    $("p").click(function(){
      $(this).toggleClass("off");
    });
    var p;
    $("button").click(function(){
      if ( p ) {
        p.appendTo("body");
        p = null;
      } else {
        p = $("p").detach();
      }
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .detach().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Lê Thanh Sang
    This is a very great function. I finding that function very long time ago :">.
  • sunsean
    .detach() is possibly the best function added in 1.4
    This allows removing elements from the DOM without destroying them which opens up large possibilities for keeping a clean DOM structure which helps the browser stay fast.
  • Antonio Ramirez Cobos
    grrrreat!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.empty() – jQuery API

jQuery API

Skip to content
  • api

.empty()

Categories: Manipulation > DOM Removal

.empty() Returns: jQuery

Description: Remove all child nodes of the set of matched elements from the DOM.

  • version added: 1.0.empty()

This method removes not only child (and other descendant) elements, but also any text within the set of matched elements. This is because, according to the DOM specification, any string of text within an element is considered a child node of that element. Consider the following HTML:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

We can target any element for removal:

$('.hello').empty();

This will result in a DOM structure with the Hello text deleted:

<div class="container">
  <div class="hello"></div>
  <div class="goodbye">Goodbye</div>
</div>

If we had any number of nested elements inside <div class="hello">, they would be removed, too. Other jQuery constructs such as data or event handlers are erased as well.

Example:

Removes all child nodes (including text nodes) from all paragraphs

<!DOCTYPE html>
<html>
<head>
  <style>
  p { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    Hello, <span>Person</span> <a href="javascript:;">and person</a>
  </p>

  <button>Call empty() on above paragraph</button>
<script>
    $("button").click(function () {
      $("p").empty();
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .empty().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.remove() – jQuery API

jQuery API

Skip to content
  • api

.remove()

Categories: Manipulation > DOM Removal

.remove( [ selector ] ) Returns: jQuery

Description: Remove the set of matched elements from the DOM.

  • version added: 1.0.remove( [ selector ] )

    selectorA selector expression that filters the set of matched elements to be removed.

Similar to .empty(), the .remove() method takes elements out of the DOM. We use .remove() when we want to remove the element itself, as well as everything inside it. In addition to the elements themselves, all bound events and jQuery data associated with the elements are removed.

Consider the following HTML:

<div class="container">
  <div class="hello">Hello</div>
  <div class="goodbye">Goodbye</div>
</div>

We can target any element for removal:

$('.hello').remove();

This will result in a DOM structure with the <div> element deleted:

<div class="container">
  <div class="goodbye">Goodbye</div>
</div>

If we had any number of nested elements inside <div class="hello">, they would be removed, too. Other jQuery constructs such as data or event handlers are erased as well.

We can also include a selector as an optional parameter. For example, we could rewrite the previous DOM removal code as follows:

$('div').remove('.hello');

This would result in the same DOM structure:

<div class="container">
  <div class="goodbye">Goodbye</div>
</div>

Examples:

Example: Removes all paragraphs from the DOM

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; margin:6px 0; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  how are
  <p>you?</p>
  <button>Call remove() on paragraphs</button>
<script>
    $("button").click(function () {
      $("p").remove();
    });

</script>
</body>
</html>

Demo:

Example: Removes all paragraphs that contain "Hello" from the DOM

<!DOCTYPE html>
<html>
<head>
  <style>p { background:yellow; margin:6px 0; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p class="hello">Hello</p>
  how are
  <p>you?</p>

  <button>Call remove(":contains('Hello')") on paragraphs</button>
<script>

    $("button").click(function () {
      $("p").remove(":contains('Hello')");
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .remove().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Replacement – jQuery API

jQuery API

Skip to content
  • api

DOM Replacement

These methods are used to remove content from the DOM and replace it with new content.

  • .replaceAll()

    A selector expression indicating which element(s) to replace.

  • .replaceWith()

    Replace each element in the set of matched elements with the provided new content.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.replaceAll() – jQuery API

jQuery API

Skip to content
  • api

.replaceAll()

Categories: Manipulation > DOM Replacement

.replaceAll() Returns: jQuery

Description: Replace each target element with the set of matched elements.

  • version added: 1.2.replaceAll()

The .replaceAll() method is corollary to .replaceWith(), but with the source and target reversed. Consider this DOM structure:

<div class="container">
  <div class="inner first">Hello</div>
  <div class="inner second">And</div>
  <div class="inner third">Goodbye</div>
</div>

We can create an element, then replace other elements with it:

$('<h2>New heading</h2>').replaceAll('.inner');

This causes all of them to be replaced:

<div class="container">
  <h2>New heading</h2>
  <h2>New heading</h2>
  <h2>New heading</h2>
</div>

Or, we could select an element to use as the replacement:

$('.first').replaceAll('.third');

This results in the DOM structure:

<div class="container">
  <div class="inner second">And</div>
  <div class="inner first">Hello</div>
</div>

From this example, we can see that the selected element replaces the target by being moved from its old location, not by being cloned.

Example:

Replace all the paragraphs with bold words.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("<b>Paragraph. </b>").replaceAll("p"); // check replaceWith() examples</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .replaceAll().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.replaceWith() – jQuery API

jQuery API

Skip to content
  • api

.replaceWith()

Categories: Manipulation > DOM Replacement

.replaceWith( newContent ) Returns: jQuery

Description: Replace each element in the set of matched elements with the provided new content.

  • version added: 1.2.replaceWith( newContent )

    newContentThe content to insert. May be an HTML string, DOM element, or jQuery object.

  • version added: 1.4.replaceWith( function )

    functionA function that returns an HTML string to replace the set of matched elements with.

The .replaceWith() method allows us to remove content from the DOM and insert new content in its place with a single call. Consider this DOM structure:

<div class="container">
  <div class="inner first">Hello</div>
  <div class="inner second">And</div>
  <div class="inner third">Goodbye</div>
</div>

We can replace the second inner <div> with specified HTML:

$('.second').replaceWith('<h2>New heading</h2>');

This results in the structure:

<div class="container">
  <div class="inner first">Hello</div>
  <h2>New heading</h2>
  <div class="inner third">Goodbye</div>
</div>

We could equally target all inner <div> elements at once:

$('.inner').replaceWith('<h2>New heading</h2>');

This causes all of them to be replaced:

<div class="container">
  <h2>New heading</h2>
  <h2>New heading</h2>
  <h2>New heading</h2>
</div>

Or, we could select an element to use as the replacement:

$('.third').replaceWith($('.first'));

This results in the DOM structure:

<div class="container">
  <div class="inner second">And</div>
  <div class="inner first">Hello</div>
</div>

From this example, we can see that the selected element replaces the target by being moved from its old location, not by being cloned.

The .replaceWith() method, like most jQuery methods, returns the jQuery object so that other methods can be chained onto it. However, it must be noted that the original jQuery object is returned. This object refers to the element that has been removed from the DOM, not the new element that has replaced it.

In jQuery 1.4 replaceWith, before, and after will also work on disconnected DOM nodes. For example if you were to do:

$("
").replaceWith("
");

Then you would end up with a jQuery set that contains only a paragraph.

Examples:

Example: On click, replace the button with a div containing the same word.

<!DOCTYPE html>
<html>
<head>
  <style>
  button { display:block; margin:3px; color:red; width:200px; }
  div { color:red; border:2px solid blue; width:200px;
        margin:3px; text-align:center; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>First</button>
  <button>Second</button>

  <button>Third</button>
<script>

    $("button").click(function () {
      $(this).replaceWith("<div>" + $(this).text() + "</div>");
    });
</script>
</body>
</html>

Demo:

Example: Replace all the paragraphs with bold words.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>

  <p>World</p>
<script>$("p").replaceWith("<b>Paragraph. </b>");</script>
</body>
</html>

Demo:

Example: Replace all the paragraphs with empty div elements.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { border:2px solid blue; margin:3px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").replaceWith(document.createElement("div"));</script>
</body>
</html>

Demo:

Example: On click, replace each paragraph with a jQuery div object that is already in the DOM. Notice it doesn't clone the object but rather moves it to replace the paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { border:2px solid blue; color:red; margin:3px; }
  p { border:2px solid red; color:blue; margin:3px; cursor:pointer; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
  <p>cruel</p>
  <p>World</p>

  <div>Replaced!</div>
<script>
    $("p").click(function () {
      $(this).replaceWith($("div"));
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .replaceWith().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • kolRmba
    It's very unespectable that "replaceWith" returns deleted element, not replacement.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


General Attributes – jQuery API

jQuery API

Skip to content
  • api

General Attributes

These methods get and set DOM attributes of elements

  • .attr()

    Attributes

    Get the value of an attribute for the first element in the set of matched elements.

  • .removeAttr()

    Attributes

    Remove an attribute from each element in the set of matched elements.

  • .text()

    Attributes, DOM Insertion, Inside

    Get the combined text contents of each element in the set of matched elements, including their descendants.

  • .val()

    Attributes, Forms

    Get the current value of the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Style Properties – jQuery API

jQuery API

Skip to content
  • api

Style Properties

These methods get and set CSS-related properties of elements.

  • .css()

    CSS

    Get the value of a style property for the first element in the set of matched elements.

  • .height()

    CSS, Dimensions

    Get the current computed height for the first element in the set of matched elements.

  • .innerHeight()

    CSS, Dimensions

    Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • .innerWidth()

    CSS, Dimensions

    Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • .offset()

    CSS, Offset

    Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • .outerHeight()

    CSS, Dimensions

    Get the current computed height for the first element in the set of matched elements, including padding and border.

  • .outerWidth()

    CSS, Dimensions

    Get the current computed width for the first element in the set of matched elements, including padding and border.

  • .position()

    CSS, Offset

    Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • .scrollLeft()

    CSS, Offset

    Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • .scrollTop()

    CSS, Offset

    Get the current vertical position of the scroll bar for the first element in the set of matched elements.

  • .width()

    CSS, Dimensions

    Get the current computed width for the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Miscellaneous – jQuery API

jQuery API

Skip to content
  • api

Miscellaneous

  • .data()

    Data Storage

    Store arbitrary data associated with the matched elements.

  • .each()

    Collection Manipulation

    Iterate over a jQuery object, executing a function for each matched element.

  • .get()

    DOM Element Methods

    Retrieve the DOM elements matched by the jQuery object.

  • .index()

    DOM Element Methods

    Search for a given element from among the matched elements.

  • jQuery.noConflict()

    Core, Setup Methods

    Relinquish jQuery's control of the $ variable.

  • jQuery.param()

    Collection Manipulation, Forms, Helper Functions

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • .removeData()

    Data Storage

    Remove a previously-stored piece of data.

  • .size()

    DOM Element Methods

    Return the number of DOM elements matched by the jQuery object.

  • .toArray()

    DOM Element Methods

    Retrieve all the DOM elements contained in the jQuery set, as an array.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Collection Manipulation – jQuery API

jQuery API

Skip to content
  • api

Collection Manipulation

  • .each()

    Iterate over a jQuery object, executing a function for each matched element.

  • jQuery.param()

    Forms, Helper Functions

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.each() – jQuery API

jQuery API

Skip to content
  • api

.each()

Categories: Miscellaneous > Collection Manipulation

.each( function(index, Element) ) Returns: jQuery

Description: Iterate over a jQuery object, executing a function for each matched element.

  • version added: 1.0.each( function(index, Element) )

    function(index, Element)A function to execute for each matched element.

The .each() method is designed to make DOM looping constructs concise and less error-prone. When called it iterates over the DOM elements that are part of the jQuery object. Each time the callback runs, it is passed the current loop iteration, beginning from 0. More importantly, the callback is fired in the context of the current DOM element, so the keyword this refers to the element.

Suppose we had a simple unordered list on the page:

<ul>
    <li>foo</li>
    <li>bar</li>
  </ul>

We can select the list items and iterate across them:

$('li').each(function(index) {
    alert(index + ': ' + $(this).text());
  });

A message is thus alerted for each item in the list:

0: foo
1: bar

We can stop the loop from within the callback function by returning false.

Examples:

Example: Iterates over three divs and sets their color property.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:red; text-align:center; cursor:pointer;
        font-weight:bolder; width:300px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>Click here</div>

  <div>to iterate through</div>
  <div>these divs.</div>
<script>
    $(document.body).click(function () {
      $("div").each(function (i) {
        if (this.style.color != "blue") {
          this.style.color = "blue";
        } else {
          this.style.color = "";
        }
      });
    });</script>
</body>
</html>

Demo:

Example: If you want to have the jQuery object instead of the regular DOM element, use the $(this) function, for example:

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { font-size:18px; margin:0; }
  span { color:blue; text-decoration:underline; cursor:pointer; }
  .example { font-style:italic; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    To do list: <span>(click here to change)</span>
  <ul>
    <li>Eat</li>
    <li>Sleep</li>

    <li>Be merry</li>
  </ul>
<script>
    $("span").click(function () {
      $("li").each(function(){
        $(this).toggleClass("example");
      });
    });

</script>
</body>
</html>

Demo:

Example: You can use 'return' to break out of each() loops early.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:40px; height:40px; margin:5px; float:left;
        border:2px blue solid; text-align:center; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Change colors</button>
  <span></span>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div id="stop">Stop here</div>
  <div></div>

  <div></div>
  <div></div>
<script>
    $("button").click(function () {
      $("div").each(function (index, domEle) {
        // domEle == this
        $(domEle).css("backgroundColor", "yellow");
        if ($(this).is("#stop")) {
          $("span").text("Stopped at div index #" + index);
          return false;
        }
      });
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .each().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Data Storage – jQuery API

jQuery API

Skip to content
  • api

Data Storage

These methods allow us to associate arbitrary data with specific DOM elements.

  • .data()

    Store arbitrary data associated with the matched elements.

  • .removeData()

    Remove a previously-stored piece of data.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.data() – jQuery API

jQuery API

Skip to content
  • api

.data()

Categories: Miscellaneous > Data Storage
Contents:
  • data( key, value )
    • .data( key, value )
    • .data( obj )
  • data( key )
    • .data( key )
    • .data()

.data( key, value ) Returns: jQuery

Description: Store arbitrary data associated with the matched elements.

  • version added: 1.2.3.data( key, value )

    keyA string naming the piece of data to set.

    valueThe new data value.

  • version added: 1.4.data( obj )

    objAn object of key-value pairs of data to set.

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks.

We can set several distinct values for a single element and retrieve them later:

$('body').data('foo', 52);
$('body').data('bar', 'test');

$('body').data('foo'); // 52
$('body').data(); // {foo: 52, bar: test}

If we set an element's data using an object, all data previously stored with that element is overridden. Because this data includes events that have been bound to the element, we should use caution when setting .data() with an object.

$('body').data('foo', 52);
$('body').data({one: 1, two: 2});

$('body').data('foo'); // undefined
$('body').data(); // {one: 1, two: 2}

Example:

Store then retrieve a value from the div element.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    The values stored were
    <span></span>
    and
    <span></span>
  </div>
<script>
$("div").data("test", { first: 16, last: "pizza!" });
$("span:first").text($("div").data("test").first);
$("span:last").text($("div").data("test").last);
</script>
</body>
</html>

Demo:

.data( key ) Returns: Object

Description: Returns value at named data store for the element, as set by data(name, value).

  • version added: 1.2.3.data( key )

    keyName of the data stored.

  • version added: 1.4.data()

The .data() method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:

alert($('body').data('foo'));
alert($('body').data());

The above lines alert the data values that were set on the body element. If nothing was set on that element, an empty string is returned:

Calling .data() with no parameters retrieves all of the values as a JavaScript object.

Example:

Get the data named "blah" stored at for an element.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:5px; background:yellow; }
  button { margin:5px; font-size:14px; }
  p { margin:5px; color:blue; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>A div</div>
  <button>Get "blah" from the div</button>
  <button>Set "blah" to "hello"</button>

  <button>Set "blah" to 86</button>
  <button>Remove "blah" from the div</button>
  <p>The "blah" value of this div is <span>?</span></p>
<script>
$("button").click(function(e) {
  var value;

  switch ($("button").index(this)) {
    case 0 :
      value = $("div").data("blah");
      break;
    case 1 :
      $("div").data("blah", "hello");
      value = "Stored!";
      break;
    case 2 :
      $("div").data("blah", 86);
      value = "Stored!";
      break;
    case 3 :
      $("div").removeData("blah");
      value = "Removed!";
      break;
  }

  $("span").text("" + value);
});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .data().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Peter
    I too am confused about the presence of event handlers on the data object. I have used data() in the past as a way to associate some data with the UI representation of that data. GUI toolkits often give you this sort of extra property (like "Tag" in .NET WinForms). I do like the idea of being able to get or set all event handlers through this kind of object, but I'm unclear why they, and not other, properties are included. And mainly I'm just concerned that I will overwrite event handlers when I use "data" for what I thought was its intended purpose -- to allow a developer to associate some bit of model data with its UI. For example, in a handler, I might find out which behind-the-scenes object a particular element represents because I cached a reference to it (or an ID, etc), in the data property.
  • question
    The following moment is very interesting. Can anybody comment it?

    // Alert doesn't work
    $('<div>click me</div>').click( function(){alert('where?')} ).data( {key: 'val'} ).appendTo( 'body' );
    //Alert
    $('<div>click me!</div>').click( function(){alert('there!')} ).data('key','val').appendTo( 'body' );

    Why is it happened?
  • Jason Lengstorf
    That's definitely strange behavior. If you swap the order of the method calls, it works as expected:

    $('<div>click me</div>')
    .data( {key: 'val'} )
    .bind("click", function(){alert('where: '+$(this).data("key"))} )
    .appendTo( 'body' );

    But adding data after binding causes the alert to fail:

    $('<div>click me</div>')
    .bind("click", function(){alert('where: '+$(this).data("key"))} ) // doesn't work
    .data( {key: 'val'} )
    .appendTo( 'body' );
  • question
    Ok, I've understand the cause of it:

    If we set an element's data using an object, all data previously stored with that element is overridden. Because this data includes events that have been bound to the element, we should use caution when setting .data() with an object.
  • Sebastian B.
    I agree to helianthus.

    But special data properties like .events should IMO rather be hidden from data() methods. Or are there use cases where .events needs to be read/written?

    If yes .events (and any other special properties, if there are any) should be documented here (along with some use cases) to make them part of the official, stable API.
  • Senamion
    I used $.data(this) to get the unique id of an element. With 1.4 is not possible, what can i use instead?
  • dude
    Do you mean something like this: this.id
  • Loïc
    I make the same use of $.data(), most of the time for other js libraries working only with dom elements identified by their #id while my dom elements don't have any since they are generated on the fly.
    Maybe there is another way to do the job if the "unique id way" is not the right one, any suggestion ?
    Thanks a lot for 1.4 !
    Loïc
  • helianthus
    I would like to know all the reserved keys used by jQuery internally, like "events", so that I will not accidentally overwrite them.
    By the way wouldn't it be better if we cannot overwrite them, or at least having them prefixed with something like underscores (eg. "__events"), so that we do not have to be aware of them?
  • Bob
    I've found that you can cache the data "object" and have its contents persist through other parts of the code. What I mean is that if you have one function in your javascript modifying your data like so:

    var data = $('#dataElement').data('data');
    data.param = 'value';
    data.arg = 'argument';

    Then the contents of data will be the same immediately after doing this through caching. If you have another function in your javascript that executes later and does this:

    var param = $('#dataElement').data('data').param;

    You are guaranteed that param == 'value' will be true. However, what I'm wondering is that if you cache data and modify the cached variable, instead of calling .data(), will this improve performance?

    If it does improve performance, caching .data() would be important in places in your code where you call .data() often.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.removeData() – jQuery API

jQuery API

Skip to content
  • api

.removeData()

Categories: Miscellaneous > Data Storage

.removeData( [ name ] ) Returns: jQuery

Description: Remove a previously-stored piece of data.

  • version added: 1.2.3.removeData( [ name ] )

    nameA string naming the piece of data to delete.

The .removeData() method allows us to remove values that were previously set using .data(). When called with the name of a key, .removeData() deletes that particular value; when called with no arguments, all values are removed.

Example:

Set a data store for 2 names then remove one of them.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { margin:2px; color:blue; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>value1 before creation: <span></span></div>
  <div>value1 after creation: <span></span></div>
  <div>value1 after removal: <span></span></div>

  <div>value2 after removal: <span></span></div>
<script>

    $("span:eq(0)").text("" + $("div").data("test1"));
    $("div").data("test1", "VALUE-1");
    $("div").data("test2", "VALUE-2");
    $("span:eq(1)").text("" + $("div").data("test1"));
    $("div").removeData("test1");
    $("span:eq(2)").text("" + $("div").data("test1"));
    $("span:eq(3)").text("" + $("div").data("test2"));

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .removeData().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


DOM Element Methods – jQuery API

jQuery API

Skip to content
  • api

DOM Element Methods

  • .get()

    Retrieve the DOM elements matched by the jQuery object.

  • .index()

    Search for a given element from among the matched elements.

  • .size()

    Return the number of DOM elements matched by the jQuery object.

  • .toArray()

    Retrieve all the DOM elements contained in the jQuery set, as an array.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.get() – jQuery API

jQuery API

Skip to content
  • api

.get()

Categories: Miscellaneous > DOM Element Methods

.get( [ index ] ) Returns: Element, Array

Description: Retrieve the DOM elements matched by the jQuery object.

  • version added: 1.0.get( [ index ] )

    indexA zero-based integer indicating which element to retrieve.

The .get() method grants us access to the DOM nodes underlying each jQuery object. Suppose we had a simple unordered list on the page:

<ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
</ul>

Without a parameter, .get() returns all of the elements:

alert($('li').get());

All of the matched DOM nodes are returned by this call, contained in a standard array:

[<li id="foo">, <li id="bar">]

With an index specified, .get() will retrieve a single element:

($('li').get(0));

Since the index is zero-based, the first list item is returned:

<li id="foo">

Each jQuery object also masquerades as an array, so we can use the array dereferencing operator to get at the list item instead:

alert($('li')[0]);

However, this syntax lacks some of the additional capabilities of .get(), such as specifying a negative index:

alert($('li').get(-1));

A negative index is counted from the end of the matched set, so this example will return the last item in the list:

<li id="bar">

Examples:

Example: Selects all divs in the document and returns the DOM Elements as an Array, then uses the built-in reverse-method to reverse that array.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Reversed - <span></span>

  <div>One</div>
  <div>Two</div>
  <div>Three</div>
<script>

    function disp(divs) {
      var a = [];
      for (var i = 0; i < divs.length; i++) {
        a.push(divs[i].innerHTML);
      }
      $("span").text(a.join(" "));
    }

    disp( $("div").get().reverse() );
</script>
</body>
</html>

Demo:

Example: Gives the tag name of the element clicked on.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { color:red; }
  div { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>&nbsp;</span>
  <p>In this paragraph is an <span>important</span> section</p>

  <div><input type="text" /></div>
<script>

    $("*", document.body).click(function (e) {
      e.stopPropagation();
      var domEl = $(this).get(0);
      $("span:first").text("Clicked on - " + domEl.tagName);
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .get().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.index() – jQuery API

jQuery API

Skip to content
  • api

.index()

Categories: Miscellaneous > DOM Element Methods

.index( ) Returns: Number

Description: Search for a given element from among the matched elements.

  • version added: 1.4.index()

  • version added: 1.4.index( selector )

    selectorA selector representing a jQuery collection in which to look for an element.

  • version added: 1.0.index( element )

    elementThe DOM element or first element within the jQuery object to look for.

Return Values

If no argument is passed to the .index() method, the return value is an integer indicating the position of the first element within the jQuery object relative to its sibling elements.

If .index() is called on a collection of elements and a DOM element or jQuery object is passed in, .index() returns an integer indicating the position of the passed element relative to the original collection.

If a selector string is passed as an argument, .index() returns an integer indicating the position of the original element relative to the elements matched by the selector. If the element is not found, .index() will return -1.

Detail

The complementary operation to .get(), which accepts an index and returns a DOM node, .index() can take a DOM node and returns an index. Suppose we have a simple unordered list on the page:

<ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>

If we retrieve one of the three list items (for example, through a DOM function or as the context to an event handler), .index() can search for this list item within the set of matched elements:

var listItem = document.getElementById('bar');
alert('Index: ' + $('li').index(listItem));
We get back the zero-based position of the list item:

Index: 1

Similarly, if we retrieve a jQuery object consisting of one of the three list items, .index() will search for that list item:

var listItem = $('#bar');
alert('Index: ' + $('li').index(listItem));

We get back the zero-based position of the list item:

Index: 1

Note that if the jQuery collection used as the .index() method's argument contains more than one element, the first element within the matched set of elements will be used.

var listItems = $('li:gt(0)');
alert('Index: ' + $('li').index(listItems));

We get back the zero-based position of the first list item within the matched set:

Index: 1

If we use a string as the .index() method's argument, it is interpreted as a jQuery selector string. The first element among the object's matched elements which also matches this selector is located.

var listItem = $('#bar');
alert('Index: ' + listItem.index('li'));

We get back the zero-based position of the list item:

Index: 1

If we omit the argument, .index() will return the position of the first element within the set of matched elements in relation to its siblings:

alert('Index: ' + $('#bar').index();

Again, we get back the zero-based position of the list item:

Index: 1

Examples:

Example: On click, returns the index (based zero) of that div in the page.

<!DOCTYPE html>
<html>
<head>
  <style>
div { background:yellow; margin:5px; }
span { color:red; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>Click a div!</span>
<div>First div</div>
<div>Second div</div>
<div>Third div</div>
<script>
$("div").click(function () {
  // this is the dom element clicked
  var index = $("div").index(this);
  $("span").text("That was div index #" + index);
});
</script>
</body>
</html>

Demo:

Example: Returns the index for the element with ID bar.

<!DOCTYPE html>
<html>
<head>
  <style>div { font-weight: bold; color: #090; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>
<div></div>
<script>var listItem = $('#bar');
    $('div').html( 'Index: ' + $('li').index(listItem) );</script>
</body>
</html>

Demo:

Example: Returns the index for the first item in the jQuery collection.

<!DOCTYPE html>
<html>
<head>
  <style>div { font-weight: bold; color: #090; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>
<div></div>
<script>var listItems = $('li:gt(0)');
$('div').html( 'Index: ' + $('li').index(listItems) );
</script>
</body>
</html>

Demo:

Example: Returns the index for the element with ID bar in relation to all <li> elements.

<!DOCTYPE html>
<html>
<head>
  <style>div { font-weight: bold; color: #090; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>
<div></div>
<script>$('div').html('Index: ' +  $('#bar').index('li') );</script>
</body>
</html>

Demo:

Example: Returns the index for the element with ID bar in relation to its siblings.

<!DOCTYPE html>
<html>
<head>
  <style>div { font-weight: bold; color: #090; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>
<div></div>
<script>var barIndex = $('#bar').index();
$('div').html( 'Index: ' +  barIndex );</script>
</body>
</html>

Demo:

Example: Returns -1, as there is no element with ID foobar.

<!DOCTYPE html>
<html>
<head>
  <style>div { font-weight: bold; color: #090; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
  <li id="foo">foo</li>
  <li id="bar">bar</li>
  <li id="baz">baz</li>
</ul>
<div></div>
<script>var foobar = $("li").index( $('#foobar') );
$('div').html('Index: ' + foobar);</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .index().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Peter
    Realy good stuff :)
  • dude
    How exactly did this change from jquery 1.3.2?
  • John Antoni
    very useful, now we'll know exactly where we are, great stuff!
  • Aleksandr Motsjonov
    .index() without parameters is very-very cool. It's so usefull! Thank you.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.size() – jQuery API

jQuery API

Skip to content
  • api

.size()

Categories: Miscellaneous > DOM Element Methods

.size() Returns: Number

Description: Return the number of DOM elements matched by the jQuery object.

  • version added: 1.0.size()

<ul>
  <li>foo</li>
  <li>bar</li>
</ul>

We can determine the number of list items by calling .size():

alert('Size: ' + $('li').size());

This will alert the count of items:

Size: 2

The .length property is a slightly faster way to get this information.

Example:

Count the divs. Click to add more.

<!DOCTYPE html>
<html>
<head>
  <style>body { cursor:pointer; }
 div { width:50px; height:30px; margin:5px; float:left; background:blue; }
 span { color:red; }
 </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span></span>

 <div></div>
<script>$(document.body).click(function () { $(document.body).append($("<div>"));
var n = $("div").size();
$("span").text("There are " + n + " divs." + "Click to add more.");}).click(); // trigger the click to start</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .size().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.toArray() – jQuery API

jQuery API

Skip to content
  • api

.toArray()

Categories: Miscellaneous > DOM Element Methods

.toArray() Returns: Array

Description: Retrieve all the DOM elements contained in the jQuery set, as an array.

  • version added: 1.4.toArray()

.toArray() returns all of the elements in the jQuery set:

alert($('li').toArray());

All of the matched DOM nodes are returned by this call, contained in a standard array:

[<li id="foo">, <li id="bar">]

Example:

Selects all divs in the document and returns the DOM Elements as an Array, then uses the built-in reverse-method to reverse that array.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Reversed - <span></span>

  <div>One</div>
  <div>Two</div>
  <div>Three</div>
<script>

    function disp(divs) {
      var a = [];
      for (var i = 0; i < divs.length; i++) {
        a.push(divs[i].innerHTML);
      }
      $("span").text(a.join(" "));
    }

    disp( $("div").toArray().reverse() );
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .toArray().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • João Henrique
    Muito bom! Jquery está cada vez melhor! =D
  • Chris Moguel
    Great additions guys ... i just ran across a situation that I can make use of this 2 days ago. I can see my code getting shorter already. Definite Plus!
  • samz
    very useful. thanks.
  • Joel
    Is this different from .get() in some way, or just another name for the same thing?
  • BBonifield
    Just some sugga!
  • John Resig
    Yep, it's identical to .get(), just a different (and more usable) name. Although, .get() takes an argument for retrieving a single element and .toArray() does not.
  • John Antoni
    big big plus! ...thanks again for this one ;-)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Setup Methods – jQuery API

jQuery API

Skip to content
  • api

Setup Methods

  • jQuery.noConflict()

    Core

    Relinquish jQuery's control of the $ variable.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Offset – jQuery API

jQuery API

Skip to content
  • api

Offset

  • .offset()

    CSS, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • .position()

    CSS, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • .scrollLeft()

    CSS, Style Properties

    Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • .scrollTop()

    CSS, Style Properties

    Get the current vertical position of the scroll bar for the first element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Plugin Authoring – jQuery API

jQuery API

Skip to content
  • api

Plugin Authoring

  • .context

    Properties of jQuery Object Instances

    The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.

  • jQuery.pushStack()

    Add a collection of DOM elements onto the jQuery stack.

  • .selector

    Properties of jQuery Object Instances

    A selector representing selector originally passed to jQuery().

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.context – jQuery API

jQuery API

Skip to content
  • api

.context

Categories: Plugin Authoring | Properties > Properties of jQuery Object Instances

context Returns: Element

Description: The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.

  • version added: 1.3context

The .live() method for binding event handlers uses this property to determine the root element to use for its event delegation needs. Plug-ins which perform similar tasks may also find the property useful.

The value of this property is typically equal to document, as this is the default context for jQuery objects if none is supplied. The context may differ if, for example, the object was created by searching within an <iframe> or XML document.

Example:

Determine the exact context used.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Context:<ul></ul>
<script>$("ul")
  .append("<li>" + $("ul").context + "</li>")
  .append("<li>" + $("ul", document.body).context.nodeName + "</li>");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .context.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.pushStack() – jQuery API

jQuery API

Skip to content
  • api

jQuery.pushStack()

Categories: Plugin Authoring

jQuery.pushStack( elements ) Returns: jQuery

Description: Add a collection of DOM elements onto the jQuery stack.

  • version added: 1.0jQuery.pushStack( elements )

    elementsAn array of elements to push onto the stack and make into a new jQuery object.

  • version added: 1.3jQuery.pushStack( elements, name, arguments )

    elementsAn array of elements to push onto the stack and make into a new jQuery object.

    nameThe name of a jQuery method that generated the array of elements.

    argumentsThe arguments that were passed in to the jQuery method (for serialization).

Example:

Add some elements onto the jQuery stack, then pop back off again.

jQuery([])
    .pushStack( document.getElementsByTagName("div") )
        .remove()
    .end();

Comments

  • Please keep comments relevant to jQuery.pushStack().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.selector – jQuery API

jQuery API

Skip to content
  • api

.selector

Categories: Plugin Authoring | Properties > Properties of jQuery Object Instances

selector Returns: String

Description: A selector representing selector originally passed to jQuery().

  • version added: 1.3selector

Should be used in conjunction with context to determine the exact query used.

The .live() method for binding event handlers uses this property to determine how to perform its searches. Plug-ins which perform similar tasks may also find the property useful. This property contains a string representing the matched set of elements, but if DOM traversal methods have been called on the object, the string may not be a valid jQuery selector expression. For this reason, the value of .selector is generally most useful immediately following the original creation of the object. Consequently, the .live() method should only be used in this scenario.

Examples:

Example: Determine the selector used.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Some selectors:<ul></ul>
<script>$("ul")
  .append("<li>" + $("ul").selector + "</li>")
  .append("<li>" + $("ul li").selector + "</li>")
  .append("<li>" + $("div#foo ul:not([class])").selector + "</li>");

</script>
</body>
</html>

Demo:

Example: Collecting elements differently

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Some selectors:<ul></ul>

<script>
   $('<div>' + $('ul li.foo').selector + '</div>').appendTo('body');  // "ul li.foo"
   $('<div>' + $('ul').find('li').filter('.foo').selector + '</div>').appendTo('body'); // "ul li.filter(.foo)"
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Properties – jQuery API

jQuery API

Skip to content
  • api

Properties

  • jQuery.browser

    Properties of the Global jQuery Object, Utilities

    We recommend against using this property, please try to use feature detection instead (see jQuery.support). Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.

  • .context

    Plugin Authoring, Properties of jQuery Object Instances

    The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.

  • jQuery.fx.off

    Custom, Properties of the Global jQuery Object

    Globally disable all animations.

  • .length

    Properties of jQuery Object Instances

    The number of elements in the jQuery object.

  • .selector

    Plugin Authoring, Properties of jQuery Object Instances

    A selector representing selector originally passed to jQuery().

  • jQuery.support

    Properties of the Global jQuery Object, Utilities

    A collection of properties that represent the presence of different browser features or bugs.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Properties of jQuery Object Instances – jQuery API

jQuery API

Skip to content
  • api

Properties of jQuery Object Instances

Each jQuery object created with the jQuery() function contains a number of properties alongside its methods. These properties allow us to inspect various attributes of the object.

  • .context

    Plugin Authoring

    The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.

  • .length

    The number of elements in the jQuery object.

  • .selector

    Plugin Authoring

    A selector representing selector originally passed to jQuery().

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.length – jQuery API

jQuery API

Skip to content
  • api

.length

Categories: Properties > Properties of jQuery Object Instances

length Returns: Number

Description: The number of elements in the jQuery object.

  • version added: 1.0length

The number of elements currently matched. The .size() method will return the same value.

Example:

Count the divs. Click to add more.

<!DOCTYPE html>
<html>
<head>
  <style>

  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span></span>
  <div></div>
<script>$(document.body).click(function () {
      $(document.body).append($("<div>"));
      var n = $("div").length;
      $("span").text("There are " + n + " divs." +
                     "Click to add more.");
    }).trigger('click'); // trigger the click to start</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .length.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Properties of the Global jQuery Object – jQuery API

jQuery API

Skip to content
  • api

Properties of the Global jQuery Object

These properties are associated with the global jQuery object.

  • jQuery.browser

    Utilities

    We recommend against using this property, please try to use feature detection instead (see jQuery.support). Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.

  • jQuery.fx.off

    Custom

    Globally disable all animations.

  • jQuery.support

    Utilities

    A collection of properties that represent the presence of different browser features or bugs.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.browser – jQuery API

jQuery API

Skip to content
  • api

jQuery.browser

Categories: Properties > Properties of the Global jQuery Object | Utilities
Contents:
  • jQuery.browser
  • jQuery.browser.version

jQuery.browser Returns: Map

Description: We recommend against using this property, please try to use feature detection instead (see jQuery.support). Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.

  • version added: 1.0jQuery.browser

The $.browser property allows us to detect which web browser is accessing the page, as reported by the browser itself. It contains flags for each of the four most prevalent browser classes (Internet Explorer, Mozilla, Webkit, and Opera) as well as version information.

Available flags are:

  • webkit (as of jQuery 1.4)
  • safari (deprecated)
  • opera
  • msie
  • mozilla

This property is available immediately. It is therefore safe to use it to determine whether or not to call $(document).ready(). The $.browser property is deprecated in jQuery 1.3, but there are no immediate plans to remove it.

Because $.browser uses navigator.userAgent to determine the platform, it is vulnerable to spoofing by the user or misrepresentation by the browser itself. It is always best to avoid browser-specific code entirely where possible. The $.support property is available for detection of support for particular features rather than relying on $.browser.

Examples:

Example: Show the browser info.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:green; font-weight:bolder; margin:3px 0 0 10px; }
  div { color:blue; margin-left:20px; font-size:14px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Browser info:</p>
<script>
    jQuery.each(jQuery.browser, function(i, val) {
      $("<div>" + i + " : <span>" + val + "</span>")
                .appendTo(document.body);
    });</script>
</body>
</html>

Demo:

Example: Returns true if the current useragent is some version of Microsoft's Internet Explorer.

$.browser.msie

Example: Alerts "this is webkit!" only for webkit browsers

if ($.browser.webkit) {
    alert("this is webkit!");
 }

Example: Alerts "Do stuff for firefox 3" only for firefox 3 browsers.

jQuery.each(jQuery.browser, function(i, val) {
   if(i=="mozilla" && jQuery.browser.version.substr(0,3)=="1.9")
      alert("Do stuff for firefox 3")
 });

Example: Set a CSS property to specific browser.

jQuery.each(jQuery.browser, function(i) {
   if($.browser.msie){
      $("#div ul li").css("display","inline");
   }else{
      $("#div ul li").css("display","inline-table");
   }
 });

jQuery.browser.version Returns: String

Description: The version number of the rendering engine for the user's browser.

  • version added: 1.1.3jQuery.browser.version

Here are some typical results:

  • Internet Explorer: 6.0, 7.0
  • Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3, 1.9
  • Opera: 9.20
  • Safari/Webkit: 312.8, 418.9

Note that IE8 claims to be 7 in Compatibility View.

Examples:

Example: Returns the browser version.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; margin:20px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
  </p>
<script>

    $("p").html("The browser version is: <span>" +
                jQuery.browser.version + "</span>");
</script>
</body>
</html>

Demo:

Example: Alerts the version of IE that is being used

if ( $.browser.msie )
  alert( $.browser.version );
}

Example: Often you only care about the "major number," the whole number. This can be accomplished with JavaScript's built-in parseInt() function:

if (jQuery.browser.msie) {
  alert(parseInt(jQuery.browser.version));
}

Comments

  • Please keep comments relevant to jQuery.browser.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.support – jQuery API

jQuery API

Skip to content
  • api

jQuery.support

Categories: Properties > Properties of the Global jQuery Object | Utilities

jQuery.support Returns: Object

Description: A collection of properties that represent the presence of different browser features or bugs.

  • version added: 1.3jQuery.support

Rather than using $.browser to detect the current user agent and alter the page presentation based on which browser is running, it is a good practice to perform feature detection. This means that prior to executing code which relies on a browser feature, we test to ensure that the feature works properly. To make this process simpler, jQuery performs many such tests and makes the results available to us as properties of the jQuery.support object.

The values of all the support properties are determined using feature detection (and do not use any form of browser sniffing). There are some excellent resources that explain how feature detection works:

  • http://peter.michaux.ca/articles/feature-detection-state-of-the-art-browser-scripting
  • http://www.jibbering.com/faq/faq_notes/not_browser_detect.html
  • http://yura.thinkweb2.com/cft/

jQuery comes with a number of properties included, you should feel free to add your own. Many of these properties are rather low-level so it's doubtful that they'll be useful in general day-to-day development, but mostly used by plugin and core developers.

The tests included in jQuery.support are as follows:

  • boxModel: Is equal to true if the page is rendering according to the W3C CSS Box Model (is currently false in IE 6 and 7 when they are in Quirks Mode). This property is null until document ready occurs.
  • cssFloat: Is equal to true if the name of the property containing the CSS float value is .cssFloat, as defined in the CSS Spec. (It is currently false in IE, it uses styleFloat instead).
  • hrefNormalized: Is equal to true if the .getAttribute() method retrieves the href attribute of elements unchanged, rather than normalizing it to a fully-qualified URL. (It is currently false in IE, the URLs are normalized).
    DOM l3 spec
  • htmlSerialize: Is equal to true if the browser is able to serialize/insert <link> elements using the .innerHTML property of elements. (is currently false in IE).
    HTML5 wd
  • leadingWhitespace: Is equal to true if the browser inserts content with .innerHTML exactly as provided—specifically, if leading whitespace characters are preserved. (It is currently false in IE 6-8).
    HTML5 wd
  • noCloneEvent: Is equal to true if cloned DOM elements are created without event handlers (that is, if the event handlers on the source element are not cloned). (It is currently false in IE).
    DOM l2 spec
  • objectAll: Is equal to true if the .getElementsByTagName() method returns all descendant elements when called with a wildcard argument ('*'). (It is currently false in IE 7 and IE 8).
    DOM l1 spec
  • opacity: Is equal to true if a browser can properly interpret the opacity style property. (It is currently false in IE, it uses alpha filters instead).
    CSS3 spec
  • scriptEval: Is equal to true if inline scripts are automatically evaluated and executed when inserted to the document using standard DOM manipulation methods, such as appendChild() and createTextNode(). (It is currently false in IE, it uses .text to insert executable scripts).
    HTML5 WD
  • style: Is equal to true if inline styles for an element can be accessed through the DOM attribute called style, as required by the DOM Level 2 specification. In this case, .getAttribute('style') can retrieve this value; in Internet Explorer, .cssText is used for this purpose.
    DOM l2 Style spec
  • tbody: Is equal to true if a <table> element can exist without a <tbody> element. According to the HTML specification, this sub-element is optional, so the property should be true in a fully-compliant browser. If false, we must account for the possibility of the browser injecting <tbody> tags implicitly. (It is currently false in IE, which automatically inserts tbody if it is not present in a string assigned to innerHTML).
    HTML5 spec

Examples:

Example: Returns the box model for the iframe.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:blue; margin:20px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
  </p>
<script>

    $("p").html("This frame uses the W3C box model: <span>" +
                jQuery.support.boxModel + "</span>");

</script>
</body>
</html>

Demo:

Example: Returns false if the page is in QuirksMode in Internet Explorer

jQuery.support.boxModel

Result:

false

Comments

  • Please keep comments relevant to jQuery.support.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Max
    I like the idea of feature detection, but suggesting that it's the end-all-be-all solution for cross-browser compatibility just isn't accurate. How do I tell if I need to create an iframe shim over the top of form and flash elements in order to display content over form/flash elements? jQuery.support can't help with that, we have to use jQuery.browser. Or what about detecting if a browser supports html5 attributes async or defer? Have to check for browser there, too.

    A lot of people add CSS on to DOM nodes using jQuery -- that's a big use case. But while CSS interpretations vary by browser (and much more than by box model), we're not "supposed" to use jQuery to determine which browser we're running? That's just...weird.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Selectors – jQuery API

jQuery API

Skip to content
  • api

Selectors

Each action we perform with jQuery requires a target; for example, in order to hide or show an element on the page, first we must find that element. To do so, we rely on jQuery’s selector expressions.
Borrowing from CSS 1–3, and then adding its own, jQuery offers a powerful set of tools for matching a set of elements in a document. In this chapter, we’ll examine every selector expression that jQuery makes available in turn.

  • All Selector (“*”)

    Basic

    Selects all elements.

  • :animated Selector

    Basic Filter

    Select all elements that are in the progress of an animation at the time the selector is run.

  • Attribute Contains Prefix Selector [name|=value]

    Attribute

    Selects elements that have the specified attribute with a value either equal to a given string or starting with that string followed by a hyphen (-).

  • Attribute Contains Selector [name*=value]

    Attribute

    Selects elements that have the specified attribute with a value containing the a given substring.

  • Attribute Contains Word Selector [name~=value]

    Attribute

    Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.

  • Attribute Ends With Selector [name$=value]

    Attribute

    Selects elements that have the specified attribute with a value ending exactly with a given string.

  • Attribute Equals Selector [name=value]

    Attribute

    Selects elements that have the specified attribute with a value exactly equal to a certain value.

  • Attribute Not Equal Selector [name!=value]

    Attribute

    Select elements that either don't have the specified attribute, or do have the specified attribute but not with a certain value.

  • Attribute Starts With Selector [name^=value]

    Attribute

    Selects elements that have the specified attribute with a value beginning exactly with a given string.

  • :button Selector

    Form

    Selects all button elements and elements of type button.

  • :checkbox Selector

    Form

    Selects all elements of type checkbox.

  • :checked Selector

    Form

    Matches all elements that are checked.

  • Child Selector (“parent > child”)

    Hierarchy

    Selects all direct child elements specified by "child" of elements specified by "parent".

  • Class Selector (“.class”)

    Basic

    Selects all elements with the given class.

  • :contains() Selector

    Content Filter

    Select all elements that contain the specified text.

  • Descendant Selector (“ancestor descendant”)

    Hierarchy

    Selects all elements that are descendants of a given ancestor.

  • :disabled Selector

    Form

    Selects all elements that are disabled.

  • Element Selector (“element”)

    Basic

    Selects all elements with the given tag name.

  • :empty Selector

    Content Filter

    Select all elements that have no children (including text nodes).

  • :enabled Selector

    Form

    Selects all elements that are enabled.

  • :eq() Selector

    Basic Filter

    Select the element at index n within the matched set.

  • :even Selector

    Basic Filter

    Selects even elements, zero-indexed. See also odd.

  • :file Selector

    Form

    Selects all elements of type file.

  • :first-child Selector

    Child Filter

    Selects all elements that are the first child of their parent.

  • :first Selector

    Basic Filter

    Selects the first matched element.

  • :gt() Selector

    Basic Filter

    Select all elements at an index greater than index within the matched set.

  • Has Attribute Selector [name]

    Attribute

    Selects elements that have the specified attribute, with any value.

  • :has() Selector

    Content Filter

    Selects elements which contain at least one element that matches the specified selector.

  • :header Selector

    Basic Filter

    Selects all elements that are headers, like h1, h2, h3 and so on.

  • :hidden Selector

    Visibility Filter

    Selects all elements that are hidden.

  • ID Selector (“#id”)

    Basic

    Selects a single element with the given id attribute.

  • :image Selector

    Form

    Selects all elements of type image.

  • :input Selector

    Form

    Selects all input, textarea, select and button elements.

  • :last-child Selector

    Child Filter

    Selects all elements that are the last child of their parent.

  • :last Selector

    Basic Filter

    Selects the last matched element.

  • :lt() Selector

    Basic Filter

    Select all elements at an index less than index within the matched set.

  • Multiple Attribute Selector [name=value][name2=value2]

    Attribute

    Matches elements that match all of the specified attribute filters.

  • Multiple Selector (“selector1, selector2, selectorN”)

    Basic

    Selects the combined results of all the specified selectors.

  • Next Adjacent Selector (“prev + next”)

    Hierarchy

    Selects all next elements matching "next" that are immediately preceded by a sibling "prev".

  • Next Siblings Selector (“prev ~ siblings”)

    Hierarchy

    Selects all sibling elements that follow after the "prev" element, have the same parent, and match the filtering "siblings" selector.

  • :not() Selector

    Basic Filter

    Selects all elements that do not match the given selector.

  • :nth-child Selector

    Child Filter

    Selects all elements that are the nth-child of their parent.

  • :odd Selector

    Basic Filter

    Selects odd elements, zero-indexed. See also even.

  • :only-child Selector

    Child Filter

    Selects all elements that are the only child of their parent.

  • :parent Selector

    Content Filter

    Select all elements that are the parent of another element, including text nodes.

  • :password Selector

    Form

    Selects all elements of type password.

  • :radio Selector

    Form

    Selects all elements of type radio.

  • :reset Selector

    Form

    Selects all elements of type reset.

  • :selected Selector

    Form

    Selects all elements that are selected.

  • :submit Selector

    Form

    Selects all elements of type submit.

  • :text Selector

    Form

    Selects all elements of type text.

  • :visible Selector

    Visibility Filter

    Selects all elements that are visible.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute – jQuery API

jQuery API

Skip to content
  • api

Attribute

The CSS specification also allows elements to be identified by their attributes. While not widely supported by browsers for the purpose of styling documents, these attribute selectors are highly useful, and jQuery allows us to employ them regardless of the browser being used.
When using any of the following attribute selectors, we should account for attributes that have multiple, space-separated values. Since these selectors see attribute values as a single string, this selector, for example, $(‘a[rel=nofollow]‘), will select Some text but not Some text.
Attribute values in selector expressions can be written as bare words or surrounded by quotation marks. Therefore, the following variations are equally correct:

bare words: $(‘a[rel=nofollow self]‘)
double quotes inside single quotes: $(‘a[rel="nofollow self"]‘)
single quotes inside double quotes: $(“a[rel='nofollow self']“)
escaped single quotes inside single quotes: $(‘a[rel=\'nofollow self\']‘)
escaped double quotes inside double quotes: $(“a[rel=\"nofollow self\"]“)

The variation you choose is generally a matter of style or convenience.

Note: In jQuery 1.3 [@attr] style selectors were removed (they were previously deprecated in jQuery 1.2). Simply remove the ‘@’ symbol from your selectors in order to make them work again.

  • Attribute Contains Prefix Selector [name|=value]

    Selects elements that have the specified attribute with a value either equal to a given string or starting with that string followed by a hyphen (-).

  • Attribute Contains Selector [name*=value]

    Selects elements that have the specified attribute with a value containing the a given substring.

  • Attribute Contains Word Selector [name~=value]

    Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.

  • Attribute Ends With Selector [name$=value]

    Selects elements that have the specified attribute with a value ending exactly with a given string.

  • Attribute Equals Selector [name=value]

    Selects elements that have the specified attribute with a value exactly equal to a certain value.

  • Attribute Not Equal Selector [name!=value]

    Select elements that either don't have the specified attribute, or do have the specified attribute but not with a certain value.

  • Attribute Starts With Selector [name^=value]

    Selects elements that have the specified attribute with a value beginning exactly with a given string.

  • Has Attribute Selector [name]

    Selects elements that have the specified attribute, with any value.

  • Multiple Attribute Selector [name=value][name2=value2]

    Matches elements that match all of the specified attribute filters.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Contains Prefix Selector [name|=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Contains Prefix Selector [name|=value]

Categories: Selectors > Attribute

attributeContainsPrefix

Sample:

version added: 1.0jQuery('[attribute|=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

This selector was introduced into the CSS specification to handle language attributes.

Example:

Finds all links with an hreflang attribute that is english.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

                         <a href="example.html" hreflang="en">Some text</a>

                          <a href="example.html" hreflang="en-UK">Some other text</a>

<script>$('a[hreflang|=en]').css('border','3px dotted green');</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Contains Prefix Selector [name|=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Contains Selector [name*=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Contains Selector [name*=value]

Categories: Selectors > Attribute

attributeContains

Sample:

version added: 1.0jQuery('[attribute*=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

This is the most generous of the jQuery attribute selectors that match against a value. It will select an element if the selector's string appears anywhere within the element's attribute value. Compare this selector with the Attribute Contains Word selector (e.g. [attr~=word]), which is more appropriate in many cases.

Example:

Finds all inputs with a name attribute that contains 'man' and sets the value with some text.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input name="man-news" />

  <input name="milkman" />
  <input name="letterman2" />
  <input name="newmilk" />
<script>$("input[name*='man']").val("has man in it!");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Contains Selector [name*=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Contains Word Selector [name~=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Contains Word Selector [name~=value]

Categories: Selectors > Attribute

attributeContainsWord

Sample:

version added: 1.0jQuery('[attribute~=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

This selector matches the test string against each word in the attribute value, where a "word" is defined as a string delimited by whitespace. The selector matches if the test string is exactly equal to any of the words.

Example:

Finds all inputs with a name attribute that contains the word 'man' and sets the value with some text.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input name="man-news" />

  <input name="milk man" />
  <input name="letterman2" />
  <input name="newmilk" />
<script>$("input[name~=man]").val("mr. man is in it!");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Contains Word Selector [name~=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Ends With Selector [name$=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Ends With Selector [name$=value]

Categories: Selectors > Attribute

attributeEndsWith

Sample:

version added: 1.0jQuery('[attribute$=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

Example:

Finds all inputs with an attribute name that ends with 'letter' and puts text in them.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input name="newsletter" />

  <input name="milkman" />
  <input name="jobletter" />
<script>$("input[name$='letter']").val("a letter");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Ends With Selector [name$=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Equals Selector [name=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Equals Selector [name=value]

Categories: Selectors > Attribute

attributeEquals

Sample:

version added: 1.0jQuery('[attribute=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

Example:

Finds all inputs with name 'newsletter' and changes the text of the span next to it.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>

    <input type="radio" name="newsletter" value="Hot Fuzz" />
    <span>name?</span>

  </div>
  <div>
    <input type="radio" name="newsletters" value="Cold Fusion" />

    <span>name?</span>
  </div>
  <div>
    <input type="radio" name="accept" value="Evil Plans" />

    <span>name?</span>
  </div>
<script>$("input[name='newsletter']").next().text(" is newsletter");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Equals Selector [name=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Not Equal Selector [name!=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Not Equal Selector [name!=value]

Categories: Selectors > Attribute

attributeNotEqual

Sample:

version added: 1.0jQuery('[attribute!=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

This selector is equivalent to :not([attr=value]).

Example:

Finds all inputs that don't have the name 'newsletter' and appends text to the span next to it.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>

    <input type="radio" name="newsletter" value="Hot Fuzz" />
    <span>name is newsletter</span>

  </div>
  <div>
    <input type="radio" value="Cold Fusion" />
    <span>no name</span>

  </div>
  <div>
    <input type="radio" name="accept" value="Evil Plans" />

    <span>name is accept</span>
  </div>
<script>$("input[name!=newsletter]").next().append("<b>; not newsletter</b>");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Not Equal Selector [name!=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Attribute Starts With Selector [name^=value] – jQuery API

jQuery API

Skip to content
  • api

Attribute Starts With Selector [name^=value]

Categories: Selectors > Attribute

attributeStartsWith

Sample:

version added: 1.0jQuery('[attribute^=value]')

  • attribute
    An attribute name.
    value
    An attribute value. Quotes are optional.

This selector can be useful for identifying elements in pages produced by server-side frameworks that produce HTML with systematic element IDs. However it will be slower than using a class selector so leverage classes, if you can, to group like elements.

Example:

Finds all inputs with an attribute name that starts with 'news' and puts text in them.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input name="newsletter" />

  <input name="milkman" />
  <input name="newsboy" />
<script>$("input[name^='news']").val("news here!");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Attribute Starts With Selector [name^=value].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Has Attribute Selector [name] – jQuery API

jQuery API

Skip to content
  • api

Has Attribute Selector [name]

Categories: Selectors > Attribute

attributeHas

Sample:

version added: 1.0jQuery('[attribute]')

  • attribute
    An attribute name.

Example:

Bind a single click that adds the div id to its text.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>no id</div>
  <div id="hey">with id</div>

  <div id="there">has an id</div>
  <div>nope</div>
<script>

    $("div[id]").one("click", function(){
      var idString = $(this).text() + " = " + $(this).attr("id");
      $(this).text(idString);
    });
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Has Attribute Selector [name].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Multiple Attribute Selector [name=value][name2=value2] – jQuery API

jQuery API

Skip to content
  • api

Multiple Attribute Selector [name=value][name2=value2]

Categories: Selectors > Attribute

attributeMultiple

Sample:

version added: 1.0jQuery('[attributeFilter1][attributeFilter2][attributeFilterN]')

  • attributeFilter1
    An attribute filter.
    attributeFilter2
    Another attribute filter, reducing the selection even more
    attributeFilterN
    As many more attribute filters as necessary

Example:

Finds all inputs that have an id attribute and whose name attribute ends with man and sets the value.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <input id="man-news" name="man-news" />

  <input name="milkman" />
  <input id="letterman" name="new-letterman" />
  <input name="newmilk" />
<script>$("input[id][name$='man']").val("only this one");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Multiple Attribute Selector [name=value][name2=value2].
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Basic – jQuery API

jQuery API

Skip to content
  • api

Basic

The following selectors are based on the Cascading Style Sheet 1 specification, as outlined by the W3C. For more information about the specifications, visit http://www.w3.org/Style/CSS/#specs.

  • All Selector (“*”)

    Selects all elements.

  • Class Selector (“.class”)

    Selects all elements with the given class.

  • Element Selector (“element”)

    Selects all elements with the given tag name.

  • ID Selector (“#id”)

    Selects a single element with the given id attribute.

  • Multiple Selector (“selector1, selector2, selectorN”)

    Selects the combined results of all the specified selectors.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


All Selector (“*”) – jQuery API

jQuery API

Skip to content
  • api

All Selector (“*”)

Categories: Selectors > Basic

all

Sample:

version added: 1.0jQuery('*')

Caution: The all, or universal, selector is extremely slow, except when used by itself.

Examples:

Example: Finds every element (including head, body, etc) in the document.

<!DOCTYPE html>
<html>
<head>
  <style>
  h3 { margin: 0; }
  div,span,p {
    width: 80px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>DIV</div>

  <span>SPAN</span>
  <p>P <button>Button</button></p>
<script>var elementCount = $("*").css("border","3px solid red").length;
$("body").prepend("<h3>" + elementCount + " elements found</h3>");</script>
</body>
</html>

Demo:

Example: A common way to select all elements is to find within document.body so elements like head, script, etc are left out.

<!DOCTYPE html>
<html>
<head>
  <style>
  h3 { margin: 0; }
  div,span,p {
    width: 80px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>DIV</div>

  <span>SPAN</span>
  <p>P <button>Button</button></p>
<script>var elementCount = $(document.body).find("*").css("border","3px solid red").length;
$("body").prepend("<h3>" + elementCount + " elements found</h3>");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to All Selector (“*”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Class Selector (“.class”) – jQuery API

jQuery API

Skip to content
  • api

Class Selector (“.class”)

Categories: Selectors > Basic

class

Sample:

version added: 1.0jQuery('.class')

  • class
    A class to search for. An element can have multiple classes; only one of them must match.

For class selectors, jQuery uses JavaScript's native getElementsByClassName() function if the browser supports it.

Examples:

Example: Finds the element with the class "myClass".

<!DOCTYPE html>
<html>
<head>
  <style>
  div,span {
    width: 100px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div class="notMe">div class="notMe"</div>

  <div class="myClass">div class="myClass"</div>
  <span class="myClass">span class="myClass"</span>
<script>$(".myClass").css("border","3px solid red");</script>
</body>
</html>

Demo:

Example: Finds the element with both "myclass" and "otherclass" classes.

<!DOCTYPE html>
<html>
<head>
  <style>
  div,span {
    width: 100px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div class=".myclass">div class="notMe"</div>

  <div class="myclass otherclass">div class="myClass"</div>
  <span class="myclass otherclass">span class="myClass"</span>
<script>$(".myclass.otherclass").css("border","13px solid red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Class Selector (“.class”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Element Selector (“element”) – jQuery API

jQuery API

Skip to content
  • api

Element Selector (“element”)

Categories: Selectors > Basic

element

Sample:

version added: 1.0jQuery('element')

  • element
    An element to search for. Refers to the tagName of DOM nodes.

JavaScript's getElementsByTagName() function is called to return the appropriate elements when this expression is used.

Example:

Finds every DIV element.

<!DOCTYPE html>
<html>
<head>
  <style>
  div,span {
    width: 60px;
    height: 60px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>DIV1</div>

  <div>DIV2</div>
  <span>SPAN</span>
<script>$("div").css("border","9px solid red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Element Selector (“element”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


ID Selector (“#id”) – jQuery API

jQuery API

Skip to content
  • api

ID Selector (“#id”)

Categories: Selectors > Basic

id

Sample:

version added: 1.0jQuery('#id')

  • id
    An ID to search for, specified via the id attribute of an element.

For id selectors, jQuery uses the JavaScript function document.getElementById(), which is extremely efficient. When another selector is attached to the id selector, such as h2#pageTitle, jQuery performs an additional check before identifying the element as a match.

Each id value must be used only once within a document. If more than one element has been assigned the same ID, queries that use that ID will only select the first matched element in the DOM. This behavior should not be relied on, however; a document with more than one element using the same ID is invalid.

If the id contains characters like periods or colons you have to escape those characters with backslashes.

As always, remember that as a developer, your time is typically the most valuable resource. Do not focus on optimization of selector speed unless it is clear that performance needs to be improved.

Examples:

Example: Finds the element with the id "myDiv".

<!DOCTYPE html>
<html>
<head>
  <style>
  div {
    width: 90px;
    height: 90px;
    float:left;
    padding: 5px;
    margin: 5px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="notMe"><p>id="notMe"</p></div>

  <div id="myDiv">id="myDiv"</div>
<script>$("#myDiv").css("border","3px solid red");</script>
</body>
</html>

Demo:

Example: Finds the element with the id "myID.entry[1]". See how certain characters must be escaped with backslashes.

<!DOCTYPE html>
<html>
<head>
  <style>
  div {
    width: 300px;
    float:left;
    padding: 2px;
    margin: 3px;
    background-color: #EEEEEE;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="myID.entry[0]">id="myID.entry[0]"</div>

  <div id="myID.entry[1]">id="myID.entry[1]"</div>
  <div id="myID.entry[2]">id="myID.entry[2]"</div>
<script>$("#myID\\.entry\\[1\\]").css("border","3px solid red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to ID Selector (“#id”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Multiple Selector (“selector1, selector2, selectorN”) – jQuery API

jQuery API

Skip to content
  • api

Multiple Selector (“selector1, selector2, selectorN”)

Categories: Selectors > Basic

multiple

Sample:

version added: 1.0jQuery('selector1, selector2, selectorN')

  • selector1
    Any valid selector.
    selector2
    Another valid selector.
    selectorN
    As many more valid selectors as you like.

You can specify any number of selectors to combine into a single result. This multiple expression combinator is an efficient way to select disparate elements. The order of the DOM elements in the returned jQuery object may not be identical, as they will be in document order. An alternative to this combinator is the .add() method.

Examples:

Example: Finds the elements that match any of these three selectors.

<!DOCTYPE html>
<html>
<head>
  <style>

  div,span,p {
    width: 126px;
    height: 60px;
    float:left;
    padding: 3px;
    margin: 2px;
    background-color: #EEEEEE;
    font-size:14px;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>div</div>

  <p class="myClass">p class="myClass"</p>
  <p class="notMyClass">p class="notMyClass"</p>
  <span>span</span>
<script>$("div,span,p.myClass").css("border","3px solid red");</script>
</body>
</html>

Demo:

Example: Show the order in the jQuery object.

<!DOCTYPE html>
<html>
<head>
  <style>
  b { color:red; font-size:16px; display:block; clear:left; }
  div,span,p { width: 40px; height: 40px; float:left;
               margin: 10px; background-color: blue;
               padding:3px; color:white;
             }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span>span</span>

  <p>p</p>
  <p>p</p>
  <div>div</div>
  <span>span</span>

  <p>p</p>
  <div>div</div>
  <b></b>
<script>
    var list = $("div,p,span").map(function () {
      return this.tagName;
    }).get().join(", ");
    $("b").append(document.createTextNode(list));
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Multiple Selector (“selector1, selector2, selectorN”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Basic Filter – jQuery API

jQuery API

Skip to content
  • api

Basic Filter

  • :animated Selector

    Select all elements that are in the progress of an animation at the time the selector is run.

  • :eq() Selector

    Select the element at index n within the matched set.

  • :even Selector

    Selects even elements, zero-indexed. See also odd.

  • :first Selector

    Selects the first matched element.

  • :gt() Selector

    Select all elements at an index greater than index within the matched set.

  • :header Selector

    Selects all elements that are headers, like h1, h2, h3 and so on.

  • :last Selector

    Selects the last matched element.

  • :lt() Selector

    Select all elements at an index less than index within the matched set.

  • :not() Selector

    Selects all elements that do not match the given selector.

  • :odd Selector

    Selects odd elements, zero-indexed. See also even.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:animated Selector – jQuery API

jQuery API

Skip to content
  • api

:animated Selector

Categories: Selectors > Basic Filter

animated

Sample:

version added: 1.2jQuery(':animated')

Example:

Change the color of any div that is animated.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { background:yellow; border:1px solid #AAA; width:80px; height:80px; margin:5px; float:left; }
  div.colored { background:green; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button id="run">Run</button>

  <div></div>
  <div id="mover"></div>
  <div></div>
<script>

    $("#run").click(function(){
      $("div:animated").toggleClass("colored");
    });
    function animateIt() {
      $("#mover").slideToggle("slow", animateIt);
    }
    animateIt();
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :animated Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:eq() Selector – jQuery API

jQuery API

Skip to content
  • api

:eq() Selector

Categories: Selectors > Basic Filter

eq

Sample:

version added: 1.0jQuery(':eq(index)')

  • index
    Zero-based index of the element to match.

The index-related selectors (:eq(), :lt(), :gt(), :even, :odd) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:eq(1)') selects the second element in the document with the class myclass, rather than the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

Example:

Finds the third td.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">
  <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
  <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>
  <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
</table>
<script>$("td:eq(2)").css("color", "red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :eq() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:even Selector – jQuery API

jQuery API

Skip to content
  • api

:even Selector

Categories: Selectors > Basic Filter

even

Sample:

version added: 1.0jQuery(':even')

In particular, note that the 0-based indexing means that, counter-intuitively, :even selects the first element, third element, and so on within the matched set.

Example:

Finds even table rows, matching the first, third and so on (index 0, 2, 4 etc.).

<!DOCTYPE html>
<html>
<head>
  <style>

  table {
    background:#eeeeee;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">
    <tr><td>Row with Index #0</td></tr>
    <tr><td>Row with Index #1</td></tr>

    <tr><td>Row with Index #2</td></tr>
    <tr><td>Row with Index #3</td></tr>
  </table>
<script>$("tr:even").css("background-color", "#bbbbff");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :even Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:first Selector – jQuery API

jQuery API

Skip to content
  • api

:first Selector

Categories: Selectors > Basic Filter

first

Sample:

version added: 1.0jQuery(':first')

The :first pseudo-class is equivalent to :eq(0). It could also be written as :lt(1). While this matches only a single element, :first-child can match more than one: One for each parent.

Example:

Finds the first table row.

<!DOCTYPE html>
<html>
<head>
  <style>

  td { color:blue; font-weight:bold; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table>
    <tr><td>Row 1</td></tr>
    <tr><td>Row 2</td></tr>

    <tr><td>Row 3</td></tr>
  </table>
<script>$("tr:first").css("font-style", "italic");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :first Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:gt() Selector – jQuery API

jQuery API

Skip to content
  • api

:gt() Selector

Categories: Selectors > Basic Filter

gt

Sample:

version added: 1.0jQuery(':gt(index)')

index-related selectors

The index-related selector expressions (including this "greater than" selector) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:gt(1)') selects elements after the second element in the document with the class myclass, rather than after the first. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

Example:

Finds TD #5 and higher. Reminder: the indexing starts at 0.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">

    <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
    <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>

    <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
  </table>
<script>$("td:gt(4)").css("text-decoration", "line-through");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :gt() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:header Selector – jQuery API

jQuery API

Skip to content
  • api

:header Selector

Categories: Selectors > Basic Filter

header

Sample:

version added: 1.2jQuery(':header')

Example:

Adds a background and text color to all the headers on the page.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { font-size: 10px; font-family: Arial; }
  h1, h2 { margin: 3px 0; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <h1>Header 1</h1>

  <p>Contents 1</p>
  <h2>Header 2</h2>
  <p>Contents 2</p>
<script>$(":header").css({ background:'#CCC', color:'blue' });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :header Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:last Selector – jQuery API

jQuery API

Skip to content
  • api

:last Selector

Categories: Selectors > Basic Filter

last

Sample:

version added: 1.0jQuery(':last')

Note that :last selects a single element by filtering the current jQuery collection and matching the last element within it.

Example:

Finds the last table row.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table>

    <tr><td>First Row</td></tr>
    <tr><td>Middle Row</td></tr>
    <tr><td>Last Row</td></tr>

  </table>
<script>$("tr:last").css({backgroundColor: 'yellow', fontWeight: 'bolder'});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :last Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:lt() Selector – jQuery API

jQuery API

Skip to content
  • api

:lt() Selector

Categories: Selectors > Basic Filter

lt

Sample:

version added: 1.0jQuery(':lt(index)')

  • index
    Zero-based index.

index-related selectors

The index-related selectors (including this "less than" selector) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (.myclass) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.

Note that since JavaScript arrays use 0-based indexing, these selectors reflect that fact. This is why $('.myclass:lt(1)') selects the first element in the document with the class myclass, rather than selecting no elements. In contrast, :nth-child(n) uses 1-based indexing to conform to the CSS specification.

Example:

Finds TDs less than the one with the 4th index (TD#4).

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">

  <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
  <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>

  <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
</table>
<script>$("td:lt(4)").css("color", "red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :lt() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:not() Selector – jQuery API

jQuery API

Skip to content
  • api

:not() Selector

Categories: Selectors > Basic Filter

not

Sample:

version added: 1.0jQuery(':not(selector)')

  • selector
    A selector with which to filter by.

All selectors are accepted inside :not(), for example: :not(div a) and :not(div,a).

Example:

Finds all inputs that are not checked and highlights the next sibling span. Notice there is no change when clicking the checkboxes since no click events have been linked.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
  <input type="checkbox" name="a" />
  <span>Mary</span>
</div>

<div>
  <input type="checkbox" name="b" />
  <span>lcm</span>

</div>
<div>
  <input type="checkbox" name="c" checked="checked" />

  <span>Peter</span>
</div>
<script>
  $("input:not(:checked) + span").css("background-color", "yellow");
  $("input").attr("disabled", "disabled");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :not() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:odd Selector – jQuery API

jQuery API

Skip to content
  • api

:odd Selector

Categories: Selectors > Basic Filter

odd

Sample:

version added: 1.0jQuery(':odd')

In particular, note that the 0-based indexing means that, counter-intuitively, :odd selects the second element, fourth element, and so on within the matched set.

Example:

Finds odd table rows, matching the second, fourth and so on (index 1, 3, 5 etc.).

<!DOCTYPE html>
<html>
<head>
  <style>

  table {
    background:#f3f7f5;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">
    <tr><td>Row with Index #0</td></tr>
    <tr><td>Row with Index #1</td></tr>

    <tr><td>Row with Index #2</td></tr>
    <tr><td>Row with Index #3</td></tr>
  </table>
<script>$("tr:odd").css("background-color", "#bbbbff");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :odd Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Child Filter – jQuery API

jQuery API

Skip to content
  • api

Child Filter

  • :first-child Selector

    Selects all elements that are the first child of their parent.

  • :last-child Selector

    Selects all elements that are the last child of their parent.

  • :nth-child Selector

    Selects all elements that are the nth-child of their parent.

  • :only-child Selector

    Selects all elements that are the only child of their parent.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:first-child Selector – jQuery API

jQuery API

Skip to content
  • api

:first-child Selector

Categories: Selectors > Child Filter

first-child

Sample:

version added: 1.1.4jQuery(':first-child')

While :first matches only a single element, the :first-child selector can match more than one: one for each parent. This is equivalent to :nth-child(1).

Example:

Finds the first span in each matched div to underline and add a hover state.

<!DOCTYPE html>
<html>
<head>
  <style>
  span { color:#008; }
  span.sogreen { color:green; font-weight: bolder; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <span>John,</span>
    <span>Karl,</span>
    <span>Brandon</span>

  </div>
  <div>
    <span>Glen,</span>
    <span>Tane,</span>
    <span>Ralph</span>

  </div>
<script>
    $("div span:first-child")
        .css("text-decoration", "underline")
        .hover(function () {
              $(this).addClass("sogreen");
            }, function () {
              $(this).removeClass("sogreen");
            });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :first-child Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:last-child Selector – jQuery API

jQuery API

Skip to content
  • api

:last-child Selector

Categories: Selectors > Child Filter

last-child

Sample:

version added: 1.1.4jQuery(':last-child')

While :last matches only a single element, :last-child can match more than one: one for each parent.

Example:

Finds the last span in each matched div and adds some css plus a hover state.

<!DOCTYPE html>
<html>
<head>
  <style>
  span.solast { text-decoration:line-through; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <span>John,</span>
    <span>Karl,</span>
    <span>Brandon,</span>

    <span>Sam</span>
  </div>
  <div>
    <span>Glen,</span>
    <span>Tane,</span>

    <span>Ralph,</span>
    <span>David</span>
  </div>
<script>
    $("div span:last-child")
        .css({color:"red", fontSize:"80%"})
        .hover(function () {
              $(this).addClass("solast");
            }, function () {
              $(this).removeClass("solast");
            });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :last-child Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:nth-child Selector – jQuery API

jQuery API

Skip to content
  • api

:nth-child Selector

Categories: Selectors > Child Filter

nth-child

Sample:

version added: 1.1.4jQuery(':nth-child(index/even/odd/equation)')

  • index
    The index of each child to match, starting with 1, the string even or odd, or an equation ( eg. :nth-child(even), :nth-child(4n) )

Because jQuery's implementation of :nth-child(n) is strictly derived from the CSS specification, the value of n is "1-indexed", meaning that the counting starts at 1. For all other selector expressions, however, jQuery follows JavaScript's "0-indexed" counting. Therefore, given a single <ul> containing two <li>s, $('li:nth-child(1)') selects the first <li> while $('li:eq(1)') selects the second.

The :nth-child(n) pseudo-class is easily confused with :eq(n), even though the two can result in dramatically different matched elements. With :nth-child(n), all children are counted, regardless of what they are, and the specified element is selected only if it matches the selector attached to the pseudo-class. With :eq(n) only the selector attached to the pseudo-class is counted, not limited to children of any other element, and the nth one is selected.

Further discussion of this unusual usage can be found in the W3C CSS specification.

Examples:

Example: Finds the second li in each matched ul and notes it.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { float:left; }
  span { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><ul>
    <li>John</li>
    <li>Karl</li>
    <li>Brandon</li>

  </ul></div>
  <div><ul>
    <li>Sam</li>
  </ul></div>

  <div><ul>
    <li>Glen</li>
    <li>Tane</li>
    <li>Ralph</li>

    <li>David</li>
  </ul></div>
<script>$("ul li:nth-child(2)").append("<span> - 2nd!</span>");</script>
</body>
</html>

Demo:

Example: This is a playground to see how the selector works with different strings. Notice that this is different from the :even and :odd which have no regard for parent and just filter the list of elements to every other one. The :nth-child, however, counts the index of the child to its particular parent. In any case, it's easier to see than explain so...

<!DOCTYPE html>
<html>
<head>
  <style>
  button { display:block; font-size:12px; width:100px; }
  div { float:left; margin:10px; font-size:10px;
        border:1px solid black; }
  span { color:blue; font-size:18px; }
  #inner { color:red; }
  td { width:50px; text-align:center; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <button>:nth-child(even)</button>
    <button>:nth-child(odd)</button>
    <button>:nth-child(3n)</button>

    <button>:nth-child(2)</button>
  </div>
  <div>
    <button>:nth-child(3n+1)</button>
    <button>:nth-child(3n+2)</button>

    <button>:even</button>
    <button>:odd</button>
  </div>
  <div><table>

    <tr><td>John</td></tr>
    <tr><td>Karl</td></tr>
    <tr><td>Brandon</td></tr>

    <tr><td>Benjamin</td></tr>
  </table></div>
  <div><table>
    <tr><td>Sam</td></tr>

  </table></div>
  <div><table>
    <tr><td>Glen</td></tr>
    <tr><td>Tane</td></tr>

    <tr><td>Ralph</td></tr>
    <tr><td>David</td></tr>
    <tr><td>Mike</td></tr>

    <tr><td>Dan</td></tr>
  </table></div>
  <span>
    tr<span id="inner"></span>

  </span>
<script>
    $("button").click(function () {
      var str = $(this).text();
      $("tr").css("background", "white");
      $("tr" + str).css("background", "#ff0000");
      $("#inner").text(str);
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :nth-child Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:only-child Selector – jQuery API

jQuery API

Skip to content
  • api

:only-child Selector

Categories: Selectors > Child Filter

only-child

Sample:

version added: 1.1.4jQuery(':only-child')

If the parent has other child elements, nothing is matched.

Example:

Finds the button with no siblings in each matched div and modifies look.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { width:100px; height:80px; margin:5px; float:left; background:#b9e }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <button>Sibling!</button>
    <button>Sibling!</button>
  </div>

  <div>
    <button>Sibling!</button>
  </div>
  <div>
    None
  </div>

  <div>
    <button>Sibling!</button>
    <button>Sibling!</button>
    <button>Sibling!</button>

  </div>
  <div>
    <button>Sibling!</button>
  </div>
<script>$("div button:only-child").text("Alone").css("border", "2px blue solid");</script>
</body>
</html>

Demo:

Result:

[ <li>Glen</li> ]

Comments

  • Please keep comments relevant to :only-child Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Content Filter – jQuery API

jQuery API

Skip to content
  • api

Content Filter

  • :contains() Selector

    Select all elements that contain the specified text.

  • :empty Selector

    Select all elements that have no children (including text nodes).

  • :has() Selector

    Selects elements which contain at least one element that matches the specified selector.

  • :parent Selector

    Select all elements that are the parent of another element, including text nodes.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:contains() Selector – jQuery API

jQuery API

Skip to content
  • api

:contains() Selector

Categories: Selectors > Content Filter

contains

Sample:

version added: 1.1.4jQuery(':contains(text)')

The matching text can appear directly within the selected element, in any of that element's descendants, or a combination thereof. As with attribute value selectors, text inside the parentheses of :contains() can be written as bare words or surrounded by quotation marks. The text must have matching case to be selected.

Example:

Finds all divs containing "John" and underlines them.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>John Resig</div>

  <div>George Martin</div>
  <div>Malcom John Sinclair</div>
  <div>J. Ohn
<script>$("div:contains('John')").css("text-decoration", "underline");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :contains() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • me
    The :contains() selector is case sensitive!.
    This is my case insensitive version:

    $.expr[':'].icontains = function(obj, index, meta, stack){
    return (obj.textContent || obj.innerText || jQuery(obj).text() || '').toLowerCase().indexOf(meta[3].toLowerCase()) >= 0;
    };

    Example:

    $("div:icontains('John')").css("text-decoration", "underline");

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:empty Selector – jQuery API

jQuery API

Skip to content
  • api

:empty Selector

Categories: Selectors > Content Filter

empty

Sample:

version added: 1.0jQuery(':empty')

This is the inverse of :parent.

One important thing to note with :empty (and :parent) is that child elements include text nodes.

The W3C recommends that the <p> element have at least one child node, even if that child is merely text (see http://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: <input>, <img>, <br>, and <hr>, for example.

Example:

Finds all elements that are empty - they don't have child elements or text.

<!DOCTYPE html>
<html>
<head>
  <style>

  td { text-align:center; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">
    <tr><td>TD #0</td><td></td></tr>
    <tr><td>TD #2</td><td></td></tr>

    <tr><td></td><td>TD#5</td></tr>
  </table>
<script>$("td:empty").text("Was empty!").css('background', 'rgb(255,220,200)');</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :empty Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:has() Selector – jQuery API

jQuery API

Skip to content
  • api

:has() Selector

Categories: Selectors > Content Filter

has

Sample:

version added: 1.1.4jQuery(':has(selector)')

The expression $('div:has(p)') matches a <div> if a <p> exists anywhere among its descendants, not just as a direct child.

Example:

Adds the class "test" to all divs that have a paragraph inside of them.

<!DOCTYPE html>
<html>
<head>
  <style>
  .test{ border: 3px inset red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><p>Hello in a paragraph</p></div>

  <div>Hello again! (with no paragraph)</div>
<script>$("div:has(p)").addClass("test");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :has() Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:parent Selector – jQuery API

jQuery API

Skip to content
  • api

:parent Selector

Categories: Selectors > Content Filter

parent

Sample:

version added: 1.0jQuery(':parent')

This is the inverse of :empty.

One important thing to note regarding the use of :parent (and :empty) is that child elements include text nodes.

The W3C recommends that the <p> element have at least one child node, even if that child is merely text (see http://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: <input>, <img>, <br>, and <hr>, for example.

Example:

Finds all tds with children, including text.

<!DOCTYPE html>
<html>
<head>
  <style>
  td { width:40px; background:green; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <table border="1">

  <tr><td>Value 1</td><td></td></tr>
  <tr><td>Value 2</td><td></td></tr>

</table>
<script>$("td:parent").fadeTo(1500, 0.3);</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :parent Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Form – jQuery API

jQuery API

Skip to content
  • api

Form

  • :button Selector

    Selects all button elements and elements of type button.

  • :checkbox Selector

    Selects all elements of type checkbox.

  • :checked Selector

    Matches all elements that are checked.

  • :disabled Selector

    Selects all elements that are disabled.

  • :enabled Selector

    Selects all elements that are enabled.

  • :file Selector

    Selects all elements of type file.

  • :image Selector

    Selects all elements of type image.

  • :input Selector

    Selects all input, textarea, select and button elements.

  • :password Selector

    Selects all elements of type password.

  • :radio Selector

    Selects all elements of type radio.

  • :reset Selector

    Selects all elements of type reset.

  • :selected Selector

    Selects all elements that are selected.

  • :submit Selector

    Selects all elements of type submit.

  • :text Selector

    Selects all elements of type text.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:button Selector – jQuery API

jQuery API

Skip to content
  • api

:button Selector

Categories: Selectors > Form

button

Sample:

version added: 1.0jQuery(':button')

Example:

Finds all button inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>

    var input = $(":button").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :button Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:checkbox Selector – jQuery API

jQuery API

Skip to content
  • api

:checkbox Selector

Categories: Selectors > Form

checkbox

Sample:

version added: 1.0jQuery(':checkbox')

$(':checkbox') is equivalent to $('[type=checkbox]'). As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':checkbox') is equivalent to $('*:checkbox'), so $('input:checkbox') should be used instead.

Example:

Finds all checkbox inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:25px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="checkbox" />
    <input type="file" />
    <input type="hidden" />

    <input type="image" />
    <input type="password" />
    <input type="radio" />

    <input type="reset" />
    <input type="submit" />
    <input type="text" />

    <select><option>Option<option/></select>
    <textarea></textarea>
    <button>Button</button>
  </form>

  <div>
  </div>
<script>

    var input = $("form input:checkbox").wrap('<span></span>').parent().css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :checkbox Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:checked Selector – jQuery API

jQuery API

Skip to content
  • api

:checked Selector

Categories: Selectors > Form

checked

Sample:

version added: 1.0jQuery(':checked')

The :checked selector works for checkboxes and radio buttons. For select elements, use the :selected selector.

Example:

Finds all input elements that are checked.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="checkbox" name="newsletter" checked="checked" value="Hourly" />

    <input type="checkbox" name="newsletter" value="Daily" />
    <input type="checkbox" name="newsletter" value="Weekly" />

    <input type="checkbox" name="newsletter" checked="checked" value="Monthly" />
    <input type="checkbox" name="newsletter" value="Yearly" />

  </form>
  <div></div>
<script>

    function countChecked() {
      var n = $("input:checked").length;
      $("div").text(n + (n <= 1 ? " is" : " are") + " checked!");
    }
    countChecked();
    $(":checkbox").click(countChecked);

</script>
</body>
</html>

Demo:

Result:

<input type="checkbox" name="newsletter" checked="checked" value="Daily" />,
  <input type="checkbox" name="newsletter" checked="checked" value="Monthly" /> ]

Comments

  • Please keep comments relevant to :checked Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:disabled Selector – jQuery API

jQuery API

Skip to content
  • api

:disabled Selector

Categories: Selectors > Form

disabled

Sample:

version added: 1.0jQuery(':disabled')

As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':disabled') is equivalent to $('*:disabled'), so $('input:disabled') should be used instead.

Example:

Finds all input elements that are disabled.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>

    <input name="email" disabled="disabled" />
    <input name="id" />
  </form>
<script>$("input:disabled").val("this is it");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :disabled Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:enabled Selector – jQuery API

jQuery API

Skip to content
  • api

:enabled Selector

Categories: Selectors > Form

enabled

Sample:

version added: 1.0jQuery(':enabled')

As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':enabled') is equivalent to $('*:enabled'), so $('input:enabled') should be used instead.

Example:

Finds all input elements that are enabled.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>

    <input name="email" disabled="disabled" />
    <input name="id" />
  </form>
<script>$("input:enabled").val("this is it");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :enabled Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:file Selector – jQuery API

jQuery API

Skip to content
  • api

:file Selector

Categories: Selectors > Form

file

Sample:

version added: 1.0jQuery(':file')

As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':file') is equivalent to $('*:file'), so $('input:file') should be used instead.

Example:

Finds all file inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>

    var input = $("input:file").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :file Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:image Selector – jQuery API

jQuery API

Skip to content
  • api

:image Selector

Categories: Selectors > Form

image

Sample:

version added: 1.0jQuery(':image')

Example:

Finds all image inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>
    var input = $("input:image").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :image Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:input Selector – jQuery API

jQuery API

Skip to content
  • api

:input Selector

Categories: Selectors > Form

input

Sample:

version added: 1.0jQuery(':input')

The :input selector basically selects all form controls.

Example:

Finds all input elements.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:25px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option</option></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div id="messages">
  </div>
<script>

    var allInputs = $(":input");
    var formChildren = $("form > *");
    $("#messages").text("Found " + allInputs.length + " inputs and the form has " +
                             formChildren.length + " children.");

    // so it won't submit
    $("form").submit(function () { return false; });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :input Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:password Selector – jQuery API

jQuery API

Skip to content
  • api

:password Selector

Categories: Selectors > Form

password

Sample:

version added: 1.0jQuery(':password')

$(':password') is equivalent to $('[type=password]'). As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':password') is equivalent to $('*:password'), so $('input:password') should be used instead.

Example:

Finds all password inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>

    var input = $("input:password").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :password Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:radio Selector – jQuery API

jQuery API

Skip to content
  • api

:radio Selector

Categories: Selectors > Form

radio

Sample:

version added: 1.0jQuery(':radio')

$(':radio') is equivalent to $('[type=radio]'). As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':radio') is equivalent to $('*:radio'), so $('input:radio') should be used instead.

To select a set of associated radio buttons, you might use: $('input[name=gender]:radio')

Example:

Finds all radio inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:25px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" name="asdf" />
    <input type="radio" name="asdf" />

    <input type="reset" />
    <input type="submit" />
    <input type="text" />

    <select><option>Option<option/></select>
    <textarea></textarea>
    <button>Button</button>
  </form>

  <div>
  </div>
<script>

    var input = $("form input:radio").wrap('<span></span>').parent().css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :radio Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:reset Selector – jQuery API

jQuery API

Skip to content
  • api

:reset Selector

Categories: Selectors > Form

reset

Sample:

version added: 1.0jQuery(':reset')

Example:

Finds all reset inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>

    var input = $("input:reset").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :reset Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:selected Selector – jQuery API

jQuery API

Skip to content
  • api

:selected Selector

Categories: Selectors > Form

selected

Sample:

version added: 1.0jQuery(':selected')

The :selected selector works for <option> elements. It does not work for checkboxes or radio inputs; use :checked for them.

Example:

Attaches a change event to the select that gets the text for each selected option and writes them in the div. It then triggers the event for the initial text draw.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <select name="garden" multiple="multiple">

    <option>Flowers</option>
    <option selected="selected">Shrubs</option>
    <option>Trees</option>
    <option selected="selected">Bushes</option>

    <option>Grass</option>
    <option>Dirt</option>
  </select>
  <div></div>
<script>

    $("select").change(function () {
          var str = "";
          $("select option:selected").each(function () {
                str += $(this).text() + " ";
              });
          $("div").text(str);
        })
        .trigger('change');
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :selected Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:submit Selector – jQuery API

jQuery API

Skip to content
  • api

:submit Selector

Categories: Selectors > Form

submit

Sample:

version added: 1.0jQuery(':submit')

The :submit selector typically applies to button or input elements. Note that some browsers treat <button> element as type="default" implicitly while others (such as Internet Explorer) do not.

Example:

Finds all submit elements that are descendants of a td element.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:45px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<table>
<form>
<table id="exampleTable" border="1" cellpadding="10" align="center">

    <tr>
        <th>
            Element Type
        </th>
        <th>
            Element
        </th>

    </tr
    <tr>
        <td>
            <input type="button" value="Input Button"/>
        </td>

    </tr>
    <tr>
        <td>
            <input type="checkbox" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="file" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="hidden" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="image" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="password" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="radio" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="reset" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="submit" />
        </td>

    </tr>
    <tr>
        <td>
            <input type="text" />
        </td>

    </tr>
    <tr>
        <td>
            <select><option>Option</option></select>
        </td>

    </tr>
    <tr>
        <td>
            <textarea></textarea>
        </td>
    </tr>

    <tr>
        <td>
            <button>Button</button>
        </td>
    </tr>
    <tr>
        <td>
            <button type="submit">Button type="submit"</button>
        </td>
    </tr>

</table>
</form>
<div id="result"></div>

<script>
    var submitEl = $("td :submit")
      .parent('td')
      .css({background:"yellow", border:"3px red solid"})
    .end();

    $('#result').text('jQuery matched ' + submitEl.length + ' elements.');

    // so it won't submit
    $("form").submit(function () { return false; });

    // Extra JS to make the HTML easier to edit (None of this is relevant to the ':submit' selector
    $('#exampleTable').find('td').each(function(i, el) {
        var inputEl = $(el).children(),
            inputType = inputEl.attr('type') ? ' type="' + inputEl.attr('type') + '"' : '';
        $(el).before('<td>' + inputEl[0].nodeName + inputType + '</td>');
    })

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :submit Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:text Selector – jQuery API

jQuery API

Skip to content
  • api

:text Selector

Categories: Selectors > Form

text

Sample:

version added: 1.0jQuery(':text')

$(':text') is equivalent to $('[type=text]'). As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare $(':text') is equivalent to $('*:text'), so $('input:text') should be used instead.

Example:

Finds all text inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  textarea { height:25px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <input type="button" value="Input Button"/>
    <input type="checkbox" />

    <input type="file" />
    <input type="hidden" />
    <input type="image" />

    <input type="password" />
    <input type="radio" />
    <input type="reset" />

    <input type="submit" />
    <input type="text" />
    <select><option>Option<option/></select>

    <textarea></textarea>
    <button>Button</button>
  </form>
  <div>
  </div>
<script>

    var input = $("form input:text").css({background:"yellow", border:"3px red solid"});
    $("div").text("For this type jQuery found " + input.length + ".")
            .css("color", "red");
    $("form").submit(function () { return false; }); // so it won't submit

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :text Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Hierarchy – jQuery API

jQuery API

Skip to content
  • api

Hierarchy

  • Child Selector (“parent > child”)

    Selects all direct child elements specified by "child" of elements specified by "parent".

  • Descendant Selector (“ancestor descendant”)

    Selects all elements that are descendants of a given ancestor.

  • Next Adjacent Selector (“prev + next”)

    Selects all next elements matching "next" that are immediately preceded by a sibling "prev".

  • Next Siblings Selector (“prev ~ siblings”)

    Selects all sibling elements that follow after the "prev" element, have the same parent, and match the filtering "siblings" selector.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Child Selector (“parent > child”) – jQuery API

jQuery API

Skip to content
  • api

Child Selector (“parent > child”)

Categories: Selectors > Hierarchy

child

Sample:

version added: 1.0jQuery('parent > child')

  • parent
    Any valid selector.
    child
    A selector to filter the child elements.

As a CSS selector, the child combinator is supported by all modern web browsers including Safari, Firefox, Opera, Chrome, and Internet Explorer 7 and above, but notably not by Internet Explorer versions 6 and below. However, in jQuery, this selector (along with all others) works across all supported browsers, including IE6.

The child combinator (E > F) can be thought of as a more specific form of the descendant combinator (E F) in that it selects only first-level descendants.

Example:

Finds all children of the element with id "main" which is yellow.

<!DOCTYPE html>
<html>
<head>
  <style>
body { font-size:14px; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<ul class="topnav">
    <li>Item 1</li>
    <li>Item 2
        <ul><li>Nested item 1</li><li>Nested item 2</li><li>Nested item 3</li></ul>
       </li>
    <li>Item 3</li>
</ul>

<script>$("ul.topnav > li").css("border", "3px double red");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Child Selector (“parent > child”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Descendant Selector (“ancestor descendant”) – jQuery API

jQuery API

Skip to content
  • api

Descendant Selector (“ancestor descendant”)

Categories: Selectors > Hierarchy

descendant

Sample:

version added: 1.0jQuery('ancestor descendant')

  • ancestor
    Any valid selector.
    descendant
    A selector to filter the descendant elements.

A descendant of an element could be a child, grandchild, great-grandchild, and so on, of that element.

Example:

Finds all input descendants of forms.

<!DOCTYPE html>
<html>
<head>
  <style>

  body { font-size:14px; }
  form { border:2px green solid; padding:2px; margin:0;
         background:#efe; }
  div { color:red; }
  fieldset { margin:1px; padding:3px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>
    <div>Form is surrounded by the green outline</div>
    <label>Child:</label>
    <input name="name" />

    <fieldset>
      <label>Grandchild:</label>
      <input name="newsletter" />
    </fieldset>

  </form>
  Sibling to form: <input name="none" />
<script>$("form input").css("border", "2px dotted blue");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Descendant Selector (“ancestor descendant”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Next Adjacent Selector (“prev + next”) – jQuery API

jQuery API

Skip to content
  • api

Next Adjacent Selector (“prev + next”)

Categories: Selectors > Hierarchy

next adjacent

Sample:

version added: 1.0jQuery('prev + next')

  • prev
    Any valid selector.
    next
    A selector to match the element that is next to the first selector.

One important point to consider with both the next adjacent sibling selector (prev + next) and the general sibling selector (prev ~ siblings) is that the elements on either side of the combinator must share the same parent.

Example:

Finds all inputs that are next to a label.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form>

    <label>Name:</label>
    <input name="name" />
    <fieldset>
      <label>Newsletter:</label>

      <input name="newsletter" />
    </fieldset>
  </form>
  <input name="none" />
<script>$("label + input").css("color", "blue").val("Labeled!")</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Next Adjacent Selector (“prev + next”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Next Siblings Selector (“prev ~ siblings”) – jQuery API

jQuery API

Skip to content
  • api

Next Siblings Selector (“prev ~ siblings”)

Categories: Selectors > Hierarchy

next siblings

Sample:

version added: 1.0jQuery('prev ~ siblings')

  • prev
    Any valid selector.
    siblings
    A selector to filter elements that are the following siblings of the first selector.

The notable difference between (prev + next) and (prev ~ siblings) is their respective reach. While the former reaches only to the immediately following sibling element, the latter extends that reach to all following sibling elements.

Example:

Finds all divs that are siblings after the element with #prev as its id. Notice the span isn't selected since it is not a div and the "niece" isn't selected since it is a child of a sibling, not an actual sibling.

<!DOCTYPE html>
<html>
<head>
  <style>

  div,span {
    display:block;
    width:80px;
    height:80px;
    margin:5px;
    background:#bbffaa;
    float:left;
    font-size:14px;
  }
  div#small {
    width:60px;
    height:25px;
    font-size:12px;
    background:#fab;
  }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>div (doesn't match since before #prev)</div>
  <span id="prev">span#prev</span>
  <div>div sibling</div>

  <div>div sibling <div id="small">div niece</div></div>
  <span>span sibling (not div)</span>
  <div>div sibling</div>
<script>$("#prev ~ div").css("border", "3px groove blue");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to Next Siblings Selector (“prev ~ siblings”).
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Visibility Filter – jQuery API

jQuery API

Skip to content
  • api

Visibility Filter

  • :hidden Selector

    Selects all elements that are hidden.

  • :visible Selector

    Selects all elements that are visible.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:hidden Selector – jQuery API

jQuery API

Skip to content
  • api

:hidden Selector

Categories: Selectors > Visibility Filter

hidden

Sample:

version added: 1.0jQuery(':hidden')

Elements can be considered hidden for several reasons:

  • They have a display value of none.
  • They are form elements with type="hidden".
  • Their width and height are explicitly set to 0.
  • An ancestor element is hidden, so the element is not shown on the page.

How :hidden is determined was changed in jQuery 1.3.2. An element is assumed to be hidden if it or any of its parents consumes no space in the document. CSS visibility isn't taken into account (therefore $(elem).css('visibiity','hidden').is(':hidden') == false). The release notes outline the changes in more detail.

Example:

Shows all hidden divs and counts hidden inputs.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:70px; height:40px; background:#ee77ff; margin:5px; float:left; }
  span { display:block; clear:left; color:red; }
  .starthidden { display:none; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <span></span>
  <div></div>
  <div style="display:none;">Hider!</div>
  <div></div>

  <div class="starthidden">Hider!</div>
  <div></div>
  <form>
    <input type="hidden" />

    <input type="hidden" />
    <input type="hidden" />
  </form>
  <span>

  </span>
<script>
    // in some browsers :hidden includes head, title, script, etc... so limit to body
    $("span:first").text("Found " + $(":hidden", document.body).length +
                         " hidden elements total.");
    $("div:hidden").show(3000);
    $("span:last").text("Found " + $("input:hidden").length + " hidden inputs.");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :hidden Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


:visible Selector – jQuery API

jQuery API

Skip to content
  • api

:visible Selector

Categories: Selectors > Visibility Filter

visible

Sample:

version added: 1.0jQuery(':visible')

Elements can be considered hidden for several reasons:

  • They have a display value of none.
  • They are form elements with type="hidden".
  • Their width and height are explicitly set to 0.
  • An ancestor element is hidden, so the element is not shown on the page.

How :visible is calculated was changed in jQuery 1.3.2. The release notes outline the changes in more detail.

Example:

Make all visible divs turn yellow on click.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:50px; height:40px; margin:5px; border:3px outset green; float:left; }
  .starthidden { display:none; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Show hidden to see they don't change</button>
  <div></div>
  <div class="starthidden"></div>
  <div></div>

  <div></div>
  <div style="display:none;"></div>
<script>
    $("div:visible").click(function () {
      $(this).css("background", "yellow");
    });
    $("button").click(function () {
      $("div:hidden").show("fast");
    });

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to :visible Selector.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Traversing – jQuery API

jQuery API

Skip to content
  • api

Traversing

  • .add()

    Miscellaneous Traversing

    Add elements to the set of matched elements.

  • .andSelf()

    Miscellaneous Traversing

    Add the previous set of elements on the stack to the current set.

  • .children()

    Tree Traversal

    Get the children of each element in the set of matched elements, optionally filtered by a selector.

  • .closest()

    Tree Traversal

    Get the first element that matches the selector, beginning at the current element and progressing up through the DOM tree.

  • .contents()

    Miscellaneous Traversing

    Get the children of each element in the set of matched elements, including text nodes.

  • .end()

    Miscellaneous Traversing

    End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

  • .eq()

    Filtering

    Reduce the set of matched elements to the one at the specified index.

  • .filter()

    Filtering

    Reduce the set of matched elements to those that match the selector or pass the function's test.

  • .find()

    Tree Traversal

    Get the descendants of each element in the current set of matched elements, filtered by a selector.

  • .first()

    Filtering

    Reduce the set of matched elements to the first in the set.

  • .has()

    Filtering

    Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.

  • .is()

    Filtering

    Check the current matched set of elements against a selector and return true if at least one of these elements matches the selector.

  • .last()

    Filtering

    Reduce the set of matched elements to the final one in the set.

  • .map()

    Filtering

    Pass each element in the current matched set through a function, producing a new jQuery object containing the return values..

  • .next()

    Tree Traversal

    Get the immediately following sibling of each element in the set of matched elements, optionally filtered by a selector.

  • .nextAll()

    Tree Traversal

    Get all following siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .nextUntil()

    Tree Traversal

    Get all following siblings of each element up to but not including the element matched by the selector.

  • .not()

    Filtering

    Remove elements from the set of matched elements.

  • .offsetParent()

    Tree Traversal

    Get the closest ancestor element that is positioned.

  • .parent()

    Tree Traversal

    Get the parent of each element in the current set of matched elements, optionally filtered by a selector.

  • .parents()

    Tree Traversal

    Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector.

  • .parentsUntil()

    Tree Traversal

    Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector.

  • .prev()

    Tree Traversal

    Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector.

  • .prevAll()

    Tree Traversal

    Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .prevUntil()

    Tree Traversal

    Get all preceding siblings of each element up to but not including the element matched by the selector.

  • .siblings()

    Tree Traversal

    Get the siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .slice()

    Filtering

    Reduce the set of matched elements to a subset specified by a range of indices.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Filtering – jQuery API

jQuery API

Skip to content
  • api

Filtering

  • .eq()

    Reduce the set of matched elements to the one at the specified index.

  • .filter()

    Reduce the set of matched elements to those that match the selector or pass the function's test.

  • .first()

    Reduce the set of matched elements to the first in the set.

  • .has()

    Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.

  • .is()

    Check the current matched set of elements against a selector and return true if at least one of these elements matches the selector.

  • .last()

    Reduce the set of matched elements to the final one in the set.

  • .map()

    Pass each element in the current matched set through a function, producing a new jQuery object containing the return values..

  • .not()

    Remove elements from the set of matched elements.

  • .slice()

    Reduce the set of matched elements to a subset specified by a range of indices.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.eq() – jQuery API

jQuery API

Skip to content
  • api

.eq()

Categories: Traversing > Filtering

.eq( index ) Returns: jQuery

Description: Reduce the set of matched elements to the one at the specified index.

  • version added: 1.1.2.eq( index )

    indexAn integer indicating the 0-based position of the element.

Given a jQuery object that represents a set of DOM elements, the .eq() method constructs a new jQuery object from one of the matching elements. The supplied index identifies the position of this element in the set.

Consider a page with a simple list on it:

  <ul>
    <li>list item 1</li>
    <li>list item 2</li>
    <li>list item 3</li>
    <li>list item 4</li>
    <li>list item 5</li>
  </ul>

We can apply this method to the set of list items:

  $('li').eq(2).css('background-color', 'red');

The result of this call is a red background for item 3. Note that the supplied index is zero-based, and refers to the position of the element within the jQuery object, not within the DOM tree.

If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:

  $('li').eq(-2).css('background-color', 'red');

This time list item 4 is turned red, since it is two from the end of the set.

Example:

Turn the div with index 2 blue by adding an appropriate class.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:60px; height:60px; margin:10px; float:left;
        border:2px solid blue; }
  .blue { background:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>
<script>

    $("div").eq(2).addClass("blue");
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .eq().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.filter() – jQuery API

jQuery API

Skip to content
  • api

.filter()

Categories: Traversing > Filtering

.filter( selector ) Returns: jQuery

Description: Reduce the set of matched elements to those that match the selector or pass the function's test.

  • version added: 1.0.filter( selector )

    selectorA string containing a selector expression to match elements against.

  • version added: 1.0.filter( function(index) )

    function(index)A function used as a test for each element in the set. this is the current DOM element.

Given a jQuery object that represents a set of DOM elements, the .filter() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; all elements matching the selector will be included in the result.

Consider a page with a simple list on it:

We can apply this method to the set of list items:

  $('li').filter(':even').css('background-color', 'red');

The result of this call is a red background for items 1, 3, and 5, as they match the selector (recall that :even and :odd use 0-based indexing).

Using a Filter Function

The second form of this method allows us to filter elements against a function rather than a selector. For each element, if the function returns true, the element will be included in the filtered set; otherwise, it will be excluded. Suppose we have a somewhat more involved HTML snippet:

<ul>
  <li><strong>list</strong> item 1 -
    one strong tag</li>
  <li><strong>list</strong> item <strong>2</strong> -
    two <span>strong tags</span></li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
  <li>list item 6</li>
</ul>

We can select the list items, then filter them based on their contents:

$('li').filter(function(index) {
  return $('strong', this).length == 1;
}).css('background-color', 'red');

This code will alter the first list item only, as it contains exactly one <strong> tag. Within the filter function, this refers to each DOM element in turn. The parameter passed to the function tells us the index of that DOM element within the set matched by the jQuery object.

We can also take advantage of the index passed through the function, which indicates the 0-based position of the element within the unfiltered set of matched elements:

$('li').filter(function(index) {
  return index % 3 == 2;
}).css('background-color', 'red');

This alteration to the code will cause the third and sixth list items to be highlighted, as it uses the modulus operator (%) to select every item with an index value that, when divided by 3, has a remainder of 2.

Examples:

Example: Change the color of all divs then put a border around only some of them.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:60px; height:60px; margin:5px; float:left;
        border:2px white solid;}
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>

  <div class="middle"></div>
  <div class="middle"></div>
  <div class="middle"></div>
  <div class="middle"></div>

  <div></div>
<script>

    $("div").css("background", "#c8ebcc")
            .filter(".middle")
            .css("border-color", "red");
</script>
</body>
</html>

Demo:

Example: Selects all paragraphs and removes those without a class "selected".

$("p").filter(".selected")

Example: Selects all paragraphs and removes those that aren't of class "selected" or the first one.

$("p").filter(".selected, :first")

Example: Change the color of all divs then put a border to specific ones.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:60px; height:60px; margin:5px; float:left;
        border:3px white solid; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="first"></div>
  <div id="second"></div>
  <div id="third"></div>

  <div id="fourth"></div>
  <div id="fifth"></div>
  <div id="sixth"></div>
<script>
    $("div").css("background", "#b4b0da")
            .filter(function (index) {
                  return index == 1 || $(this).attr("id") == "fourth";
                })
            .css("border", "3px double red");

</script>
</body>
</html>

Demo:

Example: Remove all elements that have a descendant ol element

$("div").filter(function(index) {
   return $("ol", this).length == 0;
 });

Comments

  • Please keep comments relevant to .filter().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Nigel
    I thinkthe description here is incorrect since the moethod can return more than one matched element.
    Looks as though it was pasted from another method description :-)
  • Karl Swedberg
    Yep -- copy/paste error. Fixed now. Thanks!

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.first() – jQuery API

jQuery API

Skip to content
  • api

.first()

Categories: Traversing > Filtering

.first() Returns: jQuery

Description: Reduce the set of matched elements to the first in the set.

  • version added: 1.2.first()

Given a jQuery object that represents a set of DOM elements, the .first() method constructs a new jQuery object from the first matching element.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can apply this method to the set of list items:

$('li').first().css('background-color', 'red');

The result of this call is a red background for the first item.

Example:

Highlight the first span in a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>.highlight{background-color: yellow}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><span>Look:</span> <span>This is some text in a paragraph.</span> <span>This is a note about it.</span></p>
<script>$("p span").first().addClass('highlight');</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .first().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.has() – jQuery API

jQuery API

Skip to content
  • api

.has()

Categories: Traversing > Filtering

.has( selector ) Returns: jQuery

Description: Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.

  • version added: 1.4.has( selector )

    selectorA string containing a selector expression to match elements against.

  • version added: 1.4.has( contained )

    containedA DOM element to match elements against.

Given a jQuery object that represents a set of DOM elements, the .has() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against the descendants of the matching elements; the element will be included in the result if any of its descendant elements matches the selector.

Consider a page with a nested list as follows:

 <ul>
  <li>list item 1</li>
  <li>list item 2
    <ul>
      <li>list item 2-a</li>
      <li>list item 2-b</li>
    </ul>
  </li>
  <li>list item 3</li>
  <li>list item 4</li>
</ul>

We can apply this method to the set of list items as follows:

$('li').has('ul').css('background-color', 'red');

The result of this call is a red background for item 2, as it is the only <li> that has a <ul> among its descendants.

Example:

Check if an element is inside another.

<!DOCTYPE html>
<html>
<head>
  <style>
  .full { border: 1px solid red; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<ul><li>Does the UL contain an LI?</li></ul>

<script>
  $("ul").append("<li>" + ($("ul").has("li").length ? "Yes" : "No") + "</li>");
  $("ul").has("li").addClass("full");
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .has().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • tigris2
    I use the jquery treeview plugin (from Jörn Zaefferer) with jquery 1.2.6 version but yesterday I updated the version and the plugin crashed... I found the "bug":

    this.filter(":has(>ul:hidden)")
    .addClass(CLASSES.expandable)
    .replaceClass(CLASSES.last, CLASSES.lastExpandable);

    so I tested the following alert: (under 1.2.6 and 1.4 version)
    alert(this.filter(":has(>ul:hidden)").length);
    alert(this.filter(":has(>ul:visible)").length);

    I had 4 list element in it 1-1 ul (in 3 cases the ul is display:block and in 1 case display:none)

    the result under 1.2.6:
    1
    3
    that's OK

    the result under 1.4:
    4
    4

    what's wrong?

    maybe :hidden and :visible doesn't work?

    thanks and sorry for my english.
  • Karl Swedberg
    This isn't the appropriate venue for bug reports or support requests. Please direct this issue to http://forum.jquery.com/using-jquery-plugins

    Thanks!
  • tigris2
    sorry, I didn't know, I just realized it...
  • Paco Lopez
    So, $("ul").has("li") is faster than $("ul:has(li)") ?

    I suppose it is, compute two simple selectors is faster than one complex selector.
  • Adam B
    Is this distinct from .find() ? If so how?
  • Karl Swedberg
    Yes, this is different from .find(). For example, $('div').has('p') selects all divs that have a paragraph as a descendant while $('div').find('p') selects all paragraphs that are descendants of a div.
  • Francois-Guillaume Ribreau
    $("li","ul").length seems faster than $("ul").has("li").length :

    (from the jQuery 1.4rc1 source code)
    has: function( target ) {
    var targets = jQuery( target );//gets ALL LI elements
    return this.filter(function() {//and then, loop on every LI elements.
    for ( var i = 0, l = targets.length; i < l; i++ ) {
    if ( jQuery.contains( this, targets[i] ) ) {
    return true;
    }
    }
    });
    }
  • John Resig
    It's not meant to be used like that, primarily - it's meant to be used like the :has() selector. For example instead of doing: $("ul:has(li)").addClass("full"); you can do: $("ul").has("li").addClass("full");
  • Francois-Guillaume Ribreau
    Oh Ok! I got the point now :)
    But I think the description should be updated.
  • Karl Swedberg
    Yeah, the description wasn't terribly clear. I've updated it. Hope that helps.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.is() – jQuery API

jQuery API

Skip to content
  • api

.is()

Categories: Traversing > Filtering

.is( selector ) Returns: Boolean

Description: Check the current matched set of elements against a selector and return true if at least one of these elements matches the selector.

  • version added: 1.0.is( selector )

    selectorA string containing a selector expression to match elements against.

Unlike the rest of the methods in this chapter, .is() does not create a new jQuery object. Instead, it allows us to test the contents of a jQuery object without modification. This is often useful inside callbacks, such as event handlers.

Suppose we have a list, with two of its items containing a child element:

<ul>
  <li>list <strong>item 1</strong></li>
  <li><span>list item 2</span></li>
  <li>list item 3</li>
</ul>

We can attach a click handler to the <ul> element, and then limit the code to be triggered only when a list item itself, not one of its children, is clicked:

$('ul').click(function(event) {
  if ($(event.target).is('li') ) {
    $(event.target).css('background-color', 'red');
  }
});

Now, when the user clicks on the word list in the first item or anywhere in the third item, the clicked list item will be given a red background. However, when the user clicks on item 1 in the first item or anywhere in the second item, nothing will occur, because in those cases the target of the event would be <strong> or <span>, respectively.

Examples:

Example: Shows a few ways is() can be used inside an event handler.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:60px; height:60px; margin:5px; float:left;
        border:4px outset; background:green; text-align:center;
        font-weight:bolder; cursor:pointer; }
  .blue { background:blue; }
  .red { background:red; }
  span { color:white; font-size:16px; }
  p { color:red; font-weight:bolder; background:yellow;
      margin:3px; clear:left; display:none; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div class="blue"></div>
  <div></div>
  <div class="red"></div>

  <div><br/><span>Peter</span></div>
  <div class="blue"></div>
  <p>&nbsp;</p>
<script>
    $("div").one('click', function () {
      if ($(this).is(":first-child")) {
        $("p").text("It's the first div.");
      } else if ($(this).is(".blue,.red")) {
        $("p").text("It's a blue or red div.");
      } else if ($(this).is(":contains('Peter')")) {
        $("p").text("It's Peter!");
      } else {
        $("p").html("It's nothing <em>special</em>.");
      }
      $("p").hide().slideDown("slow");
      $(this).css({"border-style": "inset", cursor:"default"});
    });

</script>
</body>
</html>

Demo:

Example: Returns true, because the parent of the input is a form element

<!DOCTYPE html>
<html>
<head>
  <style>div { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form><input type="checkbox" /></form>

  <div></div>
<script>

    var isFormParent = $("input[type='checkbox']").parent().is("form")
    $("div").text("isFormParent = " + isFormParent);
</script>
</body>
</html>

Demo:

Example: Returns false, because the parent of the input is a p element

<!DOCTYPE html>
<html>
<head>
  <style>div { color:red; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <form><p><input type="checkbox" /></p></form>

  <div></div>
<script>
    var isFormParent = $("input[type='checkbox']").parent().is("form")
    $("div").text("isFormParent = " + isFormParent);
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .is().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.last() – jQuery API

jQuery API

Skip to content
  • api

.last()

Categories: Traversing > Filtering

.last() Returns: jQuery

Description: Reduce the set of matched elements to the final one in the set.

  • version added: 1.2.last()

Given a jQuery object that represents a set of DOM elements, the .last() method constructs a new jQuery object from the first matching element.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can apply this method to the set of list items:

$('li').last().css('background-color', 'red');

The result of this call is a red background for the final item.

Example:

Highlight the last span in a paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>.highlight{background-color: yellow}</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><span>Look:</span> <span>This is some text in a paragraph.</span> <span>This is a note about it.</span></p>
<script>$("p span").last().addClass('highlight');</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .last().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Rowan187
    This is amazing! Exactly what I need to quickly and lazily get the borders off the last item in my lists

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.map() – jQuery API

jQuery API

Skip to content
  • api

.map()

Categories: Traversing > Filtering

.map( callback(index, domElement) ) Returns: jQuery

Description: Pass each element in the current matched set through a function, producing a new jQuery object containing the return values..

  • version added: 1.2.map( callback(index, domElement) )

    callback(index, domElement)A function object that will be invoked for each element in the current set.

The .map() method is particularly useful for getting or setting the value of a collection of elements. Consider a form with a set of checkboxes in it:

<form method="post" action="">
  <fieldset>
    <div>
      <label for="two">2</label>
      <input type="checkbox" value="2" id="two" name="number[]">
    </div>
    <div>
      <label for="four">4</label>
      <input type="checkbox" value="4" id="four" name="number[]">
    </div>
    <div>
      <label for="six">6</label>
      <input type="checkbox" value="6" id="six" name="number[]">
    </div>
    <div>
      <label for="eight">8</label>
      <input type="checkbox" value="8" id="eight" name="number[]">
    </div>
  </fieldset>
</form>

We can check all of the checkboxes by setting their checked property to true:

$('input:checkbox').map(function() {
 return this.checked = true;
});

We can get the sum of the values of the checked inputs:

var sum = 0;
$('input:checked').map(function() {
 return sum += (this.value * 1);
});

We can get a comma-separated list of checkbox IDs:

$(':checkbox').map(function() {
  return this.id;
}).get().join(',');

The result of this call is the string, "two,four,six,eight".

Examples:

Example: Build a list of all the values within a form.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><b>Values: </b></p>
  <form>
    <input type="text" name="name" value="John"/>

    <input type="text" name="password" value="password"/>
    <input type="text" name="url" value="http://ejohn.org/"/>

  </form>
<script>
    $("p").append( $("input").map(function(){
      return $(this).val();
    }).get().join(", ") );

</script>
</body>
</html>

Demo:

Example: A contrived example to show some functionality.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { font-size:16px; }
  ul { float:left; margin:0 30px; color:blue; }
  #results { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
    <li>First</li>
    <li>Second</li>
    <li>Third</li>

    <li>Fourth</li>
    <li>Fifth</li>
  </ul>
  <ul id="results">

  </ul>
<script>
    var mappedItems = $("li").map(function (index) {
      var replacement = $("<li>").text($(this).text()).get(0);
      if (index == 0) {
        // make the first item all caps
        $(replacement).text($(replacement).text().toUpperCase());
      } else if (index == 1 || index == 3) {
        // delete the second and fourth items
        replacement = null;
      } else if (index == 2) {
        // make two of the third item and add some text
        replacement = [replacement,$("<li>").get(0)];
        $(replacement[0]).append("<b> - A</b>");
        $(replacement[1]).append("Extra <b> - B</b>");
      }

      // replacement will be an dom element, null,
      // or an array of dom elements
      return replacement;
    });
    $("#results").append(mappedItems);

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .map().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.not() – jQuery API

jQuery API

Skip to content
  • api

.not()

Categories: Traversing > Filtering

.not( selector ) Returns: jQuery

Description: Remove elements from the set of matched elements.

  • version added: 1.0.not( selector )

    selectorA string containing a selector expression to match elements against.

  • version added: 1.0.not( elements )

    elementsOne or more DOM elements to remove from the matched set.

  • version added: 1.0.not( function(index) )

    function(index)A function used as a test for each element in the set. this is the current DOM element.

Given a jQuery object that represents a set of DOM elements, the .not() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can apply this method to the set of list items:

$('li').not(':even').css('background-color', 'red');

The result of this call is a red background for items 2 and 4, as they do not match the selector (recall that :even and :odd use 0-based indexing).

Removing Specific Elements

The second version of the .not() method allows us to remove elements from the matched set, assuming we have found those elements previously by some other means. For example, suppose our list had an id applied to one of its items:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li id="notli">list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can fetch the third list item using the native JavaScript getElementById() function, then remove it from a jQuery object:

$('li').not(document.getElementById('notli'))
  .css('background-color', 'red');

This statement changes the color of items 1, 2, 4, and 5. We could have accomplished the same thing with a simpler jQuery expression, but this technique can be useful when, for example, other libraries provide references to plain DOM nodes.

As of jQuery 1.4, the .not() method can take a function as its argument in the same way that .filter() does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.

Examples:

Example: Adds a border to divs that are not green or blue.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:50px; height:50px; margin:10px; float:left;
        background:yellow; border:2px solid white; }
  .green { background:#8f8; }
  .gray { background:#ccc; }
  #blueone { background:#99f; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div id="blueone"></div>
  <div></div>
  <div class="green"></div>

  <div class="green"></div>
  <div class="gray"></div>
  <div></div>
<script>
    $("div").not(".green, #blueone")
            .css("border-color", "red");

</script>
</body>
</html>

Demo:

Example: Removes the element with the ID "selected" from the set of all paragraphs.

$("p").not( $("#selected")[0] )

Example: Removes the element with the ID "selected" from the set of all paragraphs.

$("p").not("#selected")

Example: Removes all elements that match "div p.selected" from the total set of all paragraphs.

$("p").not($("div p.selected"))

Comments

  • Please keep comments relevant to .not().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Andir
    Forgive me if this is a double post.. my other comment seems to be missing:

    .not() seems to be buggy in implementation:
    <span id ="1">
    <span id="2"><div>test</div></span>
    <span id="3"><div>test</div></span>
    <span id="4">I want this</span>
    </span>
    <script language="javascript">
    $(document).ready(function(){
    $("span").not("span div").each(
    function(index, element) {
    alert($(element).attr("id"));
    }
    );
    });
    </script>

    Should return 4, but it returns all elements.
  • Karl Swedberg
    I think what you're trying to do is this:

    $('span').not(':has(div)') ...

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.slice() – jQuery API

jQuery API

Skip to content
  • api

.slice()

Categories: Traversing > Filtering

.slice( start ) Returns: jQuery

Description: Reduce the set of matched elements to a subset specified by a range of indices.

  • version added: 1.1.4.slice( start )

    startstart: An integer indicating the 0-based position after which the elemets are selected.

  • version added: 1.1.4.slice( [ end ] )

    endAn integer indicating the 0-based position before which the elemets stop being selected. If omitted, the range continues until the end of the set.

Given a jQuery object that represents a set of DOM elements, the .slice() method constructs a new jQuery object from a subset of the matching elements. The supplied start index identifies the position of one of the elements in the set; if end is omitted, all elements after this one will be included in the result.

Consider a page with a simple list on it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
  <li>list item 4</li>
  <li>list item 5</li>
</ul>

We can apply this method to the set of list items:

$('li').slice(2).css('background-color', 'red');

The result of this call is a red background for items 3, 4, and 5. Note that the supplied index is zero-based, and refers to the position of elements within the jQuery object, not within the DOM tree.

The end parameter allows us to limit the selected range even further. For example:

$('li').slice(2, 4).css('background-color', 'red');

Now only items 3 and 4 are selected. The index is once again zero-based; the range extends up to but not including the specified index.

Negative Indices

The jQuery .slice() method is patterned after the JavaScript .slice() method for arrays. One of the features that it mimics is the ability for negative numbers to be passed as either the start or end parameter. If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:

$('li').slice(-2, -1).css('background-color', 'red');

This time only list item 4 is turned red, since it is the only item in the range between two from the end (-2) and one from the end (-1).

Examples:

Example: Turns divs yellow based on a random slice.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:40px; height:40px; margin:10px; float:left;
        border:2px solid blue; }
  span { color:red; font-weight:bold; }
  button { margin:5px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><button>Turn slice yellow</button>
  <span>Click the button!</span></p>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
<script>

    function colorEm() {
      var $div = $("div");
      var start = Math.floor(Math.random() *
                             $div.length);
      var end = Math.floor(Math.random() *
                           ($div.length - start)) +
                           start + 1;
      if (end == $div.length) end = undefined;
      $div.css("background", "");
      if (end)
        $div.slice(start, end).css("background", "yellow");
       else
        $div.slice(start).css("background", "yellow");

      $("span").text('$("div").slice(' + start +
                     (end ? ', ' + end : '') +
                     ').css("background", "yellow");');
    }

    $("button").click(colorEm);

</script>
</body>
</html>

Demo:

Example: Selects all paragraphs, then slices the selection to include only the first element.

$("p").slice(0, 1).wrapInner("<b></b>");

Example: Selects all paragraphs, then slices the selection to include only the first and second element.

$("p").slice(0, 2).wrapInner("<b></b>");

Example: Selects all paragraphs, then slices the selection to include only the second element.

$("p").slice(1, 2).wrapInner("<b></b>");

Example: Selects all paragraphs, then slices the selection to include only the second and third element.

$("p").slice(1).wrapInner("<b></b>");

Example: Selects all paragraphs, then slices the selection to include only the third element.

$("p").slice(-1).wrapInner("<b></b>");

Comments

  • Please keep comments relevant to .slice().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • James Padolsey
    Shouldn't the argument signature for this be ( start, [end] ) ??

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Miscellaneous Traversing – jQuery API

jQuery API

Skip to content
  • api

Miscellaneous Traversing

  • .add()

    Add elements to the set of matched elements.

  • .andSelf()

    Add the previous set of elements on the stack to the current set.

  • .contents()

    Get the children of each element in the set of matched elements, including text nodes.

  • .end()

    End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.add() – jQuery API

jQuery API

Skip to content
  • api

.add()

Categories: Traversing > Miscellaneous Traversing

.add( selector ) Returns: jQuery

Description: Add elements to the set of matched elements.

  • version added: 1.0.add( selector )

    selectorA string containing a selector expression to match additional elements against.

  • version added: 1.0.add( elements )

    elementsone or more elements to add to the set of matched elements.

  • version added: 1.0.add( html )

    htmlAn HTML fragment to add to the set of matched elements.

  • version added: 1.4.add( selector, context )

    selectorA string containing a selector expression to match additional elements against.

    contextAdd some elements rooted against the specified context.

Given a jQuery object that represents a set of DOM elements, the .add() method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add() can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.

Consider a page with a simple list and a paragraph following it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
</ul>
<p>a paragraph</p>

We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the .add() method's argument:

$('li').add('p').css('background-color', 'red');

Or:

$('li').add(document.getElementsByTagName('p')[0])
  .css('background-color', 'red');

The result of this call is a red background behind all four elements. Using an HTML snippet as the .add() method's argument (as in the third version), we can create additional elements on the fly and add those elements to the matched set of elements. Let's say, for example, that we want to alter the background of the list items along with a newly created paragraph:

$('li').add('<p id="new">new paragraph</p>')
  .css('background-color', 'red');

Although the new paragraph has been created and its background color changed, it still does not appear on the page. To place it on the page, we could add one of the insertion methods to the chain.

As of jQuery 1.4 the results from .add() will always be returned in document order (rather than a simple concatenation).

Examples:

Example: Finds all divs and makes a border. Then adds all paragraphs to the jQuery object to set their backgrounds yellow.

<!DOCTYPE html>
<html>
<head>
  <style>
 div { width:60px; height:60px; margin:10px; float:left; }
 p { clear:left; font-weight:bold; font-size:16px;
     color:blue; margin:0 10px; padding:2px; }
 </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <p>Added this... (notice no border)</p>
<script>

$("div").css("border", "2px solid red")
        .add("p")
        .css("background", "yellow");
</script>
</body>
</html>

Demo:

Example: Adds more elements, matched by the given expression, to the set of matched elements.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><span>Hello Again</span>
<script>$("p").add("span").css("background", "yellow");</script>
</body>
</html>

Demo:

Example: Adds more elements, created on the fly, to the set of matched elements.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>
<script>$("p").clone().add("<span>Again</span>").appendTo(document.body);</script>
</body>
</html>

Demo:

Example: Adds one or more Elements to the set of matched elements.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><span id="a">Hello Again</span>
<script>$("p").add(document.getElementById("a")).css("background", "yellow");</script>
</body>
</html>

Demo:

Example: Demonstrates how to add (or push) elements to an existing collection

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p><span id="a">Hello Again</span>
<script>var collection = $("p");
// capture the new collection
collection = collection.add(document.getElementById("a"));
collection.css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .add().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Adam
    The 1.3 compat file mentions a concat method, but I don't see it in the source. Is there a concat method I can use that wouldn't order the results like add() does?
  • jcteague
    wouldn't union be a better name for this method?
  • B@rmaley.e><e
    This method don't works with argument-function. Method insert function (!) in jQuery-chain.
    $('body').add(function(){/*function argument for add*/}) returns object:
    length: 2
    0: [object HTMLBodyElement]
    1: function(){/*function argument for add*/}
    ...
  • Levon Mamikonyan
    Yeah .. you do .. :-D Genius idea !!
  • Levon Mamikonyan
    Good stuff, really interesting if you guys lazy loading this comments. As when im initially opening the page, this comments box is hidden

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.andSelf() – jQuery API

jQuery API

Skip to content
  • api

.andSelf()

Categories: Traversing > Miscellaneous Traversing

.andSelf() Returns: jQuery

Description: Add the previous set of elements on the stack to the current set.

  • version added: 1.2.andSelf()

As described in the discussion for .end() above, jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, .andSelf() can help.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find the elements which come after it:

$('li.third-item').nextAll().andSelf()
  .css('background-color', 'red');

The result of this call is a red background behind items 3, 4 and 5. First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to .nextAll() then pushes the set of items 4 and 5 onto the stack. Finally, the .andSelf() invocation merges these two sets together, creating a jQuery object that points to all three items.

Example:

Find all divs, and all the paragraphs inside of them, and give them both classnames. Notice the div doesn't have the yellow background color since it didn't use andSelf.

<!DOCTYPE html>
<html>
<head>
  <style>
  p, div { margin:5px; padding:5px; }
  .border { border: 2px solid red; }
  .background { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <p>First Paragraph</p>
    <p>Second Paragraph</p>
  </div>
<script>
    $("div").find("p").andSelf().addClass("border");
    $("div").find("p").addClass("background");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .andSelf().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Tómas T.
    Nice!
    The .andself makes alot of sense. Can't wait to use it at work
    I'm excited about the new redesign of the site :)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.contents() – jQuery API

jQuery API

Skip to content
  • api

.contents()

Categories: Traversing > Miscellaneous Traversing

.contents() Returns: jQuery

Description: Get the children of each element in the set of matched elements, including text nodes.

  • version added: 1.2.contents()

Given a jQuery object that represents a set of DOM elements, the .contents() method allows us to search through the immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .contents() and .children() methods are similar, except that the former includes text nodes as well as HTML elements in the resulting jQuery object.

Consider a simple <div> with a number of text nodes, each of which is separated by two line break elements (<br />):

<div class="container">
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
  do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  <br /><br />
  Ut enim ad minim veniam, quis nostrud exercitation ullamco
  laboris nisi ut aliquip ex ea commodo consequat.
  <br /> <br />
  Duis aute irure dolor in reprehenderit in voluptate velit
  esse cillum dolore eu fugiat nulla pariatur.
</div>

We can employ the .contents() method to help convert this blob of text into three well-formed paragraphs:

$('.container').contents().filter(function() {
  return this.nodeType == 3;
})
  .wrap('<p></p>')
.end()
.filter('br')
  .remove();

This code first retrieves the contents of <div class="container"> and then filters it for text nodes, which are wrapped in paragraph tags. This is accomplished by testing the .nodeType property of the element. This DOM property holds a numeric code indicating the node's type; text nodes use the code 3. The contents are again filtered, this time for <br /> elements, and these elements are removed.

Example:

Find all the text nodes inside a paragraph and wrap them with a bold tag.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello <a href="http://ejohn.org/">John</a>, how are you doing?</p>
<script>$("p").contents().filter(function(){ return this.nodeType != 1; }).wrap("<b/>");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .contents().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Karl Stanton
    I found this very useful with trying to access an iFrame as seen in this blog post:

    http://simple.procoding.net/2008/03/21/how-to-a...

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.end() – jQuery API

jQuery API

Skip to content
  • api

.end()

Categories: Traversing > Miscellaneous Traversing

.end() Returns: jQuery

Description: End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

  • version added: 1.0.end()

Most of the methods in this chapter operate on a jQuery object and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use end() to pop the sets back off of the stack.

Suppose we have a couple short lists on a page:

<ul class="first">
   <li class="foo">list item 1</li>
   <li>list item 2</li>
   <li class="bar">list item 3</li>
</ul>
<ul class="second">
   <li class="foo">list item 1</li>
   <li>list item 2</li>
   <li class="bar">list item 3</li>
</ul>

The end() method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so we don't need to manipulate the stack. With end(), though, we can string all the method calls together:

$('ul.first').find('.foo').css('background-color', 'red')
  end().find('.bar').css('background-color', 'green');

This chain searches for items with the class foo within the first list only and turns their backgrounds red. Then end() returns the object to its state before the call to find(), so the second find() looks for '.bar' inside <ul class="first">, not just inside that list's <li class="foo">, and turns the matching elements' backgrounds green. The net result is that items 1 and 3 of the first list have a colored background, and none of the items from the second list do.

A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and end() methods closing them:

$('ul.first').find('.foo')
  .css('background-color', 'red')
.end().find('.bar')
  .css('background-color', 'green')
.end();

The last end() is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form, the end() provides visual symmetry and closure—making the program, at least to the eyes of some developers, more readable.

Examples:

Example: Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>
  p, div { margin:1px; padding:1px; font-weight:bold;
           font-size:16px; }
  div { color:blue; }
  b { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    Hi there <span>how</span> are you <span>doing</span>?
  </p>

  <p>
    This <span>span</span> is one of
    several <span>spans</span> in this
    <span>sentence</span>.
  </p>

  <div>
    Tags in jQuery object initially: <b></b>
  </div>
  <div>
    Tags in jQuery object after find: <b></b>

  </div>
  <div>
    Tags in jQuery object after end: <b></b>
  </div>
<script>

    jQuery.fn.showTags = function (n) {
      var tags = this.map(function () {
                              return this.tagName;
                            })
                        .get().join(", ");
      $("b:eq(" + n + ")").text(tags);
      return this;
    };

    $("p").showTags(0)
          .find("span")
          .showTags(1)
          .css("background", "yellow")
          .end()
          .showTags(2)
          .css("font-style", "italic");

</script>
</body>
</html>

Demo:

Example: Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.

<!DOCTYPE html>
<html>
<head>
  <style>p { margin:10px; padding:10px; }</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><span>Hello</span>, how are you?</p>
<script>$("p").find("span").end().css("border", "2px red solid");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .end().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Hadrian
    I think there should be a dot before "end" in the first example.
  • azoff
    I can finally write my jQuery as one long incomprehensible chain! I sincerely hope that I never have to debug code that makes extensive use of this method. Chaining is great, but there is a lot to be said about readable code as well. If you are going to use this function then I highly suggest using the style guideline in the example, if not for your sake then for the sake of the guy who has to work on your code next.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Tree Traversal – jQuery API

jQuery API

Skip to content
  • api

Tree Traversal

  • .children()

    Get the children of each element in the set of matched elements, optionally filtered by a selector.

  • .closest()

    Get the first element that matches the selector, beginning at the current element and progressing up through the DOM tree.

  • .find()

    Get the descendants of each element in the current set of matched elements, filtered by a selector.

  • .next()

    Get the immediately following sibling of each element in the set of matched elements, optionally filtered by a selector.

  • .nextAll()

    Get all following siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .nextUntil()

    Get all following siblings of each element up to but not including the element matched by the selector.

  • .offsetParent()

    Get the closest ancestor element that is positioned.

  • .parent()

    Get the parent of each element in the current set of matched elements, optionally filtered by a selector.

  • .parents()

    Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector.

  • .parentsUntil()

    Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector.

  • .prev()

    Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector.

  • .prevAll()

    Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .prevUntil()

    Get all preceding siblings of each element up to but not including the element matched by the selector.

  • .siblings()

    Get the siblings of each element in the set of matched elements, optionally filtered by a selector.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.children() – jQuery API

jQuery API

Skip to content
  • api

.children()

Categories: Traversing > Tree Traversal

.children( [ selector ] ) Returns: jQuery

Description: Get the children of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.0.children( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .children() method allows us to search through the immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .find() and .children() methods are similar, except that the latter only travels a single level down the DOM tree.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at the level-2 list, we can find its children:

$('ul.level-2').children().css('background-color', 'red');

The result of this call is a red background behind items A, B, and C. Since we do not supply a selector expression, all of the children are part of the returned jQuery object. If we had supplied one, only the matching items among these three would be included.

Examples:

Example: Find all children of the clicked element.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { font-size:16px; font-weight:bolder; }
  div { width:130px; height:82px; margin:10px; float:left;
        border:1px solid blue; padding:4px; }
  #container { width:auto; height:105px; margin:0; float:none;
        border:none; }
  .hilite { border-color:red; }
  #results { display:block; color:red; }
  p { margin:10px; border:1px solid transparent; }
  span { color:blue; border:1px solid transparent; }
  input { width:100px; }
  em { border:1px solid transparent; }
  a { border:1px solid transparent; }
  b { border:1px solid transparent; }
  button { border:1px solid transparent; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="container">

    <div>
      <p>This <span>is the <em>way</em> we</span>
      write <em>the</em> demo,</p>

    </div>
    <div>
      <a href="#"><b>w</b>rit<b>e</b></a> the <span>demo,</span> <button>write
      the</button> demo,
    </div>

    <div>
      This <span>the way we <em>write</em> the <em>demo</em> so</span>

      <input type="text" value="early" /> in
    </div>
    <p>
      <span>t</span>he <span>m</span>orning.
      <span id="results">Found <span>0</span> children in <span>TAG</span>.</span>

    </p>
  </div>
<script>

    $("#container").click(function (e) {
      $("*").removeClass("hilite");
      var $kids = $(e.target).children();
      var len = $kids.addClass("hilite").length;

      $("#results span:first").text(len);
      $("#results span:last").text(e.target.tagName);

      e.preventDefault();
      return false;
    });
</script>
</body>
</html>

Demo:

Example: Find all children of each div.

<!DOCTYPE html>
<html>
<head>
  <style>
  body { font-size:16px; font-weight:bolder; }
  span { color:blue; }
  p { margin:5px 0; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello (this is a paragraph)</p>

  <div><span>Hello Again (this span is a child of the a div)</span></div>
  <p>And <span>Again</span> (in another paragraph)</p>

  <div>And One Last <span>Time</span> (most text directly in a div)</div>
<script>$("div").children().css("border-bottom", "3px double red");</script>
</body>
</html>

Demo:

Example: Find all children with a class "selected" of each div.

<!DOCTYPE html>
<html>
<head>
  <style>

  body { font-size:16px; font-weight:bolder; }
  p { margin:5px 0; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <span>Hello</span>
    <p class="selected">Hello Again</p>
    <div class="selected">And Again</div>

    <p>And One Last Time</p>
  </div>
<script>$("div").children(".selected").css("color", "blue");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .children().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • janbaars
    How to get the text "And Again" from above example. (it's a child div).
    and it will be loaded in $result
    $("#result").text();

    thanks. jan

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.closest() – jQuery API

jQuery API

Skip to content
  • api

.closest()

Categories: Traversing > Tree Traversal
Contents:
  • closest( selector )
    • .closest( selector )
    • .closest( selector, [ context ] )
  • closest( selectors, [ context ] )
    • .closest( selectors, [ context ] )

.closest( selector ) Returns: jQuery

Description: Get the first element that matches the selector, beginning at the current element and progressing up through the DOM tree.

  • version added: 1.3.closest( selector )

    selectorA string containing a selector expression to match elements against.

  • version added: 1.4.closest( selector, [ context ] )

    selectorA string containing a selector expression to match elements against.

    contextA DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.

Given a jQuery object that represents a set of DOM elements, the .closest() method allows us to search through these elements and their ancestors in the DOM tree and construct a new jQuery object from the matching elements. The .parents() and .closest() methods are similar in that they both traverse up the DOM tree. The differences between the two, though subtle, are significant:

.closest() | .parents()
Begins with the current element | Begins with the parent element
Travels up the DOM tree until it finds a match for the supplied selector | Travels up the DOM tree to the document's root element, adding each ancestor element to a temporary collection; it then filters that collection based on a selector if one is supplied
The returned jQuery object contains zero or one element | The returned jQuery object contains zero, one, or multiple elements
  <ul id="one" class="level-1">
    <li class="item-i">I</li>
    <li id="ii" class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

Suppose we perform a search for <ul> elements starting at item A:

$('li.item-a').closest('ul')
  .css('background-color', 'red');

This will change the color of the level-2 <ul>, since it is the first encountered when traveling up the DOM tree.

Suppose we search for an <li> element instead:

$('li.item-a').closest('li')
  .css('background-color', 'red');

This will change the color of list item A. The .closest() method begins its search with the element itself before progressing up the DOM tree, and stops when item A matches the selector.

We can pass in a DOM element as the context within which to search for the closest element.

var listItemII = document.getElementById('ii');
$('li.item-a').closest('ul', listItemII)
  .css('background-color', 'red');
$('li.item-a').closest('#one', listItemII)
  .css('background-color', 'green');

This will change the color of the level-2 <ul>, because it is both the first <ul> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <ul>, however, because it is not a descendant of list item II.

Example:

Show how event delegation can be done with closest.

<!DOCTYPE html>
<html>
<head>
  <style>
  li { margin: 3px; padding: 3px; background: #EEEEEE; }
  li.hilight { background: yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
<li><b>Click me!</b></li>
<li>You can also <b>Click me!</b></li>
</ul>
<script>

    $(document).bind("click", function (e) {
      $(e.target).closest("li").toggleClass("hilight");
    });
</script>
</body>
</html>

Demo:

.closest( selectors, [ context ] ) Returns: Array

Description: Gets an array of all the elements and selectors matched against the current element up through the DOM tree.

  • version added: 1.4.closest( selectors, [ context ] )

    selectorsAn array of string containing a selector expression to match elements against (can also be a jQuery object).

    contextA DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.

This method is primarily meant to be used internally or by plugin authors.

Example:

Show how event delegation can be done with closest.

<!DOCTYPE html>
<html>
<head>
  <style></style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul><li></li><li></li></ul>
<script>var close = $("li:first").closest(["ul", "body"]);
$.each(close, function(i){
  $("li").eq(i).html( this.selector + ": " + this.elem.nodeName );
});</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .closest().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • PekkaS
    Yes, very useful. jQuery traversing tools are mostly targeted "inwards" and this is must have for getting parent DIV info without too much hassle. Here's getting surrounding DIV's ID when you click an item (deep) inside it:

    jQuery('#someitem').click(function(){
    parent_id = jQuery(this).closest("div[class='myparentclass']").attr("id");
    });
  • srhoades
    Best enhancement to jQuery!

    This is extremely useful as I have encountered many instances where simply finding the parent() element is insufficient.

    Previously doing a $('.obj').parent().parent().find("ul") can be replaced by a $('obj').closest('ul');

    Thank you!
  • Bob
    Can it be replaced in all instances? As the documentation shows, .closest() returns one element, while .find() returns all elements that were found. So if you wanted instead to get all the ul which are children of the obj's parents, with closest you will only get one of those children.
  • Daz
    I agree, my favourite too. This was in the last version of jQuery by the way, I bet you're kicking yourself for not knowing :)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.find() – jQuery API

jQuery API

Skip to content
  • api

.find()

Categories: Traversing > Tree Traversal

.find( selector ) Returns: jQuery

Description: Get the descendants of each element in the current set of matched elements, filtered by a selector.

  • version added: 1.0.find( selector )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .find() method allows us to search through the descendants of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .find() and .children() methods are similar, except that the latter only travels a single level down the DOM tree.

The method accepts a selector expression of the same type that we can pass to the $() function. The elements will be filtered by testing whether they match this selector.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item II, we can find list items within it:

$('li.item-ii').find('li').css('background-color', 'red');

The result of this call is a red background on items A, B, 1, 2, 3, and C. Even though item II matches the selector expression, it is not included in the results; only descendants are considered candidates for the match.

As discussed in “The jQuery Factory Function” section above, selector context is implemented with the .find() method; therefore, $('li.item-ii').find('li') is equivalent to $('li', 'li.item-ii').

Unlike in the rest of the tree traversal methods, the selector expression is required in a call to .find(). If we need to retrieve all of the descendant elements, we can pass in the universal selector '*' to accomplish this.

Examples:

Example: Starts with all paragraphs and searches for descendant span elements, same as $("p span")

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p><span>Hello</span>, how are you?</p>

  <p>Me? I'm <span>good</span>.</p>
<script>$("p").find("span").css('color','red');</script>
</body>
</html>

Demo:

Example: Add spans around each word then add a hover and italicize words with the letter t.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { font-size:20px; width:200px; cursor:default;
      color:blue; font-weight:bold; margin:0 10px; }
  .hilite { background:yellow; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    When the day is short
    find that which matters to you
    or stop believing
  </p>
<script>
    var newText = $("p").text().split(" ").join("</span> <span>");
    newText = "<span>" + newText + "</span>";

    $("p").html(newText)
          .find('span')
            .hover(function () { $(this).addClass("hilite"); },
                   function () { $(this).removeClass("hilite"); })
          .end()
          .find(":contains('t')")
            .css({"font-style":"italic", "font-weight":"bolder"});

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .find().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.next() – jQuery API

jQuery API

Skip to content
  • api

.next()

Categories: Traversing > Tree Traversal

.next( [ selector ] ) Returns: jQuery

Description: Get the immediately following sibling of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.0.next( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .next() method allows us to search through the successors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find the element which comes just after it:

$('li.third-item').next().css('background-color', 'red');

The result of this call is a red background behind item 4. Since we do not supply a selector expression, this following element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

Examples:

Example: Find the very next sibling of each disabled button and change its text "this button is disabled".

<!DOCTYPE html>
<html>
<head>
  <style>

  span { color:blue; font-weight:bold; }
  button { width:100px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><button disabled="disabled">First</button> - <span></span></div>
  <div><button>Second</button> - <span></span></div>

  <div><button disabled="disabled">Third</button> - <span></span></div>
<script>$("button[disabled]").next().text("this button is disabled");</script>
</body>
</html>

Demo:

Example: Find the very next sibling of each paragraph. Keep only the ones with a class "selected".

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>Hello</p>

  <p class="selected">Hello Again</p>
  <div><span>And Again</span></div>
<script>$("p").next(".selected").css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .next().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.nextAll() – jQuery API

jQuery API

Skip to content
  • api

.nextAll()

Categories: Traversing > Tree Traversal

.nextAll( [ selector ] ) Returns: jQuery

Description: Get all following siblings of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.2.nextAll( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .nextAll() method allows us to search through the successors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find the elements which come after it:

$('li.third-item').nextAll().css('background-color', 'red');

The result of this call is a red background behind items 4 and 5. Since we do not supply a selector expression, these following elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.

Examples:

Example: Locate all the divs after the first and give them a class.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { width: 80px; height: 80px; background: #abc;
        border: 2px solid black; margin: 10px; float: left; }
  div.after { border-color: red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>first</div>
  <div>sibling<div>child</div></div>
  <div>sibling</div>

  <div>sibling</div>
<script>$("div:first").nextAll().addClass("after");</script>
</body>
</html>

Demo:

Example: Locate all the paragraphs after the second child in the body and give them a class.

<!DOCTYPE html>
<html>
<head>
  <style>
  div, p { width: 60px; height: 60px; background: #abc;
           border: 2px solid black; margin: 10px; float: left; }
  .after { border-color: red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>p</p>

  <div>div</div>
  <p>p</p>
  <p>p</p>
  <div>div</div>

  <p>p</p>
  <div>div</div>
<script>
    $(":nth-child(1)").nextAll("p").addClass("after");
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .nextAll().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.nextUntil() – jQuery API

jQuery API

Skip to content
  • api

.nextUntil()

Categories: Traversing > Tree Traversal

.nextUntil( [ selector ] ) Returns: jQuery

Description: Get all following siblings of each element up to but not including the element matched by the selector.

  • version added: 1.4.nextUntil( [ selector ] )

    selectorA string containing a selector expression to indicate where to stop matching following sibling elements.

Given a jQuery object that represents a set of DOM elements, the .nextUntil() method allows us to search through the successors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all following siblings up to but not including the one matched by the .nextUntil() selector.

If the selector is not matched or is not supplied, all following siblings will be selected; in these cases it selects the same elements as the .nextAll() method does when no filter selector is provided.

Consider a page with a simple definition list as follows:

<dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>

If we begin at the second term, we can find the elements which come after it until a following <dt>.

$('#term-2').nextUntil('dt').css('background-color', 'red');

The result of this call is a red background behind definitions 2-a, 2-b, and 2-c.

Example:

Find the siblings that follow <dt id="term-2"> up to the next <dt> and give them a red background color.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>
<script>
    $("#term-2").nextUntil("dt")
      .css("background-color", "red")
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .nextUntil().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Bob
    Forgot to add that I was using Firefox 3.5.3 on Ubuntu 8.04 with Firebug. I can't say how the results will turn out in other browsers, but there will probably be a similarly dramatic difference.
  • Bob
    I did some basic benchmarking of nextUntil() to test the speed. Here, the javascript is traversing a table of this format:

    <table>
    <tbody>
    <tr id='jqueryfirstrow1'><td>Text</td><td><pre>Text</pre></td><td>Text</td></tr>
    <tr><td>Text</td><td><pre>Text</pre></td><td>Text</td></tr>
    ... snip tr 1120 times ...
    <tr id='jquerylastrow1' ><td>Text</td><td><pre>Text</pre></td><td>Text</td></tr>
    ... snip 5 more tr ...
    </tbody>
    </table>

    Here is the javascript:

    var firstRow = jQuery('#jqueryfirstrow1');
    var time = new Date();
    var row = firstRow.next();
    var rowArray = [];
    while (row.length && !row.is('#jquerylastrow1')) {
    rowArray.push(row[0]);
    row = row.next();
    }
    console.log('Total time with next: ' + ((new Date()) - time));

    rowArray = [];
    var time = new Date();
    var row = firstRow;
    var rowArray = row.nextUntil('#jquerylastrow1');
    console.log('Total time with nextUntil: ' + ((new Date()) - time));

    var time = new Date();
    var row = document.getElementById('jqueryfirstrow1').nextSibling;
    var rowArray = [];
    while (!!row && (row.id != 'jquerylastrow1')) {
    rowArray.push(row);
    row = row.nextSibling;
    }
    console.log('Total time with nextSibling: ' + ((new Date()) - time));

    Basically, in the end you should always end up with the same rows in the array. Performing the above ten times in a row and averaging the results, I get this:

    Average time with next: 236
    Average time with nextUntil: 164
    Average time with nextSibling: 11

    As the results show, just going with plain javascript is a massive performance improvement over using jQuery to retrieve the rows, at least when you use id's to identify the table rows between which your result set will be.

    Also, nextUntil is a significant improvement over putting something together using only next, and of course has the versatility of using any jQuery selector.

    Additionally, you can use jQuery on the rowArray generated using plain javascript to use the jQuery functions in the examples above on those rows. I tried this and it was on average 200ms faster when the rows are first retrieved using plain javascript.

    It won't make that much of a difference when you only have three elements as in the examples above, but it certainly is something to keep in mind when you're handling large amounts of elements and performance is critical.
  • "Cowboy" Ben Alman
    FYI, If you're interested in how this method came to be, check out
    jQuery Untils: nextUntil, prevUntil, parentsUntil

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.offsetParent() – jQuery API

jQuery API

Skip to content
  • api

.offsetParent()

Categories: Traversing > Tree Traversal

.offsetParent() Returns: jQuery

Description: Get the closest ancestor element that is positioned.

  • version added: 1.26.offsetParent()

Given a jQuery object that represents a set of DOM elements, the .offsetParent() method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object wrapped around the closest positioned ancestor. An element is said to be positioned if it has a CSS position attribute of relative, absolute, or fixed. This information is useful for calculating offsets for performing animations and placing objects on the page.

Consider a page with a basic nested list on it, with a positioned element:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii" style="position: relative;">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item A, we can find its positioned ancestor:

$('li.item-a').offsetParent().css('background-color', 'red');

This will change the color of list item II, which is positioned.

Example:

Find the offsetParent of item "A."

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

    <ul class="level-1">
      <li class="item-i">I</li>
      <li class="item-ii" style="position: relative;">II
        <ul class="level-2">
          <li class="item-a">A</li>
          <li class="item-b">B
            <ul class="level-3">
              <li class="item-1">1</li>
              <li class="item-2">2</li>
              <li class="item-3">3</li>
            </ul>
          </li>
          <li class="item-c">C</li>
        </ul>
      </li>
      <li class="item-iii">III</li>
    </ul>

<script>$('li.item-a').offsetParent().css('background-color', 'red');</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .offsetParent().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.parent() – jQuery API

jQuery API

Skip to content
  • api

.parent()

Categories: Traversing > Tree Traversal

.parent( [ selector ] ) Returns: jQuery

Description: Get the parent of each element in the current set of matched elements, optionally filtered by a selector.

  • version added: 1.0.parent( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .parent() method allows us to search through the parents of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .parents() and .parent() methods are similar, except that the latter only travels a single level up the DOM tree.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item A, we can find its parents:

$('li.item-a').parent().css('background-color', 'red');

The result of this call is a red background for the level-2 list. Since we do not supply a selector expression, the parent element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

Examples:

Example: Shows the parent of each element as (parent > child). Check the View Source to see the raw html.

<!DOCTYPE html>
<html>
<head>
  <style>
  div,p { margin:10px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>div,
    <span>span, </span>
    <b>b </b>

  </div>
  <p>p,
    <span>span,
      <em>em </em>
    </span>
  </p>

  <div>div,
    <strong>strong,
      <span>span, </span>
      <em>em,
        <b>b, </b>
      </em>

    </strong>
    <b>b </b>
  </div>
<script>

    $("*", document.body).each(function () {
      var parentTag = $(this).parent().get(0).tagName;
      $(this).prepend(document.createTextNode(parentTag + " > "));
    });
</script>
</body>
</html>

Demo:

Example: Find the parent element of each paragraph with a class "selected".

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><p>Hello</p></div>

  <div class="selected"><p>Hello Again</p></div>

<script>$("p").parent(".selected").css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .parent().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.parents() – jQuery API

jQuery API

Skip to content
  • api

.parents()

Categories: Traversing > Tree Traversal

.parents( [ selector ] ) Returns: jQuery

Description: Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector.

  • version added: 1.0.parents( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .parents() method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .parents() and .parent() methods are similar, except that the latter only travels a single level up the DOM tree.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item A, we can find its ancestors:

$('li.item-a').parents().css('background-color', 'red');

The result of this call is a red background for the level-2 list, item II, and the level-1 list (and on up the DOM tree all the way to the <html> element). Since we do not supply a selector expression, all of the ancestors are part of the returned jQuery object. If we had supplied one, only the matching items among these would be included.

Examples:

Example: Find all parent elements of each b.

<!DOCTYPE html>
<html>
<head>
  <style>
  b, span, p, html body {
    padding: .5em;
    border: 1px solid;
  }
  b { color:blue; }
  strong { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>
    <p>
      <span>
        <b>My parents are: </b>
      </span>

    </p>
  </div>
<script>
    var parentEls = $("b").parents()
                          .map(function () {
                                return this.tagName;
                              })
                          .get().join(", ");
    $("b").append("<strong>" + parentEls + "</strong>");

</script>
</body>
</html>

Demo:

Example: Click to find all unique div parent elements of each span.

<!DOCTYPE html>
<html>
<head>
  <style>

  p, div, span {margin:2px; padding:1px; }
  div { border:2px white solid; }
  span { cursor:pointer; font-size:12px; }
  .selected { color:blue; }
  b { color:red; display:block; font-size:14px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
    <div>
      <div><span>Hello</span></div>
      <span>Hello Again</span>

    </div>
    <div>
      <span>And Hello Again</span>
    </div>
  </p>

  <b>Click Hellos to toggle their parents.</b>
<script>
    function showParents() {
      $("div").css("border-color", "white");
      var len = $("span.selected")
                       .parents("div")
                       .css("border", "2px red solid")
                       .length;
      $("b").text("Unique div parents: " + len);
    }
    $("span").click(function () {
      $(this).toggleClass("selected");
      showParents();
    });</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .parents().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.parentsUntil() – jQuery API

jQuery API

Skip to content
  • api

.parentsUntil()

Categories: Traversing > Tree Traversal

.parentsUntil( [ selector ] ) Returns: jQuery

Description: Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector.

  • version added: 1.4.parentsUntil( [ selector ] )

    selectorA string containing a selector expression to indicate where to stop matching ancestor elements.

Given a jQuery object that represents a set of DOM elements, the .parentsUntil() method traverses through the ancestors of these elements until it reaches an element matched by the selector passed in the method's argument. The resulting jQuery object contains all of the ancestors up to but not including the one matched by the .parentsUntil() selector. Consider a page with a basic nested list as follows:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item A, we can find its ancestors up to but not including <ul class="level-1"> as follows:

$('li.item-a').parentsUntil('.level-1')
    .css('background-color', 'red');

The result of this call is a red background for the level-2 list and the item II.

If the .parentsUntil() selector is not matched, or if no selector is supplied, the returned jQuery object contains all of the previous jQuery object's ancestors. For example, let's say we begin at item A again, but this time we use a selector that is not matched by any of its ancestors:

$('li.item-a').parentsUntil('.not-here')
    .css('background-color', 'red');

The result of this call is a red background-color style applied to the level-2 list, the item II, the level-1 list, the <body> element, and the <html> element.

Example:

Find the ancestors of <li class="item-a"> up to <ul class="level-1"> and give them a red background color.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>
<script>
    $('li.item-a').parentsUntil('.level-1')
      .css('background-color', 'red');
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .parentsUntil().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Brian
    There is a typo here...

    If we begin at item A, we can find its ancestors up to but not including <li class="level-1"> as follows:

    should be

    If we begin at item A, we can find its ancestors up to but not including <ul class="level-1"> as follows:
  • John Resig
    Good catch, fixed.
  • Emil Stjerneman
    This is awesome! Toghter with nextUntil() and prevUntil() this will ROCK MY WORLD!
  • Francois-Guillaume Ribreau
    Yeah ! Great improvements here !
  • "Cowboy" Ben Alman
    FYI, If you're interested in how this method came to be, check out
    jQuery Untils: nextUntil, prevUntil, parentsUntil

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.prev() – jQuery API

jQuery API

Skip to content
  • api

.prev()

Categories: Traversing > Tree Traversal

.prev( [ selector ] ) Returns: jQuery

Description: Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.0.prev( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .prev() method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find the element which comes just before it:

$('li.third-item').prev().css('background-color', 'red');

The result of this call is a red background behind item 2. Since we do not supply a selector expression, this preceding element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.

Examples:

Example: Find the very previous sibling of each div.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:40px; height:40px; margin:10px;
        float:left; border:2px blue solid;
        padding:2px; }
  span { font-size:14px; }
  p { clear:left; margin:10px; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div></div>
  <div><span>has child</span></div>

  <div></div>
  <div></div>
  <div></div>
  <div id="start"></div>

  <div></div>
  <p><button>Go to Prev</button></p>
<script>
    var $curr = $("#start");
    $curr.css("background", "#f99");
    $("button").click(function () {
      $curr = $curr.prev();
      $("div").css("background", "");
      $curr.css("background", "#f99");
    });

</script>
</body>
</html>

Demo:

Example: For each paragraph, find the very previous sibling that has a class "selected".

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><span>Hello</span></div>

  <p class="selected">Hello Again</p>
  <p>And Again</p>
<script>$("p").prev(".selected").css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .prev().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.prevAll() – jQuery API

jQuery API

Skip to content
  • api

.prevAll()

Categories: Traversing > Tree Traversal

.prevAll( [ selector ] ) Returns: jQuery

Description: Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.2.prevAll( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .prevAll() method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find the elements which come before it:

$('li.third-item').prevAll().css('background-color', 'red');

The result of this call is a red background behind items 1 and 2. Since we do not supply a selector expression, these preceding elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.

Example:

Locate all the divs in front of the last div and give them a class.

<!DOCTYPE html>
<html>
<head>
  <style>

  div { width:70px; height:70px; background:#abc;
        border:2px solid black; margin:10px; float:left; }
  div.before { border-color: red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <div></div>
  <div></div>
  <div></div>
<script>$("div:last").prevAll().addClass("before");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .prevAll().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.prevUntil() – jQuery API

jQuery API

Skip to content
  • api

.prevUntil()

Categories: Traversing > Tree Traversal

.prevUntil( [ selector ] ) Returns: jQuery

Description: Get all preceding siblings of each element up to but not including the element matched by the selector.

  • version added: 1.4.prevUntil( [ selector ] )

    selectorA string containing a selector expression to indicate where to stop matching preceding sibling elements.

Given a jQuery object that represents a set of DOM elements, the .prevUntil() method allows us to search through the predecessors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all previous siblings up to but not including the one matched by the .prevUntil() selector.

If the selector is not matched or is not supplied, all previous siblings will be selected; in these cases it selects the same elements as the .prevUntil() method does when no filter selector is provided.

Consider a page with a simple definition list as follows:

<dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>

If we begin at the second term, we can find the elements which come after it until a preceding <dt>.

$('#term-2').prevUntil('dt').css('background-color', 'red');

The result of this call is a red background behind definitions 1-a, 1-b, 1-c, and 1-d.

Example:

Find the siblings that precede <dt id="term-2"> up to the preceding <dt> and give them a red background color.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <dl>
  <dt>term 1</dt>
  <dd>definition 1-a</dd>
  <dd>definition 1-b</dd>
  <dd>definition 1-c</dd>
  <dd>definition 1-d</dd>

  <dt id="term-2">term 2</dt>
  <dd>definition 2-a</dd>
  <dd>definition 2-b</dd>
  <dd>definition 2-c</dd>

  <dt>term 3</dt>
  <dd>definition 3-a</dd>
  <dd>definition 3-b</dd>
</dl>
<script>
    $("#term-2").prevUntil("dt")
      .css("background-color", "red")
</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .prevUntil().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Shawphy
    "in these cases it selects the same elements as the .prevUntil() method does when no filter selector is provided."

    maybe ".prevUntil()" is ".prevAll()"
  • "Cowboy" Ben Alman
    FYI, If you're interested in how this method came to be, check out
    jQuery Untils: nextUntil, prevUntil, parentsUntil

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


.siblings() – jQuery API

jQuery API

Skip to content
  • api

.siblings()

Categories: Traversing > Tree Traversal

.siblings( [ selector ] ) Returns: jQuery

Description: Get the siblings of each element in the set of matched elements, optionally filtered by a selector.

  • version added: 1.0.siblings( [ selector ] )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .siblings() method allows us to search through the siblings of these elements in the DOM tree and construct a new jQuery object from the matching elements.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

Consider a page with a simple list on it:

<ul>
   <li>list item 1</li>
   <li>list item 2</li>
   <li class="third-item">list item 3</li>
   <li>list item 4</li>
   <li>list item 5</li>
</ul>

If we begin at the third item, we can find its siblings:

$('li.third-item').siblings().css('background-color', 'red');

The result of this call is a red background behind items 1, 2, 4, and 5. Since we do not supply a selector expression, all of the siblings are part of the object. If we had supplied one, only the matching items among these four would be included.

The original element is not included among the siblings, which is important to remember when we wish to find all elements at a particular level of the DOM tree.

Examples:

Example: Find the unique siblings of all yellow li elements in the 3 lists (including other yellow li elements if appropriate).

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { float:left; margin:5px; font-size:16px; font-weight:bold; }
  p { color:blue; margin:10px 20px; font-size:16px; padding:5px;
      font-weight:bolder; }
  .hilite { background:yellow; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <ul>
    <li>One</li>

    <li>Two</li>
    <li class="hilite">Three</li>
    <li>Four</li>
  </ul>

  <ul>
    <li>Five</li>
    <li>Six</li>
    <li>Seven</li>

  </ul>
  <ul>
    <li>Eight</li>
    <li class="hilite">Nine</li>

    <li>Ten</li>
    <li class="hilite">Eleven</li>
  </ul>
  <p>Unique siblings: <b></b></p>
<script>

    var len = $(".hilite").siblings()
                          .css("color", "red")
                          .length;
    $("b").text(len);
</script>
</body>
</html>

Demo:

Example: Find all siblings with a class "selected" of each div.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div><span>Hello</span></div>

  <p class="selected">Hello Again</p>
  <p>And Again</p>
<script>$("p").siblings(".selected").css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to .siblings().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


Utilities – jQuery API

jQuery API

Skip to content
  • api

Utilities

  • jQuery.boxModel

    Deprecated in jQuery 1.3 (see jQuery.support). States if the current page, in the user's browser, is being rendered using the W3C CSS Box Model.

  • jQuery.browser

    Properties of the Global jQuery Object

    We recommend against using this property, please try to use feature detection instead (see jQuery.support). Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.

  • .clearQueue()

    Custom, Data

    Remove from the queue all items that have not yet been run.

  • jQuery.contains()

    Check to see if a DOM node is within another DOM node.

  • jQuery.data()

    Data

    Store arbitrary data associated with the specified element.

  • .dequeue()

    Custom, Data

    Execute the next function on the queue for the matched elements.

  • jQuery.dequeue()

    Data

    Execute the next function on the queue for the matched elements.

  • jQuery.each()

    Iterates through the array displaying each number as both a word and numeral

  • jQuery.extend()

    Merge the contents of two or more objects together into the first object.

  • jQuery.globalEval()

    Execute some JavaScript code globally.

  • jQuery.grep()

    Finds the elements of an array which satisfy a filter function. The original array is not affected.

  • jQuery.inArray()

    Report the index of some elements in the array.

  • jQuery.isArray()

    Determine whether the argument is an array.

  • jQuery.isEmptyObject()

    Check to see if an object is empty (contains no properties).

  • jQuery.isFunction()

    Determine if the argument passed is a Javascript function object.

  • jQuery.isPlainObject()

    Check to see if an object is a plain object (created using "{}" or "new Object").

  • jQuery.isXMLDoc()

    Check to see if a DOM node is within an XML document (or is an XML document).

  • jQuery.makeArray()

    Convert an array-like object into a true JavaScript array.

  • jQuery.map()

    Translate all items in an array or array-like object to another array of items.

  • jQuery.merge()

    Merge the contents of two arrays together into the first array.

  • jQuery.noop

    An empty function.

  • jQuery.proxy()

    Event Handler Attachment

    Takes a function and returns a new one that will always have a particular scope.

  • .queue()

    Custom, Data

    Show the queue of functions to be executed on the matched elements.

  • jQuery.queue()

    Data

    Show the queue of functions to be executed on the matched elements.

  • jQuery.removeData()

    Data

    Remove a previously-stored piece of data.

  • jQuery.support

    Properties of the Global jQuery Object

    A collection of properties that represent the presence of different browser features or bugs.

  • jQuery.trim()

    Remove the whitespace from the beginning and end of a string.

  • jQuery.unique()

    Create a copy of an array of DOM elements with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.boxModel – jQuery API

jQuery API

Skip to content
  • api

jQuery.boxModel

Categories: Utilities

jQuery.boxModel Returns: Boolean

Description: Deprecated in jQuery 1.3 (see jQuery.support). States if the current page, in the user's browser, is being rendered using the W3C CSS Box Model.

  • version added: 1.0jQuery.boxModel

Examples:

Example: Returns the box model for the iframe.

<!DOCTYPE html>
<html>
<head>
  <style>

  p { color:blue; margin:20px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <p>
  </p>
<script>

    $("p").html("The box model for this iframe is: <span>" +
                jQuery.boxModel + "</span>");
</script>
</body>
</html>

Demo:

Example: Returns false if the page is in Quirks Mode in Internet Explorer

$.boxModel

Result:

false

Comments

  • Please keep comments relevant to jQuery.boxModel.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.contains() – jQuery API

jQuery API

Skip to content
  • api

jQuery.contains()

Categories: Utilities

jQuery.contains( container, contained ) Returns: Boolean

Description: Check to see if a DOM node is within another DOM node.

  • version added: 1.4jQuery.contains( container, contained )

    containerThe DOM element that may contain the other element.

    containedThe DOM node that may be contained by the other element.

Example:

Check if an element is inside another.

jQuery.contains(document.documentElement, document.body); // true
jQuery.contains(document.body, document.documentElement); // false

Comments

  • Please keep comments relevant to jQuery.contains().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • Yukulélé
    document.documentElement = <html>
    document.body = <body>
  • aaron hendrick
    Given the examples, it seems that the second argument is the container, not the contained, ie the body is the container for the documentElement.
  • Karl Swedberg
    document.documentElement contains document.body, so the examples have the arguments in the correct order.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.each() – jQuery API

jQuery API

Skip to content
  • api

jQuery.each()

Categories: Utilities

jQuery.each( object, callback(indexInArray, valueOfElement) ) Returns: Object

Description: A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties.

  • version added: 1.0jQuery.each( object, callback(indexInArray, valueOfElement) )

    objectThe object or array to iterate over.

    callback(indexInArray, valueOfElement)The function that will be executed on every object. this is the valueOfElement

This function is not the same as $().each() - which is used to iterate, exclusively, over a jQuery object. This function can be used to iterate over anything.

The callback has two arguments: the key (objects) or index (arrays) as the first, and the value as the second.

If you wish to break the each loop at a particular iteration you can do so by making your function return false. Returning non-false is the same as a continue statement in a for loop; it will skip immediately to the next iteration.

Examples:

Example: Iterates through the array displaying each number as both a word and numeral

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  div#five { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div id="one"></div>
  <div id="two"></div>

  <div id="three"></div>
  <div id="four"></div>
  <div id="five"></div>
<script>
    var arr = [ "one", "two", "three", "four", "five" ];
    var obj = { one:1, two:2, three:3, four:4, five:5 };

    jQuery.each(arr, function() {
      $("#" + this).text("My id is " + this + ".");
      return (this !== "four"); // will stop running to skip "five"

    });

    jQuery.each(obj, function(i, val) {
      $("#" + i).append(document.createTextNode(" - " + val));
    });
</script>
</body>
</html>

Demo:

Example: Iterates over items in an array, accessing both the current item and its index.

$.each( ['a','b','c'], function(i, l){
   alert( "Index #" + i + ": " + l );
 });

Example: Iterates over the properties in an object, accessing both the current item and its key.

$.each( { name: "John", lang: "JS" }, function(k, v){
   alert( "Key: " + k + ", Value: " + v );
 });

Comments

  • Please keep comments relevant to jQuery.each().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • yanpeng
    Nice!
  • Karl Swedberg
    Thanks for the report! Fixed now.
  • brostbeef
    The last example has an error:
    function(k, v){
    alert( "Key: " + k + ", Value: " + c );

    Notice that it should be using "k" & "v", not "k" & "c" in the alert

    Otherwise... great documentation!
  • Karl Swedberg
    Thanks for the report! Fixed now. (sorry for the double comment. forgot to "reply" the first time.)

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.extend() – jQuery API

jQuery API

Skip to content
  • api

jQuery.extend()

Categories: Utilities

jQuery.extend( target, [ object1 ], [ objectN ] ) Returns: Object

Description: Merge the contents of two or more objects together into the first object.

  • version added: 1.0jQuery.extend( target, [ object1 ], [ objectN ] )

    target An object that will receive the new properties if additional objects are passed in or that will extend the jQuery namespace if it is the sole argument.

    object1An object containing additional properties to merge in.

    objectNAdditional objects containing properties to merge in.

  • version added: 1.1.4jQuery.extend( [ deep ], target, object1, [ objectN ] )

    deepIf true, the merge becomes recursive (aka. deep copy).

    targetThe object to extend. It will receive the new properties.

    object1An object containing additional properties to merge in.

    objectNAdditional objects containing properties to merge in.

When we supply two or more objects to $.extend(), properties from all of the objects are added to the target object.

If only one argument is supplied to $.extend(), this means the target argument was omitted. In this case, the jQuery object itself is assumed to be the target. By doing this, we can add new functions to the jQuery namespace. This can be useful for plugin authors wishing to add new methods to JQuery.

Keep in mind that the target object (first argument) will be modified, and will also be returned from $.extend(). If, however, we want to preserve both of the original objects, we can do so by passing an empty object as the target:

var object = $.extend({}, object1, object2);

The merge performed by $.extend() is not recursive by default; if a property of the first object is itself an object or array, it will be completely overwritten by a property with the same key in the second object. The values are not merged. This can be seen in the example below by examining the value of banana. However, by passing true for the first function argument, objects will be recursively merged.

Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over.

Examples:

Example: Merge two objects, modifying the first.

var object1 = {
  apple: 0,
  banana: {weight: 52, price: 100},
  cherry: 97
};
var object2 = {
  banana: {price: 200},
  durian: 100
};

$.extend(object1, object2);

Result:

object1 === {apple: 0, banana: {price: 200}, cherry: 97, durian: 100}

Example: Merge two objects recursively, modifying the first.

var object1 = {
  apple: 0,
  banana: {weight: 52, price: 100},
  cherry: 97
};
var object2 = {
  banana: {price: 200},
  durian: 100
};

$.extend(true, object1, object2);

Result:

object1 === {apple: 0, banana: {weight: 52, price: 200}, cherry: 97, durian: 100}

Example: Merge settings and options, modifying settings.

var settings = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
jQuery.extend(settings, options);

Result:

settings == { validate: true, limit: 5, name: "bar" }

Example: Merge defaults and options, without modifying the defaults. This is a common plugin development pattern.

var empty = {}
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
var settings = $.extend(empty, defaults, options);

Result:

settings == { validate: true, limit: 5, name: "bar" }
empty == { validate: true, limit: 5, name: "bar" }

Comments

  • Please keep comments relevant to jQuery.extend().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • azoff
    don't forget this little tidbit from the old docs: "If no target is specified, the JQuery namespace itself is extended. This can be useful for plugin authors wishing to add new methods to JQuery"
  • Karl Swedberg
    We already mention that in the second paragraph above. I did go in and edit the entry to try to clarify a couple things, so thanks for bringing this to our attention.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.globalEval() – jQuery API

jQuery API

Skip to content
  • api

jQuery.globalEval()

Categories: Utilities

jQuery.globalEval( code )

Description: Execute some JavaScript code globally.

  • version added: 1.0.4jQuery.globalEval( code )

    codeThe JavaScript code to execute.

This method behaves differently from using a normal JavaScript eval() in that it's executed within the global context (which is important for loading external scripts dynamically).

Example:

Execute a script in the global context.

function test(){
    jQuery.globalEval("var newVar = true;")
}
test();
// newVar === true

Comments

  • Please keep comments relevant to jQuery.globalEval().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • rafael
    what is a good use case for this, doesn't this go against Doug Crockford's "eval is evil" principle.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.grep() – jQuery API

jQuery API

Skip to content
  • api

jQuery.grep()

Categories: Utilities

jQuery.grep( array, function(elementOfArray, indexInArray), [ invert ] ) Returns: Array

Description: Finds the elements of an array which satisfy a filter function. The original array is not affected.

  • version added: 1.0jQuery.grep( array, function(elementOfArray, indexInArray), [ invert ] )

    arrayThe array to search through.

    function(elementOfArray, indexInArray)The function to process each item against. The first argument to the function is the item, and the second argument is the index. The function should return a Boolean value. this will be the global window object.

    invertIf "invert" is false, or not provided, then the function returns an array consisting of all elements for which "callback" returns true. If "invert" is true, then the function returns an array consisting of all elements for which "callback" returns false.

The $.grep() method removes items from an array as necessary so that all remaining items pass a provided test. The test is a function that is passed an array item and the index of the item within the array. Only if the test returns true will the item be in the result array.

The filter function will be passed two arguments: the current array item and its index. The filter function must return 'true' to include the item in the result array.

Examples:

Example: Filters the original array of numbers leaving that are not 5 and have an index greater than 4. Then it removes all 9s.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  p { color:green; margin:0; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <p></p>
  <span></span>

<script>
var arr = [ 1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1 ];
$("div").text(arr.join(", "));

arr = jQuery.grep(arr, function(n, i){
  return (n != 5 && i > 4);
});
$("p").text(arr.join(", "));

arr = jQuery.grep(arr, function (a) { return a != 9; });
$("span").text(arr.join(", "));

</script>
</body>
</html>

Demo:

Example: Filter an array of numbers to include only numbers bigger then zero.

$.grep( [0,1,2], function(n,i){
   return n > 0;
 });

Result:

[1, 2]

Example: Filter an array of numbers to include numbers that are not bigger than zero.

$.grep( [0,1,2], function(n,i){
    return n > 0;
},true);

Result:

[0]

Comments

  • Please keep comments relevant to jQuery.grep().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.inArray() – jQuery API

jQuery API

Skip to content
  • api

jQuery.inArray()

Categories: Utilities

jQuery.inArray( value, array ) Returns: Number

Description:

  • version added: 1.2jQuery.inArray( value, array )

    valueThe value to search for.

    arrayAn array through which to search.

The $.inArray() method is similar to JavaScript's native .indexOf() method in that it returns -1 when it doesn't find a match. If the first element within the array matches value, $.inArray() returns 0.

Because JavaScript treats 0 as loosely equal to false (i.e. 0 == false, but 0 !== false), if we're checking for the presence of value within array, we need to check if it's not equal to (or greater than) -1.

Example:

Report the index of some elements in the array.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  span { color:red; }
</style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

<div>"John" found at <span></span></div>
<div>4 found at <span></span></div>
<div>"Karl" not found, so <span></span></div>
<script>var arr = [ 4, "Pete", 8, "John" ];

$("span:eq(0)").text(jQuery.inArray("John", arr));
$("span:eq(1)").text(jQuery.inArray(4, arr));
$("span:eq(2)").text(jQuery.inArray("Karl", arr));

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.inArray().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.isArray() – jQuery API

jQuery API

Skip to content
  • api

jQuery.isArray()

Categories: Utilities

jQuery.isArray( obj ) Returns: boolean

Description: Determine whether the argument is an array.

  • version added: 1.3jQuery.isArray( obj )

    objObject to test whether or not it is an array.

$.isArray() returns a Boolean indicating whether the object is a JavaScript array (not an array-like object, such as a jQuery object).

Example:

Finds out if the parameter is an array.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    Is [] an Array? <b></b>
<script>$("b").append( "" + $.isArray([]) );</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.isArray().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.isEmptyObject() – jQuery API

jQuery API

Skip to content
  • api

jQuery.isEmptyObject()

Categories: Utilities

jQuery.isEmptyObject( object ) Returns: Boolean

Description: Check to see if an object is empty (contains no properties).

  • version added: 1.4jQuery.isEmptyObject( object )

    objectThe object that will be checked to see if it's empty.

As of jQuery 1.4 this method checks both properties on the object itself and properties inherited from prototypes (in that it doesn't use hasOwnProperty).

Example:

Check an object to see if it's empty.

jQuery.isEmptyObject({}) // true
jQuery.isEmptyObject({ foo: "bar" }) // false

Comments

  • Please keep comments relevant to jQuery.isEmptyObject().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.isFunction() – jQuery API

jQuery API

Skip to content
  • api

jQuery.isFunction()

Categories: Utilities

jQuery.isFunction() Returns: boolean

Description: Determine if the argument passed is a Javascript function object.

  • version added: 1.2jQuery.isFunction()

Note: As of jQuery 1.3, functions provided by the browser like alert() and DOM element methods like getAttribute() are not guaranteed to be detected as functions in browsers such as Internet Explorer.

Examples:

Example: Test a few parameter examples.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; margin:2px; font-size:14px; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>

  <div>jQuery.isFunction(objs[0]) = <span></span></div>

  <div>jQuery.isFunction(objs[1]) = <span></span></div>
  <div>jQuery.isFunction(objs[2]) = <span></span></div>
  <div>jQuery.isFunction(objs[3]) = <span></span></div>

  <div>jQuery.isFunction(objs[4]) = <span></span></div>

<script>
    function stub() {
    }
    var objs = [
          function () {},
          { x:15, y:20 },
          null,
          stub,
          "function"
        ];

    jQuery.each(objs, function (i) {
      var isFunc = jQuery.isFunction(objs[i]);
      $("span").eq(i).text(isFunc);
    });
</script>
</body>
</html>

Demo:

Example: Finds out if the parameter is a funcion.

$.isFunction(function(){});

Result:

true

Comments

  • Please keep comments relevant to jQuery.isFunction().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.isPlainObject() – jQuery API

jQuery API

Skip to content
  • api

jQuery.isPlainObject()

Categories: Utilities

jQuery.isPlainObject( object ) Returns: Boolean

Description: Check to see if an object is a plain object (created using "{}" or "new Object").

  • version added: 1.4jQuery.isPlainObject( object )

    objectThe object that will be checked to see if it's an object literal.

Example:

Check an object to see if it's a plain object.

jQuery.isPlainObject({}) // true
jQuery.isPlainObject("test") // false

Comments

  • Please keep comments relevant to jQuery.isPlainObject().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • build_your_web
    "The object that will be checked to see if it's an object literal."
    - if it's a plain object.
  • Robert Katić
    Replace 2 "isObjectLiteral" with "isPlainObject".
  • John Resig
    Good catch, fixed.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.isXMLDoc() – jQuery API

jQuery API

Skip to content
  • api

jQuery.isXMLDoc()

Categories: Utilities

jQuery.isXMLDoc( node ) Returns: Boolean

Description: Check to see if a DOM node is within an XML document (or is an XML document).

  • version added: 1.1.4jQuery.isXMLDoc( node )

    nodeThe DOM node that will be checked to see if it's in an XML document.

Example:

Check an object to see if it's in an XML document.

jQuery.isXMLDoc(document) // false
jQuery.isXMLDoc(document.body) // false

Comments

  • Please keep comments relevant to jQuery.isXMLDoc().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.makeArray() – jQuery API

jQuery API

Skip to content
  • api

jQuery.makeArray()

Categories: Utilities

jQuery.makeArray( obj ) Returns: Array

Description: Convert an array-like object into a true JavaScript array.

  • version added: 1.2jQuery.makeArray( obj )

    objAny object to turn into a native Array.

Many methods, both in jQuery and in JavaScript in general, return objects that are array-like. For example, the jQuery factory function $() returns a jQuery object that has many of the properties of an array (a length, the [] array access operator, etc.), but is not exactly the same as an array and lacks some of an array's built-in methods (such as .pop() and .reverse()).

Note that after the conversion, any special features the object had (such as the jQuery methods in our example) will no longer be present. The object is now a plain array.

Examples:

Example: Turn a collection of HTMLElements into an Array of them.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>First</div>
  <div>Second</div>
  <div>Third</div>

  <div>Fourth</div>
<script>
    var elems = document.getElementsByTagName("div"); // returns a nodeList
    var arr = jQuery.makeArray(elems);
    arr.reverse(); // use an Array method on list of dom elements
    $(arr).appendTo(document.body);
</script>
</body>
</html>

Demo:

Example: Turn a jQuery object into an array

    var obj = $('li');
    var arr = $.makeArray(obj);

Result:

(typeof obj === 'object' && obj.jquery) === true;
jQuery.isArray(arr) === true;

Comments

  • Please keep comments relevant to jQuery.makeArray().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • jackysee
    Can it be use for $.makeArray(arguments)?
  • Karl Swedberg
    No, but for that you can just do something like this:

    function arrayFromArgs() {
    return Array.slice.call(arguments);
    }

    and then call it:

    arrayFromArgs('3', '2', '4');

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.map() – jQuery API

jQuery API

Skip to content
  • api

jQuery.map()

Categories: Utilities

jQuery.map( array, callback(elementOfArray, indexInArray) ) Returns: Array

Description: Translate all items in an array or array-like object to another array of items.

  • version added: 1.0jQuery.map( array, callback(elementOfArray, indexInArray) )

    arrayThe Array to translate.

    callback(elementOfArray, indexInArray)The function to process each item against. The first argument to the function is the list item, the second argument is the index in array The function can return any value. this will be the global window object.

The $.map() method applies a function to each item in an array, collecting the results into a new array.

The translation function that is provided to this method is called for each item in the array and is passed two arguments: The item to be translated, and the index within the array.

The function can return:

  • the translated value, which will be mapped to the resulting array
  • null, to remove the item
  • an array of values, which will be flattened into the full array

Map can iterate through Array-like objects, like a jQuery object, that have a length property.

Examples:

Example: A couple examples of using .map()

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  p { color:green; margin:0; }
  span { color:red; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div></div>
  <p></p>
  <span></span>

<script>

    var arr = [ "a", "b", "c", "d", "e" ];
    $("div").text(arr.join(", "));

    arr = jQuery.map(arr, function(n, i){
      return (n.toUpperCase() + i);
    });
    $("p").text(arr.join(", "));

    arr = jQuery.map(arr, function (a) { return a + a; });
    $("span").text(arr.join(", "));

</script>
</body>
</html>

Demo:

Example: Maps the original array to a new one and adds 4 to each value.

$.map( [0,1,2], function(n){
   return n + 4;
 });

Result:

[4, 5, 6]

Example: Maps the original array to a new one and adds 1 to each value if it is bigger then zero, otherwise it's removed.

$.map( [0,1,2], function(n){
   return n > 0 ? n + 1 : null;
 });

Result:

[2, 3]

Example: Maps the original array to a new one, each element is added with it's original value and the value plus one.

$.map( [0,1,2], function(n){
   return [ n, n + 1 ];
 });

Result:

[0, 1, 1, 2, 2, 3]

Example: Maps the original array to a new one, each element is squared.

$.map( [0,1,2,3], function (a) { return a * a; } );

Result:

[0, 1, 4, 9]

Example: Remove items by returning null from the function. This removes any numbers less than 50, and the rest are decreased by 45.

$.map( [0, 1, 52, 97], function (a) { return (a > 50 ? a - 45 : null); } );

Result:

[7, 52]

Example: Augmenting the resulting array by returning an array inside the function.

var array = [0, 1, 52, 97];
array = $.map(array, function(a, index) {
  return [a - 45, index];
});

Result:

[-45, 0, -44, 1, 7, 2, 52, 3]

Comments

  • Please keep comments relevant to jQuery.map().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.merge() – jQuery API

jQuery API

Skip to content
  • api

jQuery.merge()

Categories: Utilities

jQuery.merge( first, second ) Returns: Array

Description: Merge the contents of two arrays together into the first array.

  • version added: 1.0jQuery.merge( first, second )

    firstThe first array to merge, the elements of second added.

    secondThe second array to merge into the first, unaltered.

The $.merge() operation forms an array that contains all elements from the two arrays. The orders of items in the arrays are preserved, with items from the second array appended. The $.merge() function is destructive. It alters the first parameter to add the items from the second.

If you need the original first array, make a copy of it before calling $.merge(). Fortunately, $.merge() itself can be used for this duplication:

var newArray = $.merge([], oldArray);

This shortcut creates a new, empty array and merges the contents of oldArray into it, effectively cloning the array.

The arguments should be true Javascript Array objects; use $.makeArray if they are not.

Examples:

Example: Merges two arrays, altering the first argument.

$.merge( [0,1,2], [2,3,4] )

Result:

[0,1,2,2,3,4]

Example: Merges two arrays, altering the first argument.

$.merge( [3,2,1], [4,3,2] )

Result:

[3,2,1,4,3,2]

Example: Merges two arrays, but uses a copy, so the original isn't altered.

var first = ['a','b','c'];
var second = ['d','e','f'];
$.merge( $.merge([],first), second);

Result:

["a","b","c","d","e","f"]

Comments

  • Please keep comments relevant to jQuery.merge().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.noop – jQuery API

jQuery API

Skip to content
  • api

jQuery.noop

Categories: Utilities

jQuery.noop Returns: Function

Description: An empty function.

  • version added: 1.4jQuery.noop

You can use this empty function when you wish to pass around a function that will do nothing.

This is useful for plugin authors who offer optional callbacks; in the case that no callback is given, something like jQuery.noop could execute.

Comments

  • Please keep comments relevant to jQuery.noop.
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum
  • joemccann
    Here's where it may be useful, or at least my first usage:

    $('a').bind('click', function(){
    var href = $(this).attr('href');
    // Make bookmarkable.
    !location.hash ? location.href += href : $.noop();
    return false;
    });

    And your html would be an anchor tag where the href was equal to "#foo".
  • Karl Swedberg
    $.noop returns the sound of one hand clapping.
  • xr
    doesn't null works??
    null不行吗?????
  • SmokeyBones
    i want "foo" "foobar"
  • human3rror
    AHAHAHHAAH
  • Marco Rogers
    It's not overly useful. But typing $.noop is 6 chars shorter than function(){}. Also if you use this everywhere instead of creating new, anonymous, empty functions, you'll slightly cut down on memory.
  • serkanyersen
    It's like Prototype.K shorthand for function(){}

    it can be useful for validating callbacks such as:

    function myFunc(num, callback){

    var x = num * 100;

    # run callback if provided
    (callback || $.noop)( x );

    return x;
    }

  • David Pio
    I think it is used for functions that require a callback as a parameter..but you don't want to do anything in a callback..rather than creating empty functions all the time..do this..
  • JustAJoke
    I Guess is for compatibility with NaDa

    http://www.bernardbelanger.com/computing/NaDa/i...
  • WildeMan
    Ok.. ok... ok this maybe a noobish type question, but what is this useful?

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.trim() – jQuery API

jQuery API

Skip to content
  • api

jQuery.trim()

Categories: Utilities

jQuery.trim() Returns: String

Description: Remove the whitespace from the beginning and end of a string.

  • version added: 1.0jQuery.trim()

Examples:

Example: Removes the two whitespaces at the start and at the end of the string.

<!DOCTYPE html>
<html>
<head>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <button>Show Trim Example</button>
<script>

    $("button").click(function () {
      var str = "     lots of spaces before and after     ";
      alert("'" + str + "'");

      str = jQuery.trim(str);
      alert("'" + str + "' - no longer");
    });

</script>
</body>
</html>

Demo:

Example: Removes the two whitespaces at the start and at the end of the string.

$.trim("  hello, how are you?  ");

Result:

"hello, how are you?"

Comments

  • Please keep comments relevant to jQuery.trim().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery.unique() – jQuery API

jQuery API

Skip to content
  • api

jQuery.unique()

Categories: Utilities

jQuery.unique( array ) Returns: Array

Description: Create a copy of an array of DOM elements with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.

  • version added: 1.1.3jQuery.unique( array )

    arrayThe Array of DOM elements.

The $.unique() function searches through an array of objects, forming a new array that does not contain duplicate objects. This function only works on plain JavaScript arrays of DOM elements, and is chiefly used internally by jQuery.

As of jQuery 1.4 the results will always be returned in document order.

Example:

Removes any duplicate elements from the array of divs.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:blue; }
  </style>
  <script src="/scripts/jquery-1.4.js"></script>
</head>
<body>
    <div>There are 6 divs in this document.</div>
  <div></div>
  <div class="dup"></div>
  <div class="dup"></div>

  <div class="dup"></div>
  <div></div>
<script>

    var divs = $("div").get(); // unique() must take a native array

    // add 3 elements of class dup too (they are divs)
    divs = divs.concat($(".dup").get());
    $("div:eq(1)").text("Pre-unique there are " + divs.length + " elements.");

    divs = jQuery.unique(divs);
    $("div:eq(2)").text("Post-unique there are " + divs.length + " elements.")
                  .css("color", "red");

</script>
</body>
</html>

Demo:

Comments

  • Please keep comments relevant to jQuery.unique().
  • Additional examples and requests for clarification are encouraged, but please do not use these comments as a bug tracker or support forum.
  • Please report bugs on the bug tracker or the jQuery Forum.
  • Request support on the jQuery Forum

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities


jQuery API

jQuery API

Skip to content
  • api

jQuery API

  • .add()

    Miscellaneous Traversing

    Add elements to the set of matched elements.

  • .addClass()

    Attributes, CSS, Class Attribute

    Adds the specified class(es) to each of the set of matched elements.

  • .after()

    DOM Insertion, Outside

    Insert content, specified by the parameter, after each element in the set of matched elements.

  • jQuery.ajax()

    Low-Level Interface

    Perform an asynchronous HTTP (Ajax) request.

  • .ajaxComplete()

    Global Ajax Event Handlers

    Register a handler to be called when Ajax requests complete. This is an Ajax Event.

  • .ajaxError()

    Global Ajax Event Handlers

    Register a handler to be called when Ajax requests complete with an error. This is an Ajax Event.

  • .ajaxSend()

    Global Ajax Event Handlers

    Show a message before an Ajax request is sent.

  • jQuery.ajaxSetup()

    Low-Level Interface

    Set default values for future Ajax requests.

  • .ajaxStart()

    Global Ajax Event Handlers

    Register a handler to be called when the first Ajax request begins. This is an Ajax Event.

  • .ajaxStop()

    Global Ajax Event Handlers

    Hide a loading message after all the Ajax requests have stopped.

  • .ajaxSuccess()

    Global Ajax Event Handlers

    Show a message when an Ajax request completes successfully.

  • All Selector (“*”)

    Basic

    Selects all elements.

  • .andSelf()

    Miscellaneous Traversing

    Add the previous set of elements on the stack to the current set.

  • .animate()

    Custom

    Perform a custom animation of a set of CSS properties.

  • :animated Selector

    Basic Filter

    Select all elements that are in the progress of an animation at the time the selector is run.

  • .append()

    DOM Insertion, Inside

    Insert content, specified by the parameter, to the end of each element in the set of matched elements.

  • .appendTo()

    DOM Insertion, Inside

    Insert every element in the set of matched elements to the end of the target.

  • .attr()

    Attributes, General Attributes

    Get the value of an attribute for the first element in the set of matched elements.

  • Attribute Contains Prefix Selector [name|=value]

    Attribute

    Selects elements that have the specified attribute with a value either equal to a given string or starting with that string followed by a hyphen (-).

  • Attribute Contains Selector [name*=value]

    Attribute

    Selects elements that have the specified attribute with a value containing the a given substring.

  • Attribute Contains Word Selector [name~=value]

    Attribute

    Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.

  • Attribute Ends With Selector [name$=value]

    Attribute

    Selects elements that have the specified attribute with a value ending exactly with a given string.

  • Attribute Equals Selector [name=value]

    Attribute

    Selects elements that have the specified attribute with a value exactly equal to a certain value.

  • Attribute Not Equal Selector [name!=value]

    Attribute

    Select elements that either don't have the specified attribute, or do have the specified attribute but not with a certain value.

  • Attribute Starts With Selector [name^=value]

    Attribute

    Selects elements that have the specified attribute with a value beginning exactly with a given string.

  • .before()

    DOM Insertion, Outside

    Insert content, specified by the parameter, before each element in the set of matched elements.

  • .bind()

    Event Handler Attachment

    Attach a handler to an event for the elements.

  • .blur()

    Form Events, Forms

    Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.

  • jQuery.boxModel

    Utilities

    Deprecated in jQuery 1.3 (see jQuery.support). States if the current page, in the user's browser, is being rendered using the W3C CSS Box Model.

  • jQuery.browser

    Properties of the Global jQuery Object, Utilities

    We recommend against using this property, please try to use feature detection instead (see jQuery.support). Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.

  • :button Selector

    Form

    Selects all button elements and elements of type button.

  • .change()

    Form Events, Forms

    Bind an event handler to the "change" JavaScript event, or trigger that event on an element.

  • :checkbox Selector

    Form

    Selects all elements of type checkbox.

  • :checked Selector

    Form

    Matches all elements that are checked.

  • Child Selector (“parent > child”)

    Hierarchy

    Selects all direct child elements specified by "child" of elements specified by "parent".

  • .children()

    Tree Traversal

    Get the children of each element in the set of matched elements, optionally filtered by a selector.

  • Class Selector (“.class”)

    Basic

    Selects all elements with the given class.

  • .clearQueue()

    Custom, Data, Utilities

    Remove from the queue all items that have not yet been run.

  • .click()

    Mouse Events

    Bind an event handler to the "click" JavaScript event, or trigger that event on an element.

  • .clone()

    Copying

    Create a copy of the set of matched elements.

  • .closest()

    Tree Traversal

    Get the first element that matches the selector, beginning at the current element and progressing up through the DOM tree.

  • jQuery.contains()

    Utilities

    Check to see if a DOM node is within another DOM node.

  • :contains() Selector

    Content Filter

    Select all elements that contain the specified text.

  • .contents()

    Miscellaneous Traversing

    Get the children of each element in the set of matched elements, including text nodes.

  • .context

    Plugin Authoring, Properties of jQuery Object Instances

    The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.

  • .css()

    CSS, Style Properties

    Get the value of a style property for the first element in the set of matched elements.

  • .data()

    Data Storage

    Store arbitrary data associated with the matched elements.

  • jQuery.data()

    Data, Utilities

    Store arbitrary data associated with the specified element.

  • .dblclick()

    Mouse Events

    Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.

  • .delay()

    Custom

    Set a timer to delay execution of subsequent items in the queue.

  • .dequeue()

    Custom, Data, Utilities

    Execute the next function on the queue for the matched elements.

  • jQuery.dequeue()

    Data, Utilities

    Execute the next function on the queue for the matched elements.

  • Descendant Selector (“ancestor descendant”)

    Hierarchy

    Selects all elements that are descendants of a given ancestor.

  • .detach()

    DOM Removal

    Remove the set of matched elements from the DOM.

  • .die()

    Event Handler Attachment

    Remove an event handler previously attached using .live() from the elements.

  • :disabled Selector

    Form

    Selects all elements that are disabled.

  • jQuery.each()

    Utilities

    Iterates through the array displaying each number as both a word and numeral

  • .each()

    Collection Manipulation

    Iterate over a jQuery object, executing a function for each matched element.

  • Element Selector (“element”)

    Basic

    Selects all elements with the given tag name.

  • .empty()

    DOM Removal

    Remove all child nodes of the set of matched elements from the DOM.

  • :empty Selector

    Content Filter

    Select all elements that have no children (including text nodes).

  • :enabled Selector

    Form

    Selects all elements that are enabled.

  • .end()

    Miscellaneous Traversing

    End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

  • .eq()

    Filtering

    Reduce the set of matched elements to the one at the specified index.

  • :eq() Selector

    Basic Filter

    Select the element at index n within the matched set.

  • .error()

    Browser Events

    Bind an event handler to the "error" JavaScript event.

  • :even Selector

    Basic Filter

    Selects even elements, zero-indexed. See also odd.

  • event.currentTarget

    Event Object

    The current DOM element within the event bubbling phase.

  • event.data

    Event Object

    Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound.

  • event.isDefaultPrevented()

    Event Object

    Returns whether event.preventDefault() was ever called on this event object.

  • event.isImmediatePropagationStopped()

    Event Object

    Returns whether event.stopImmediatePropagation() was ever called on this event object.

  • event.isPropagationStopped()

    Event Object

    Returns whether event.stopPropagation() was ever called on this event object.

  • event.pageX

    Event Object

    The mouse position relative to the left edge of the document.

  • event.pageY

    Event Object

    The mouse position relative to the top edge of the document.

  • event.preventDefault

    Event Object

    If this method is called, the default action of the event will not be triggered.

  • event.relatedTarget

    Event Object

    The other DOM element involved in the event, if any.

  • event.result

    Event Object

    This attribute contains the last value returned by an event handler that was triggered by this event, unless the value was undefined.

  • event.stopImmediatePropagation()

    Event Object

    Prevents other event handlers from being called.

  • event.stopPropagation()

    Event Object

    This method prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.

  • event.target

    Event Object

    The DOM element that initiated the event.

  • event.timeStamp

    Event Object

    This attribute returns the number of milliseconds since January 1, 1970, when the event is triggered.

  • event.type

    Event Object

    Describes the nature of the event.

  • event.which

    Event Object

    For key or button events, this attribute indicates the specific button or key that was pressed.

  • jQuery.extend()

    Utilities

    Merge the contents of two or more objects together into the first object.

  • .fadeIn()

    Fading

    Display the matched elements by fading them to opaque.

  • .fadeOut()

    Fading

    Hide the matched elements by fading them to transparent.

  • .fadeTo()

    Fading

    Adjust the opacity of the matched elements.

  • :file Selector

    Form

    Selects all elements of type file.

  • .filter()

    Filtering

    Reduce the set of matched elements to those that match the selector or pass the function's test.

  • .find()

    Tree Traversal

    Get the descendants of each element in the current set of matched elements, filtered by a selector.

  • .first()

    Filtering

    Reduce the set of matched elements to the first in the set.

  • :first-child Selector

    Child Filter

    Selects all elements that are the first child of their parent.

  • :first Selector

    Basic Filter

    Selects the first matched element.

  • .focus()

    Form Events, Forms

    Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.

  • .focusin()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusin" JavaScript event.

  • .focusout()

    Keyboard Events, Mouse Events

    Bind an event handler to the "focusout" JavaScript event.

  • jQuery.fx.off

    Custom, Properties of the Global jQuery Object

    Globally disable all animations.

  • jQuery.get()

    Shorthand Methods

    Load data from the server using a HTTP GET request.

  • .get()

    DOM Element Methods

    Retrieve the DOM elements matched by the jQuery object.

  • jQuery.getJSON()

    Shorthand Methods

    Load JSON-encoded data from the server using a GET HTTP request.

  • jQuery.getScript()

    Shorthand Methods

    Load a JavaScript file from the server using a GET HTTP request, then execute it.

  • jQuery.globalEval()

    Utilities

    Execute some JavaScript code globally.

  • jQuery.grep()

    Utilities

    Finds the elements of an array which satisfy a filter function. The original array is not affected.

  • :gt() Selector

    Basic Filter

    Select all elements at an index greater than index within the matched set.

  • .has()

    Filtering

    Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.

  • Has Attribute Selector [name]

    Attribute

    Selects elements that have the specified attribute, with any value.

  • :has() Selector

    Content Filter

    Selects elements which contain at least one element that matches the specified selector.

  • .hasClass()

    Attributes, CSS, Class Attribute

    Determine whether any of the matched elements are assigned the given class.

  • :header Selector

    Basic Filter

    Selects all elements that are headers, like h1, h2, h3 and so on.

  • .height()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements.

  • :hidden Selector

    Visibility Filter

    Selects all elements that are hidden.

  • .hide()

    Basics

    Hide the matched elements.

  • .hover()

    Mouse Events

    Bind two handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.

  • .html()

    Attributes, DOM Insertion

    Get the HTML contents of the first element in the set of matched elements.

  • ID Selector (“#id”)

    Basic

    Selects a single element with the given id attribute.

  • :image Selector

    Form

    Selects all elements of type image.

  • jQuery.inArray()

    Utilities

    Report the index of some elements in the array.

  • .index()

    DOM Element Methods

    Search for a given element from among the matched elements.

  • .innerHeight()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding but not border.

  • .innerWidth()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding but not border.

  • :input Selector

    Form

    Selects all input, textarea, select and button elements.

  • .insertAfter()

    DOM Insertion, Outside

    Insert every element in the set of matched elements after the target.

  • .insertBefore()

    DOM Insertion, Outside

    Insert every element in the set of matched elements before the target.

  • .is()

    Filtering

    Check the current matched set of elements against a selector and return true if at least one of these elements matches the selector.

  • jQuery.isArray()

    Utilities

    Determine whether the argument is an array.

  • jQuery.isEmptyObject()

    Utilities

    Check to see if an object is empty (contains no properties).

  • jQuery.isFunction()

    Utilities

    Determine if the argument passed is a Javascript function object.

  • jQuery.isPlainObject()

    Utilities

    Check to see if an object is a plain object (created using "{}" or "new Object").

  • jQuery.isXMLDoc()

    Utilities

    Check to see if a DOM node is within an XML document (or is an XML document).

  • jQuery()

    Core

    Accepts a string containing a CSS selector which is then used to match a set of elements.

  • .keydown()

    Keyboard Events

    Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.

  • .keypress()

    Keyboard Events

    Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.

  • .keyup()

    Keyboard Events

    Bind an event handler to the "keyup" JavaScript event, or trigger that event on an element.

  • .last()

    Filtering

    Reduce the set of matched elements to the final one in the set.

  • :last-child Selector

    Child Filter

    Selects all elements that are the last child of their parent.

  • :last Selector

    Basic Filter

    Selects the last matched element.

  • .length

    Properties of jQuery Object Instances

    The number of elements in the jQuery object.

  • .live()

    Event Handler Attachment

    Attach a handler to the event for all elements which match the current selector, now or in the future.

  • .load()

    Shorthand Methods

    Load data from the server and place the returned HTML into the matched element.

  • .load()

    Document Loading

    Bind an event handler to the "load" JavaScript event.

  • :lt() Selector

    Basic Filter

    Select all elements at an index less than index within the matched set.

  • jQuery.makeArray()

    Utilities

    Convert an array-like object into a true JavaScript array.

  • .map()

    Filtering

    Pass each element in the current matched set through a function, producing a new jQuery object containing the return values..

  • jQuery.map()

    Utilities

    Translate all items in an array or array-like object to another array of items.

  • jQuery.merge()

    Utilities

    Merge the contents of two arrays together into the first array.

  • .mousedown()

    Mouse Events

    Bind an event handler to the "mousedown" JavaScript event, or trigger that event on an element.

  • .mouseenter()

    Mouse Events

    Bind an event handler to be fired when the mouse enters an element, or trigger that handler on an element.

  • .mouseleave()

    Mouse Events

    Bind an event handler to be fired when the mouse leaves an element, or trigger that handler on an element.

  • .mousemove()

    Mouse Events

    Bind an event handler to the "mousemove" JavaScript event, or trigger that event on an element.

  • .mouseout()

    Mouse Events

    Bind an event handler to the "mouseout" JavaScript event, or trigger that event on an element.

  • .mouseover()

    Mouse Events

    Bind an event handler to the "mouseover" JavaScript event, or trigger that event on an element.

  • .mouseup()

    Mouse Events

    Bind an event handler to the "mouseup" JavaScript event, or trigger that event on an element.

  • Multiple Attribute Selector [name=value][name2=value2]

    Attribute

    Matches elements that match all of the specified attribute filters.

  • Multiple Selector (“selector1, selector2, selectorN”)

    Basic

    Selects the combined results of all the specified selectors.

  • .next()

    Tree Traversal

    Get the immediately following sibling of each element in the set of matched elements, optionally filtered by a selector.

  • Next Adjacent Selector (“prev + next”)

    Hierarchy

    Selects all next elements matching "next" that are immediately preceded by a sibling "prev".

  • Next Siblings Selector (“prev ~ siblings”)

    Hierarchy

    Selects all sibling elements that follow after the "prev" element, have the same parent, and match the filtering "siblings" selector.

  • .nextAll()

    Tree Traversal

    Get all following siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .nextUntil()

    Tree Traversal

    Get all following siblings of each element up to but not including the element matched by the selector.

  • jQuery.noConflict()

    Core, Setup Methods

    Relinquish jQuery's control of the $ variable.

  • jQuery.noop

    Utilities

    An empty function.

  • .not()

    Filtering

    Remove elements from the set of matched elements.

  • :not() Selector

    Basic Filter

    Selects all elements that do not match the given selector.

  • :nth-child Selector

    Child Filter

    Selects all elements that are the nth-child of their parent.

  • :odd Selector

    Basic Filter

    Selects odd elements, zero-indexed. See also even.

  • .offset()

    CSS, Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • .offsetParent()

    Tree Traversal

    Get the closest ancestor element that is positioned.

  • .one()

    Event Handler Attachment

    Attach a handler to an event for the elements. The handler is executed at most once.

  • :only-child Selector

    Child Filter

    Selects all elements that are the only child of their parent.

  • .outerHeight()

    CSS, Dimensions, Style Properties

    Get the current computed height for the first element in the set of matched elements, including padding and border.

  • .outerWidth()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements, including padding and border.

  • jQuery.param()

    Collection Manipulation, Forms, Helper Functions

    Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request.

  • .parent()

    Tree Traversal

    Get the parent of each element in the current set of matched elements, optionally filtered by a selector.

  • :parent Selector

    Content Filter

    Select all elements that are the parent of another element, including text nodes.

  • .parents()

    Tree Traversal

    Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector.

  • .parentsUntil()

    Tree Traversal

    Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector.

  • :password Selector

    Form

    Selects all elements of type password.

  • .position()

    CSS, Offset, Style Properties

    Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.

  • jQuery.post()

    Shorthand Methods

    Load data from the server using a HTTP POST request.

  • .prepend()

    DOM Insertion, Inside

    Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.

  • .prependTo()

    DOM Insertion, Inside

    Insert every element in the set of matched elements to the beginning of the target.

  • .prev()

    Tree Traversal

    Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector.

  • .prevAll()

    Tree Traversal

    Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .prevUntil()

    Tree Traversal

    Get all preceding siblings of each element up to but not including the element matched by the selector.

  • jQuery.proxy()

    Event Handler Attachment, Utilities

    Takes a function and returns a new one that will always have a particular scope.

  • jQuery.pushStack()

    Plugin Authoring

    Add a collection of DOM elements onto the jQuery stack.

  • .queue()

    Custom, Data, Utilities

    Show the queue of functions to be executed on the matched elements.

  • jQuery.queue()

    Data, Utilities

    Show the queue of functions to be executed on the matched elements.

  • :radio Selector

    Form

    Selects all elements of type radio.

  • .ready()

    Document Loading

    Specify a function to execute when the DOM is fully loaded.

  • .remove()

    DOM Removal

    Remove the set of matched elements from the DOM.

  • .removeAttr()

    Attributes, General Attributes

    Remove an attribute from each element in the set of matched elements.

  • .removeClass()

    Attributes, CSS, Class Attribute

    Remove one or all classes from each element in the set of matched elements.

  • .removeData()

    Data Storage

    Remove a previously-stored piece of data.

  • jQuery.removeData()

    Data, Utilities

    Remove a previously-stored piece of data.

  • .replaceAll()

    DOM Replacement

    A selector expression indicating which element(s) to replace.

  • .replaceWith()

    DOM Replacement

    Replace each element in the set of matched elements with the provided new content.

  • :reset Selector

    Form

    Selects all elements of type reset.

  • .resize()

    Browser Events

    Bind an event handler to the "resize" JavaScript event, or trigger that event on an element.

  • .scroll()

    Browser Events

    Bind an event handler to the "scroll" JavaScript event, or trigger that event on an element.

  • .scrollLeft()

    CSS, Offset, Style Properties

    Get the current horizontal position of the scroll bar for the first element in the set of matched elements.

  • .scrollTop()

    CSS, Offset, Style Properties

    Get the current vertical position of the scroll bar for the first element in the set of matched elements.

  • .select()

    Form Events, Forms

    Bind an event handler to the "select" JavaScript event, or trigger that event on an element.

  • :selected Selector

    Form

    Selects all elements that are selected.

  • .selector

    Plugin Authoring, Properties of jQuery Object Instances

    A selector representing selector originally passed to jQuery().

  • .serialize()

    Forms, Helper Functions

    Encode a set of form elements as a string for submission.

  • .serializeArray()

    Forms, Helper Functions

    Encode a set of form elements as an array of names and values.

  • .show()

    Basics

    Display the matched elements.

  • .siblings()

    Tree Traversal

    Get the siblings of each element in the set of matched elements, optionally filtered by a selector.

  • .size()

    DOM Element Methods

    Return the number of DOM elements matched by the jQuery object.

  • .slice()

    Filtering

    Reduce the set of matched elements to a subset specified by a range of indices.

  • .slideDown()

    Sliding

    Display the matched elements with a sliding motion.

  • .slideToggle()

    Sliding

    Display or hide the matched elements with a sliding motion.

  • .slideUp()

    Sliding

    Hide the matched elements with a sliding motion.

  • .stop()

    Custom

    Stop the currently-running animation on the matched elements.

  • .submit()

    Form Events, Forms

    Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.

  • :submit Selector

    Form

    Selects all elements of type submit.

  • jQuery.support

    Properties of the Global jQuery Object, Utilities

    A collection of properties that represent the presence of different browser features or bugs.

  • .text()

    Attributes, DOM Insertion, Inside, General Attributes

    Get the combined text contents of each element in the set of matched elements, including their descendants.

  • :text Selector

    Form

    Selects all elements of type text.

  • .toArray()

    DOM Element Methods

    Retrieve all the DOM elements contained in the jQuery set, as an array.

  • .toggle()

    Basics, Mouse Events

    Bind two or more handlers to the matched elements, to be executed on alternate clicks.

  • .toggleClass()

    Attributes, CSS, Class Attribute

    Add or remove a class from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.

  • .trigger()

    Event Handler Attachment

    Execute all handlers and behaviors attached to the matched elements for the given event type.

  • .triggerHandler()

    Event Handler Attachment

    Execute all handlers attached to an element for an event.

  • jQuery.trim()

    Utilities

    Remove the whitespace from the beginning and end of a string.

  • .unbind()

    Event Handler Attachment

    Remove a previously-attached event handler from the elements.

  • jQuery.unique()

    Utilities

    Create a copy of an array of DOM elements with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.

  • .unload()

    Document Loading

    Bind an event handler to the "unload" JavaScript event.

  • .unwrap()

    DOM Insertion, Around, DOM Removal

    Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

  • .val()

    Attributes, Forms, General Attributes

    Get the current value of the first element in the set of matched elements.

  • :visible Selector

    Visibility Filter

    Selects all elements that are visible.

  • .width()

    CSS, Dimensions, Style Properties

    Get the current computed width for the first element in the set of matched elements.

  • .wrap()

    DOM Insertion, Around

    Wrap an HTML structure around each element in the set of matched elements.

  • .wrapAll()

    DOM Insertion, Around

    Wrap an HTML structure around all elements in the set of matched elements.

  • .wrapInner()

    DOM Insertion, Around

    Wrap an HTML structure around the content of each element in the set of matched elements.

jQuery API

    • New or Changed in 1.4
    • Raw XML API Dump
    • Dynamic API Browser
    • jQuery API Book

Browse the jQuery API

    • All
    • Ajax
      • Global Ajax Event Handlers
      • Helper Functions
      • Low-Level Interface
      • Shorthand Methods
    • Attributes
    • Core
    • CSS
    • Data
    • Dimensions
    • Effects
      • Basics
      • Custom
      • Fading
      • Sliding
    • Events
      • Browser Events
      • Document Loading
      • Event Handler Attachment
      • Event Object
      • Form Events
      • Keyboard Events
      • Mouse Events
    • Forms
    • Manipulation
      • Class Attribute
      • Copying
      • DOM Insertion
      • DOM Insertion, Around
      • DOM Insertion, Inside
      • DOM Insertion, Outside
      • DOM Removal
      • DOM Replacement
      • General Attributes
      • Style Properties
    • Miscellaneous
      • Collection Manipulation
      • Data Storage
      • DOM Element Methods
      • Setup Methods
    • Offset
    • Plugin Authoring
    • Properties
      • Properties of jQuery Object Instances
      • Properties of the Global jQuery Object
    • Selectors
      • Attribute
      • Basic
      • Basic Filter
      • Child Filter
      • Content Filter
      • Form
      • Hierarchy
      • Visibility Filter
    • Traversing
      • Filtering
      • Miscellaneous Traversing
      • Tree Traversal
    • Utilities