This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

getComputedStyle

Summary

Gets the values of all the CSS properties of an element after applying the active stylesheets and resolving the basic computations they may contain.

The returned object is of the same type that the object returned from the element’s “style” property, however the two objects have different purposes. The object returned from getComputedStyle is read-only and can be used to inspect the element’s style (including those set by a <style> element or an external stylesheet). The elt.style object should be used to set styles on a specific element.

Method of dom/Windowdom/Window

Syntax

var declaration = window.getComputedStyle(/* see parameter list */);

Parameters

element

Data-type
DOM Node

The element that contains the desired style settings.

pseudoElementName

Data-type
String

(Optional)

The name of a CSS pseudo-element or a null value (“::before” or “::after”). Optional in WebKit based browsers.

Return Value

Returns an object of type CSSStyleDeclarationCSSStyleDeclaration

A CSSStyleDeclaration object that contains the CSS settings applied to the desired object.

The settings in the returned object account for all applicable style rules and represent the resolved values for the various CSS properties applied to the specified object.

Examples

var elem1 = document.getElementById("elemId");
var style = window.getComputedStyle(elem1, null);

// this is equivalent:
// var style = document.defaultView.getComputedStyle(elem1, null);
<style><br/> #elem-container{<br/>   position: absolute;<br/>   left:     100px;<br/>   top:      200px;<br/>   height:   100px;<br/> }<br/></style><br/> <br/><div id="elem-container">dummy</div><br/><div id="output"></div>  <br/> <br/><script><br/>  function getTheStyle(){<br/>    var elem = document.getElementById("elem-container");<br/>    var theCSSprop = window.getComputedStyle(elem,null).getPropertyValue("height");<br/>    document.getElementById("output").innerHTML = theCSSprop;<br/>   }<br/>  getTheStyle();<br/></script>

getComputedStyle can pull style info off of pseudo-elements (for example, ::after, ::before, ::marker, ::line-marker).

<style><br/> h3:after {<br/>   content: ' rocks!';<br/> }<br/></style><br/> <br/><h3>generated content</h3> <br/> <br/><script><br/>  var h3       = document.querySelector('h3'), <br/>      result   = getComputedStyle(h3, ':after').content;<br/> <br/>  console.log('the generated content is: ', result); // returns ' rocks!'<br/></script>

Notes

The first argument must be an Element (passing a non-Element Node, like a #text Node, will throw an error).

The returned object actually represents the CSS 2.1 resolved values, not the computed values. While those values are usually equal, some older CSS properties like 'width’, ‘height’ or ‘padding’ will return their used value instead.

Originally, CSS 2.0 defined the computed values to be the “ready to be used” final values of properties after cascading and inheritance, but CSS 2.1 redefined computed values as pre-layout, and added the used values as post-layout. The differences between pre- and post-layout does include the resolution of percentages relative to the width or the height of an element (its layout).

While the computed style will return percentages values untouched in this case, the getComputedStyle function will sometimes, to preserve backwards compatibility, return the old meaning of computed values (now called used values) for a specific set of CSS 2.0 properties and resolve those percentages anyway.

The returned value can, in certain known cases, be expressly inaccurate by deliberate intent. In particular, to avoid the so called CSS History Leak security issue, browsers may expressly “lie” about the used value for a link and always return values as if a user has never visited the linked site. See http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/ and http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ for details of the examples of how this is implemented, most other modern browser have applied similar changes to the application of pseudo-selector styles and the values returned by getComputedStyle.

During a CSS transition, getComputedStyle returns the original property value in FireFox, but the final property value in WebKit.

When the pseudoElementName is set to a value other than null, the value is interpreted as a CSS pseudo-element with respect to the object specified in the element parameter.

Starting in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0), returned URL values now have quotes around the URL, like this: url("http://foo.com/bar.jpg").

Related specifications

DOM Level 2 Style
Recommendation
CSS Object Model (resolved style)
Draft

See also

Related articles

CSSOM

External resources

Microsoft Test Drive for getComputedStyle http://ie.microsoft.com/testdrive/HTML5/getComputedStyle/

Attributions