In order to access this site you need to enable JavaScript!

You are here: Reference > JavaScript > client-side > style handling > objects > CSSValueList

CSSValueList collection

Browser support:

Represents the value of a complex style property and its type.

The CSSValue object is the base interface for all available style values.

There are two objects in JavaScript that inherit from the CSSValue object:

One is the CSSPrimitiveValue object for simple style values (color, width, height, ...).
the other is the CSSValueList object for complex style values (backgroundPosition, borderSpacing, cursor, ...).

The getPropertyCSSValue method returns a CSSPrimitiveValue or CSSValueList object, depending on the type of the style property's value. In case of some special style properties, the getPropertyCSSValue method returns custom objects. The custom objects are also inherited from the CSSValue object.

The cssValueType property of the returned object helps to identify its type.
Note: all possible returned objects support the cssValueType property, because it is inherited from the CSSValue object.

The CSSValueList collection represents the complex value as a list of CSSValue objects. See the examples below for details.

Syntax:

Methods that return the object:

•	object.getPropertyCSSValue (propertyName)
	Related objects: CSSStyleDeclaration, style

The base interface, through which you can add new functionalities to the CSSValueList collection, is the CSSValueList interface.

Inherits from:

CSSValue

Possible members:

Properties:

cssText

Sets or retrieves the contents of a style declaration as a string.

cssValueType

Returns the type of the style value that belongs to the current object.

length

Returns an integer that specifies the number of objects in the current collection.

This property is read-only.

Methods:

[index]

Returns a CSSValue object from the current collection by index.

Parameters:

index

Required. Zero-based integer that specifies the position of the object to retrieve.

Return value:

Returns a CSSValue object.

item (index)

Returns a CSSValue object from the current collection by index.

Parameters:

index

Required. Zero-based integer that specifies the position of the object to retrieve.

Return value:

Returns a CSSValue object.

Example HTML code 1:

This example illustrates the use of the CSSValueList collection:

<head>
    <style>
        .example {
            background-image: url("bg.jpg");
            background-repeat: no-repeat;
            width: 200px;
            height: 100px;
            border:1px solid #CCCCCC;
            
            background-position: center top;
        }
    </style>
    <script type="text/javascript">
        function GetBGPosition () {
            var div = document.getElementById ("myDiv");
            if (window.getComputedStyle) {
                var compStyle = window.getComputedStyle (div, null);
                try {
                    var valueList = compStyle.getPropertyCSSValue ("background-position");
                    if (valueList.cssValueType == CSSValue.CSS_VALUE_LIST) {
                        var valueHoriz = valueList[0].getFloatValue (2);
                        var valueVert = valueList[1].getFloatValue (2);

                        alert ("The position of the background: " + valueHoriz + "%, " + valueVert + "%.");
                    }
                    else {
                        alert ("The type of the value is not CSSValueList!");
                    }
                }
                catch (e) {
                    alert ("Your browser does not support the getPropertyCSSValue method!");
                }
            }
            else {
                alert ("Your browser does not support the getComputedStyle method!");
            }
        }
    </script>
</head>
<body>
    <div class="example" id="myDiv">
        Use the button below to get the value of the background-position style property
    </div>
    <br />
    <button onclick="GetBGPosition ();">Get background-position</button>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 2:

This example shows how to list all style properties for a HTML element.

<head>
    <style>
        #testDiv {
            border:1px solid #FF0000;
            background-position: 10% 20px;
            clip: rect(10px, 40px, 150px, 5px);
        }
    </style>
    <script type="text/javascript">
        function GetPrimitiveValue (value) {
            var valueType = value.primitiveType;

            if (valueType == CSSPrimitiveValue.CSS_NUMBER) {
                return value.getFloatValue (CSSPrimitiveValue.CSS_NUMBER);
            }
            if (valueType == CSSPrimitiveValue.CSS_PERCENTAGE) {
                return value.getFloatValue (CSSPrimitiveValue.CSS_PERCENTAGE) + "%";
            }
            if (CSSPrimitiveValue.CSS_EMS <= valueType && valueType <= CSSPrimitiveValue.CSS_DIMENSION) {
                return value.getFloatValue (CSSPrimitiveValue.CSS_PX) + "px";
            }
            if (CSSPrimitiveValue.CSS_STRING <= valueType && valueType <= CSSPrimitiveValue.CSS_ATTR) {
                return value.getStringValue ();
            }
            if (valueType == CSSPrimitiveValue.CSS_COUNTER) {
                var counterValue = value.getCounterValue ();
                return "(identifier: " + counterValue.identifier + 
                       ", listStyle: " + counterValue.listStyle + 
                       ", separator: " + counterValue.separator + ")";
            }
            if (valueType == CSSPrimitiveValue.CSS_RECT) {
                var rect = value.getRectValue ();
                var topPX = rect.top.getFloatValue (CSSPrimitiveValue.CSS_PX);
                var rightPX = rect.right.getFloatValue (CSSPrimitiveValue.CSS_PX);
                var bottomPX = rect.bottom.getFloatValue (CSSPrimitiveValue.CSS_PX);
                var leftPX = rect.left.getFloatValue (CSSPrimitiveValue.CSS_PX);
                return "RECT(" + topPX + "px, " + rightPX + "px, " + bottomPX + "px, " + leftPX + "px)";
            }
            if (valueType == CSSPrimitiveValue.CSS_RGBCOLOR) {
                var rgb = value.getRGBColorValue ();
                var r = rgb.red.getFloatValue (CSSPrimitiveValue.CSS_NUMBER);
                var g = rgb.green.getFloatValue (CSSPrimitiveValue.CSS_NUMBER);
                var b = rgb.blue.getFloatValue (CSSPrimitiveValue.CSS_NUMBER);
                return "RGB(" + r + "," + g + "," + b + ")";
            }
            
            return value.cssText;
        }

        function GetComplexValue (value) {
            var valueStr = "";
            for (var i = 0; i < value.length; i++) {
                switch (value[i].cssValueType) {
                case CSSValue.CSS_INHERIT:
                    valueStr += value[i].toString ();
                    break;
                case CSSValue.CSS_PRIMITIVE_VALUE:
                    valueStr += GetPrimitiveValue (value[i]);
                    break;
                case CSSValue.CSS_VALUE_LIST:
                    valueStr += GetComplexValue (value[i]);
                    break;
                case CSSValue.CSS_CUSTOM:
                    valueStr += value[i].toString ();
                    break;
                }

                valueStr += "<br/>";
            }

            return valueStr;
        }

        function GetCssProperties () {
            var resTable = document.getElementById ("resTable");            
            var div = document.getElementById ("testDiv");

            if (window.getComputedStyle) {
                var compStyle = window.getComputedStyle (div, null);
                try {
                    for (var i = 0; i < compStyle.length; i++) {
                        var propName = compStyle.item(i);

                        resTable.insertRow (i);
                        resTable.rows[i].insertCell (0);
                        resTable.rows[i].insertCell (1);
                        resTable.rows[i].insertCell (2);

                        resTable.rows[i].cells[0].innerHTML = propName;

                        var message = propName + ": ";
                        var value = compStyle.getPropertyCSSValue (propName);

                        if (value) {
                            switch (value.cssValueType) {
                            case CSSValue.CSS_INHERIT:
                                resTable.rows[i].cells[1].innerHTML = "The value is inherited from the parent";
                                resTable.rows[i].cells[2].innerHTML = value.toString ();
                                break;
                            case CSSValue.CSS_PRIMITIVE_VALUE:
                                resTable.rows[i].cells[1].innerHTML = "The value is a primitive value";
                                resTable.rows[i].cells[2].innerHTML = GetPrimitiveValue (value);
                                break;
                            case CSSValue.CSS_VALUE_LIST:
                                resTable.rows[i].cells[1].innerHTML = "The value is a complex value";
                                resTable.rows[i].cells[2].innerHTML = GetComplexValue (value);
                                break;
                            case CSSValue.CSS_CUSTOM:
                                resTable.rows[i].cells[1].innerHTML = "The value is a custom value";
                                resTable.rows[i].cells[2].innerHTML = value.toString ();
                                break;
                            }
                        }
                        else {
                            resTable.rows[i].cells[1].innerHTML = "null";
                            resTable.rows[i].cells[2].innerHTML = "null";
                        }
                    }
                } 
                catch (e) {
                    alert ("Your browser does not support getPropertyCSSValue method!");
                }
            }
            else {
                alert ("Your browser does not support getComputedStyle method!");
            }
        }
    </script>
</head>
<body onload="GetCssProperties ()">
    <div id="testDiv">division element with custom style</div>
    <br/>
    <h3>Style properties of the div above:</h3>
    <table border="1px" cellspacing="5px">
        <thead style="font-weight: bold;">
            <tr>
                <td>Property</td>
                <td>Type</td>
                <td>Value</td>
            </tr>
        </thead>
        <tbody id="resTable">
        </tbody>
    </table>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

External links:

CSSValueList (W3C)

Digg Del.icio.us Reddit Facebook Twitter Diigo

User Contributed Comments

CSSValueList collection

Syntax:

Inherits from:

Possible members:

Parameters:

Return value:

Parameters:

Return value:

Example HTML code 1:

Example HTML code 2:

External links:

Post Content