Style properties
These methods get and set CSS-related properties of elements.
.css() (getter)
Note
Get the value of a style property for the first element in the set of matched elements.
.css(propertyName)
Parameters
propertyName: A CSS property
Return value
A string containing the CSS property value.
Description
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 left string for each of the following three lines:
$('div.left').css('float');$('div.left').css('cssFloat');$('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').
.css() (setter)
Note
Set one or more CSS properties for the set of matched elements.
.css(propertyName, value) .css(map) .css(propertyName, function)
Parameters (first version)
propertyName: A CSS property namevalue: A value to set for the property
Parameters (second version)
map: A map of property-value pairs to set
Parameters (third version)
propertyName: A CSS property namefunction: A function returning the value to set
Return value
The jQuery object, for chaining purposes.
Description
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. However, 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 as follows:
$('div.example').css('width', function(index) {
return index * 50;
});
This example sets the widths of the matched elements to incrementally larger values.
.height() (getter)
Note
Get the current computed height for the first element in the set of matched elements.
.height()
Parameters
None
Return value
The height of the element in pixels
Description
The difference between .css('height') and .height() is that the latter returns a unitless 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.
.height() (setter)
Note
Set the CSS height of each element in the set of matched elements.
.height(value)
Parameters
value: An integer representing the number of pixels, or an integer with an optional unit of measure appended
Return value
The jQuery object, for chaining purposes.
Description
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. However, if a string is provided, 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.
.innerHeight()
Note
Get the current computed height for the first element in the set of matched elements, including padding but not border.
.innerHeight()
Parameters
None
Return value
The height of the element in pixels, including top and bottom padding.
Description
This method is not applicable to window and document objects; for these use .height() instead.
.outerHeight()
Note
Get the current computed height for the first element in the set of matched elements, including padding and border.
.outerHeight([includeMargin])
Parameters
includeMargin: A Boolean indicating whether to include the element's margin in the calculation
Return value
The height of the element, along with its top and bottom padding, border, and optionally margin, in pixels.
Description
If includeMargin is omitted or false, the padding and border are included in the calculation; if it's true, the margin is also included.
This method is not applicable to window and document objects, for these use .height() instead.
.width() (getter)
Note
Get the current computed width for the first element in the set of matched elements.
.width()
Parameters
None
Return value
The width of the element in pixels.
Description
The difference between .css(width) and .width() is that the latter returns a unitless 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.
.width() (setter)
Note
Set the CSS width of each element in the set of matched elements.
.width(value)
Parameters
value: An integer representing the number of pixels, or an integer along with an optional unit of measure appended
Return value
The jQuery object, for chaining purposes.
Description
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. However, if a string is provided, 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.
.innerWidth()
Note
Get the current computed width for the first element in the set of matched elements, including padding but not border.
.innerWidth()
Parameters
None
Return value
The width of the element, including left and right padding, in pixels.
Description
This method is not applicable to window and document objects, for these use .width() instead.
.outerWidth()
Note
Get the current computed width for the first element in the set of matched elements, including padding and border.
.outerWidth([includeMargin])
Parameters
includeMargin: A Boolean indicating whether to include the element's margin in the calculation
Return value
The width of the element, along with left and right padding, border, and optionally margin, in pixels.
Description
If includeMargin is omitted or false, the padding and border are included in the calculation; if it's true, the margin is also included.
This method is not applicable to window and document objects; for these use .width() instead.
.offset() (getter)
Note
Get the current coordinates of the first element in the set of matched elements relative to the document.
.offset()
Parameters
None
Return value
An object containing the properties top and left.
Description
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 more useful.
.offset() (setter)
Note
Set the current coordinates of the first element in the set of matched elements relative to the document.
.offset(coordinates)
Parameters
coordinates: An object containing thetopandleftproperties, which are integers indicating the new top and left coordinates for the element
Return value
The jQuery object, for chaining purposes.
Description
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.
.position()
Note
Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.
.position()
Parameters
None
Return value
An object containing the properties top and left.
Description
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 within the same DOM element, .position() is more useful.
.scrollTop() (getter)
Note
Get the current vertical position of the scroll bar for the first element in the set of matched elements.
.scrollTop()
Parameters
None
Return value
The vertical scroll position in pixels.
Description
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.
.scrollTop() (setter)
Note
Set the current vertical position of the scroll bar for each of the sets of matched elements.
.scrollTop(value)
Parameters
value: An integer indicating the new position to set the scroll bar to
Return value
The jQuery object, for chaining purposes.
.scrollLeft() (getter)
Note
Get the current horizontal position of the scroll bar for the first element in the set of matched elements.
.scrollLeft()
Parameters
None
Return value
The horizontal scroll position in pixels.
Description
The horizontal scroll position is the same as the number of pixels that are hidden from view to the left of the scrollable area. If the scroll bar is at the very left, or if the element is not scrollable, this number will be 0.
.scrollLeft() (setter)
Note
Set the current horizontal position of the scroll bar for each of the set of matched elements.
.scrollLeft(value)
Parameters
value: An integer indicating the new position to set the scroll bar to
Return value
The jQuery object, for chaining purposes