entries/css.xml

<?xml version="1.0"?>
<entries>
  <desc>Get the value of a style property for the first element in the set of matched elements or set one or more CSS properties for every matched element.</desc>
  <entry type="method" name="css" return="String">
    <title>.css()</title>
    <signature>
      <added>1.0</added>
      <argument name="propertyName" type="String">
        <desc>A CSS property.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.9</added>
      <argument name="propertyNames" type="Array">
        <desc>An array of one or more CSS properties.</desc>
      </argument>
    </signature>
    <desc>Get the computed style properties for the first element in the set of matched elements.</desc>
    <longdesc>
      <p>The <code>.css()</code> 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 <code>getComputedStyle()</code> method in standards-based browsers versus the <code>currentStyle</code> and <code>runtimeStyle</code> properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the <code>float</code> property as <code>styleFloat</code>, while W3C standards-compliant browsers refer to it as <code>cssFloat</code>. For consistency, you can simply use <code>"float"</code>, and jQuery will translate it to the correct value for each browser.</p>
      <p>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 <code>.css( "background-color" )</code> and <code>.css( "backgroundColor" )</code>.</p>
	  <p>Note that the <em>computed style</em> of an element may not be the same as the value specified for that element in a style sheet. For example, computed styles of dimensions are almost always pixels, but they can be specified as em, ex, px or % in a style sheet. Different browsers may return CSS color values that are logically but not textually equal, e.g., #FFF, #ffffff, and rgb(255,255,255).</p>
      <p>Retrieval of shorthand CSS properties (e.g., <code>margin</code>, <code>background</code>, <code>border</code>), although functional with some browsers, is not guaranteed. For example, if you want to retrieve the rendered <code>border-width</code>, use: <code>$( elem ).css( "borderTopWidth" )</code>, <code>$( elem ).css( "borderBottomWidth" )</code>, and so on.</p>
      <p><strong>As of jQuery 1.9</strong>, passing an array of style properties to <code>.css()</code> will result in an object of property-value pairs. For example, to retrieve all four rendered <code>border-width</code> values, you could use <code>$( elem ).css([ "borderTopWidth", "borderRightWidth", "borderBottomWidth", "borderLeftWidth" ])</code>. </p>
    </longdesc>
    <example>
      <desc>Get the background color of a clicked div.</desc>
      <code><![CDATA[
$( "div" ).click(function() {
  var color = $( this ).css( "background-color" );
  $( "#result" ).html( "That div is <span style='color:" +
    color + ";'>" + color + "</span>." );
});
]]></code>
      <css><![CDATA[
  div {
    width: 60px;
    height: 60px;
    margin: 5px;
    float: left;
  }
]]></css>
      <html><![CDATA[
<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>
]]></html>
    </example>

    <example>
      <desc>Get the width, height, text color, and background color of a clicked div.</desc>
      <code><![CDATA[
$( "div" ).click(function() {
  var html = [ "The clicked div has the following styles:" ];

  var styleProps = $( this ).css([
    "width", "height", "color", "background-color"
  ]);
  $.each( styleProps, function( prop, value ) {
    html.push( prop + ": " + value );
  });

  $( "#result" ).html( html.join( "<br>" ) );
});
]]></code>
      <css><![CDATA[
  div {
    height: 50px;
    margin: 5px;
    padding: 5px;
    float: left;
  }
  #box1 {
    width: 50px;
    color: yellow;
    background-color: blue;
  }
  #box2 {
    width: 80px;
    color: rgb(255, 255, 255);
    background-color: rgb(15, 99, 30);
  }
  #box3 {
    width: 40px;
    color: #fcc;
    background-color: #123456;
  }
  #box4 {
    width: 70px;
    background-color: #f11;
  }
]]></css>
      <html><![CDATA[
<p id="result">&nbsp;</p>
<div id="box1">1</div>
<div id="box2">2</div>
<div id="box3">3</div>
<div id="box4">4</div>
]]></html>
    </example>
    <category slug="css"/>
    <category slug="manipulation/style-properties"/>
    <category slug="version/1.0"/>
    <category slug="version/1.4"/>
    <category slug="version/1.9"/>
  </entry>
  <entry type="method" name="css" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="propertyName" type="String">
        <desc>A CSS property name.</desc>
      </argument>
      <argument name="value">
        <desc>A value to set for the property.</desc>
        <type name="String"/>
        <type name="Number"/>
      </argument>
    </signature>
    <signature>
      <added>1.4</added>
      <argument name="propertyName" type="String">
        <desc>A CSS property name.</desc>
      </argument>
      <argument name="function" type="Function">
        <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old value as arguments.</desc>
        <argument name="index" type="Integer" />
        <argument name="value" type="String" />
        <return>  
          <type name="String"/>
          <type name="Number"/>
        </return>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="properties" type="PlainObject">
        <desc>An object of property-value pairs to set.</desc>
      </argument>
    </signature>
    <desc>Set one or more CSS properties for the set of matched elements.</desc>
    <longdesc>
      <p>As with the <code>.prop()</code> method, the <code>.css()</code> 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 object of key-value pairs.</p>
      <p>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 <code>.css({ "background-color": "#ffe", "border-left": "5px solid #ccc" })</code> and <code>.css({backgroundColor: "#ffe", borderLeft: "5px solid #ccc" })</code>. 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.</p>
      <p>When using <code>.css()</code> as a setter, jQuery modifies the element's <code>style</code> property. For example,  <code>$( "#mydiv" ).css( "color", "green" )</code> is equivalent to <code>document.getElementById( "mydiv" ).style.color = "green"</code>. Setting the value of a style property to an empty string &#x2014; e.g. <code>$( "#mydiv" ).css( "color", "" )</code> &#x2014; removes that property from an element if it has already been directly applied, whether in the HTML style attribute, through jQuery's <code>.css()</code> method, or through direct DOM manipulation of the <code>style</code> property. It does not, however, remove a style that has been applied with a CSS rule in a stylesheet or <code>&lt;style&gt;</code> element. <strong>Warning:</strong> one notable exception is that, for IE 8 and below, removing a shorthand property such as <code>border</code> or <code>background</code> will remove that style entirely from the element, regardless of what is set in a stylesheet or <code>&lt;style&gt;</code> element.</p>
      <p>As of jQuery 1.6, <code>.css()</code> accepts relative values similar to <code>.animate()</code>. Relative values are a string starting with <code>+=</code> or <code>-=</code> to increment or decrement the current value. For example, if an element's padding-left was 10px, <code>.css( "padding-left", "+=15" )</code> would result in a total padding-left of 25px.</p>
      <p>As of jQuery 1.4, <code>.css()</code> allows us to pass a function as the property value:</p>
      <pre><code>
$( "div.example" ).css( "width", function( index ) {
  return index * 50;
});
      </code></pre>
      <p>This example sets the widths of the matched elements to incrementally larger values.</p>
      <p><strong>Note: </strong>If nothing is returned in the setter function (ie. <code>function( index, style ){} )</code>, or if <code>undefined</code> is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.</p>
    </longdesc>
    <example>
      <desc>Change the color of any paragraph to red on mouseover event.</desc>
      <code><![CDATA[
$( "p" ).on( "mouseover", function() {
  $( this ).css( "color", "red" );
});
]]></code>
      <css><![CDATA[
  p {
    color: blue;
    width: 200px;
    font-size: 14px;
  }
]]></css>
      <html><![CDATA[
  <p>Just roll the mouse over me.</p>

  <p>Or me to see a color change.</p>
]]></html>
    </example>
    <example>
      <desc>Increase the width of #box by 200 pixels the first time it is clicked.</desc>
      <code><![CDATA[
$( "#box" ).one( "click", function() {
  $( this ).css( "width", "+=200" );
});
]]></code>
      <css><![CDATA[
  #box {
    background: black;
    color: snow;
    width: 100px;
    padding: 10px;
  }
]]></css>
      <html><![CDATA[
<div id="box">Click me to grow</div>
]]></html>
    </example>
    <example>
      <desc>Highlight a clicked word in the paragraph.</desc>
      <code><![CDATA[
var words = $( "p" ).first().text().split( /\s+/ );
var text = words.join( "</span> <span>" );
$( "p" ).first().html( "<span>" + text + "</span>" );
$( "span" ).on( "click", function() {
  $( this ).css( "background-color", "yellow" );
});
]]></code>
      <css><![CDATA[
  p {
    color: blue;
    font-weight: bold;
    cursor: pointer;
  }
]]></css>
      <html><![CDATA[
<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>
]]></html>
    </example>
    <example>
      <desc>Change the font weight and background color on mouseenter and mouseleave.</desc>
      <code><![CDATA[
$( "p" )
  .on( "mouseenter", function() {
    $( this ).css({
      "background-color": "yellow",
      "font-weight": "bolder"
    });
  })
  .on( "mouseleave", function() {
    var styles = {
      backgroundColor : "#ddd",
      fontWeight: ""
    };
    $( this ).css( styles );
  });
]]></code>
      <css><![CDATA[
  p {
    color: green;
  }
]]></css>
      <html><![CDATA[
<p>Move the mouse over a paragraph.</p>
<p>Like this one or the one above.</p>
]]></html>
    </example>
    <example>
      <desc>Increase the size of a div when you click it.</desc>
      <code><![CDATA[
$( "div" ).on( "click", function() {
  $( this ).css({
    width: function( index, value ) {
      return parseFloat( value ) * 1.2;
    },
    height: function( index, value ) {
      return parseFloat( value ) * 1.2;
    }
  });
});
]]></code>
      <css><![CDATA[
  div {
    width: 20px;
    height: 15px;
    background-color: #f33;
  }
]]></css>
      <html><![CDATA[
<div>click</div>
<div>click</div>
]]></html>
    </example>
    <category slug="css"/>
    <category slug="manipulation/style-properties"/>
    <category slug="version/1.0"/>
    <category slug="version/1.4"/>
  </entry>
</entries>