.prop()S2C Home « Attributes & Properties « .prop()

First element property retrieval and matched set property setting.

Description

The .prop() method is used to retrieve a property value from the first element within the matched set, or set one or more property values within the matched set.

  • Returns undefined for property values that haven't been set.
  • Use the .attr() method to retrieve or set DOM attributes.
  • When changing the dynamic state of a DOM element, the .prop() method should be used to set disabled and checked.
  • When changing the dynamic state of a DOM element, the .val() method should be used for getting and setting value.
  • In IE6-8, when using the .prop() method to set a DOM element property to anything other than a simple primitive value (boolean, number or string), the method can cause memory leaks. This happens if the property is not removed using the .removeProp() method before the DOM element is removed from the document. To safely set values on DOM elements without memory leaks, use the .data() method.

Syntax

Signature Description
.prop( propertyName ) Retrieve a property value from the first element within the matched set.
.prop( propertyName, value ) Set a single property value within the matched set.
.prop( map )Use a map of attribute-value pairs to set multiple property values within the matched set.
.prop( propertyName, function(index, prop) )A function returning the property value to set.

Parameters

Parameter Description Type
propertyNameThe property name.String
valueA value to set the property to.String or
Number
propertiesA plain JavaScript object of key-value pairs to set.PlainObject
function(index, prop)A function.
  • Each time the callback runs, it is passed the current index position of the element in the set.
  • The existing properties pertaining to the current element are also passed.
  • The callback is fired in the context of the current element in the set, so the keyword this refers to that element.
Function

Return

Retrieving - A String object.

Setting - A jQuery object including the updated properties within the matched set.

.prop( propertyName ) ExampleTop

Retrieve a property value from the first element within the matched set.

  • Use a looping construct such as .each() or .map() to get element properties for all elements within the matched set.

In the example below we get the value of the class attribute of the 'col' element for the table that has an id of 'table1'.

Table For Testing The .prop( propertyName ) Signature
Table Row 1, Table Data 1 Table Row 1, Table Data 2
Table Row 2, Table Data 1 Table Row 2, Table Data 2


$(function(){
  $('#btn26').on('click', function() {
    alert('The first column in the table above has a class of: ' 
           + $('#table1 col').prop('class') + '.'); 
  });
});

Press the button below to action the above code:


.prop( propertyName, value ) ExampleTop

Set a single attribute value within the matched set.

In the example below when we press the button we disable input of type 'checkbox'.

Pie Survey

Which pies do you like?:



$(function(){
  $('#btn27').on('click', function() {
    $("#form1 input[type='checkbox']").prop({
       disabled: true
    });
  });
});

Press the button below to action the above code:


.prop( properties ) ExampleTop

A plain JavaScript object of key-value pairs to set multiple property values within the matched set.

We can set multiple property values using a 'map' of property-value pairs which we pass to the method in object literal format, commonly known as JSON. Take a look at: JavaScript Intermediate - Lesson 7: Object Literals for more information on object literals and JSON.

In the example below when we press the button we disable input of type 'checkbox' and check each box.

Pie Survey

Which pies do you like?:



$(function(){
  $('#btn28').on('click', function() {
    $("#form2 input[type='checkbox']").prop({
       disabled: true,
       checked: true
    });
  });
});

Press the button below to action the above code:


.prop( propertyName, function(index, prop) ) ExampleTop

A function returning the property value to set.

In the example below when we press the button we switch checked boxes to unswitched and vice versa.

Pie Survey

Which pies do you like?:



$(function(){
  $('#btn29').on('click', function() {
    $("#form3 input[type='checkbox']").prop('checked', function(index, prop) {
      if (prop == true) {
          return false;
      } else {
          return true;
      }
    });
  });
});

Press the button below to action the above code: