Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 402 lines (297 sloc) 18.022 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402
<!DOCTYPE html>
  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
  <title>PIE Documentation: Supported CSS3 Features</title>


<h1>Supported CSS3 Features</h1>

<!-- noformat on -->

<p>The following sections describe in detail the exact levels of support PIE has for certain CSS3 properties
and value types.</p>

    <li><a href="#border-radius">border-radius</a></li>
    <li><a href="#box-shadow">box-shadow</a></li>
    <li><a href="#border-image">border-image</a></li>
    <li><a href="#pie-background">CSS3 Backgrounds (-pie-background)</a></li>
    <li><a href="#gradients">Gradients</a></li>
    <li><a href="#rgba">RGBA Color Values</a></li>
    <li><a href="#custom">PIE Custom Properties</a>
            <li><a href="#pie-watch-ancestors">-pie-watch-ancestors</a></li>
            <li><a href="#pie-png-fix">PNG alpha transparency and -pie-png-fix</a></li>
            <li><a href="#pie-lazy-init">Lazy Initialization (-pie-lazy-init)</a></li>
            <li><a href="#pie-poll">Layout polling (-pie-poll)</a></li>

<h2 id="border-radius">border-radius</h2>

<p>PIE fully supports the border-radius property as defined in the CSS3
Backgrounds and Borders module specification.</p>

<pre class="long">border-radius: [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} [ / [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} ]?</pre>

<p>Only the shorthand version is supported; the longhand
border-top-left-radius etc. properties are not. The shorthand syntax does support different radii per corner, though:</p>

<p><code>border-radius: 5px 10px 15px 20px;</code> (top-left, top-right, bottom-right, bottom-left).</p>

<p>The rounded corners are applied to the element's background area
(including solid background colors, background images, and background
gradients), the element's border, and the box-shadow if specified.</p>

<p>Both the standard border-radius property name as well as a custom
prefixed -pie-border-radius property name are recognized; if both are
present then the prefixed value will take precedence. It is recommended
to only use the standard unprefixed property when possible (in
addition, of course, to -moz- and -webkit- prefixed properties as
necessary), since the CSS3 spec for this property seems fairly
solidified, and because there are no known incompatibilities between
PIE's implementation and the standard.</p>

<p>Notes on other browsers:</p>

<p>Elliptical radii (the optional set of values after the slash) are
only supported in Firefox versions 3.5 and up. As of the current
release (3.6), percentage values for vertical radii are incorrectly
calculated relative to the width of the box whereas the CSS3 spec says
they should be relative to the height. PIE handles this correctly.</p>

<p>WebKit deviates significantly from the CSS3 spec: the shorthand
property cannot be used to specify different radii per corner, so you
must use the separate longhand properties if you want to do that. It
also does not support percentage values at all. (TODO: check this in
WebKit nightlies and recent Chrome, I think these may now match the
spec and drop the prefix.)</p>

<h2 id="box-shadow">box-shadow</h2>

<p>PIE supports the <a href="">box-shadow property syntax</a>
as currently defined in the CSS3 Backgrounds &amp; Borders module.</p>

<pre class="long">box-shadow: none | &lt;shadow&gt; [,&lt;shadow&gt;]*
    where &lt;shadow&gt; = inset? &amp;&amp; [ &lt;offset-x&gt; &lt;offset-y&gt; &lt;blur-radius&gt;? &lt;spread-radius&gt;? &amp;&amp; &lt;color&gt;? ]</pre>

<p>Both the standard box-shadow property name as well as a custom
prefixed -pie-box-shadow property name are recognized; if both are
present the prefixed value will take precedence. It is recommended to
use the non-prefixed property when possible, since there are no known
incompatibilities between PIE's implementation and others which use the
non-prefixed property, such as Opera.</p>

<p>When used in conjunction with border-radius, the shape of the shadow
matches the shape of the rounded border box.</p>

<p>When using the blur radius parameter, the strength and size of the
blur as rendered by PIE should match that of other browsers almost
identically, however you may notice some slight differences due to
rounding, particularly when the blur is very small (this should not be
more than a one-pixel difference).</p>

<p>PIE does not currently support the 'inset' keyword, but support is
planned in a future version (see <a href="">issue #3</a>.</p>

<p>Notes on other browsers:</p>

<p>See the compatibility chart at the bottom of
<a href=""></a></p>

<h2 id="border-image">border-image</h2>

<p>PIE has preliminary support for the border-image property. This property allows
you to specify an image which gets divided into nine squares which are then drawn as
the corners, sides, and center of the target element. The sides and center will stretch
to match the size of the element.</p>

<p>There are currently several limitations of PIE's implementation, including:</p>
    <li>It only supports the 'stretch' scheme. I'd like to support the others in the future but performance
        is a big concern as it seems it will require creating a separate VML shape for each tile.</li>
    <li>It doesn't support the <a href="">outset parameter</a>
        described in the Backgrounds &amp; Borders module spec, though other browsers don't seem to support
        that yet either.</li>
    <li>It doesn't support the <a href="">width override
        parameter</a> to the border-image shorthand; it will only use the element's border-width for determining
        the slice widths (again, support for this in other browsers is spotty too).</li>
    <li>Related to #3, if the element's <code>border-style</code> is 'none' it will treat that as
    <li>It requires the 'fill' keyword to be present for the center area to be filled in. This is correct
        behavior according to the spec but other browsers don't require it and some even fail if 'fill' is
        present, so it's a bit tricky making it work consistently across browsers.</li>
    <li>It doesn't hide the element's normal border when border-image is specified. In conjunction with #4
        above, this means you have to set the border-style to 'solid' (or something other than 'none')
        <strong>and</strong> set the border-color to transparent.</li>
    <li>It seems there are on rare occasion rounding errors which cause 1px gaps between slices of the
        image. I've seen these gaps occur in other browsers too, though.</li>

<p>These issues will be addressed in a future release.</p>

<h2 id="pie-background">CSS3 Backgrounds (-pie-background)</h2>

<p>PIE supports CSS3 multiple background images, linear gradients as
background images, and some of the new CSS3 background aspects such as
background origin and clip. Unfortunately, to get access to these
post-CSS2 values, we have to put them in a property other than the
standard 'background' property, because IE will attempt to parse the
value internally and not allow us access to the original value string.
Therefore we use a custom -pie-background property for holding these

<p>Only the single -pie-background shorthand value is recognized; longhand values (e.g.
-pie-background-origin) are ignored.</p>

<p>For backward-compatibility with browsers which do not support CSS3
backgrounds, be sure to include appropriate fallbacks. For example:</p>

<pre class="long"><code>#myElement {
    background: url(bg-image.png) no-repeat #CCC; /*non-CSS3 browsers will use this*/
    background: url(bg-image.png) no-repeat, -moz-linear-gradient(#CCC, #EEE); /*gecko*/
    background: url(bg-image.png) no-repeat, -webkit-gradient(linear, 0 0, 0 100%, from(#CCC) to(#EEE)); /*webkit*/
    background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*future CSS3 browsers*/
    -pie-background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*PIE*/

<p>While the PIE parser will allow them, the following aspects of the
background shorthand will currently be ignored when rendering:</p>

  <li>background-attachment (will always use 'scroll' even if 'fixed'
or 'local' are specified)</li>
  <li>background-size (will always use the image's intrinsic size)</li>
  <li>background-repeat values of 'space' or 'round' (the other repeat
values are supported)</li>
  <li>background-origin (will always use 'padding-box')</li>
  <li>background-position values with more than 2 parts</li>

<p>Support for these items will be added in future versions as possible.</p>

<p>Note that PNG background images specified using <code>-pie-background</code> will be
rendered with correct alpha channel transparency in IE6. See the section below regarding
<a href="#pie-png-fix">PNG alpha transparency</a> for more information.</p>

<p>Notes on other browsers:</p>

<p>Firefox supports multiple backgrounds as of version 3.6. Safari supports them as of version 1.3.
See <a href=""></a></p>

<h2 id="gradients">Gradients</h2>

<p>PIE currently supports <code>linear-gradient</code> image values when used in the
-pie-background property. Uses in any contexts other than the background
are not supported. The supported syntax matches that of the current
<a href="">CSS3 Image Values module</a> draft.</p>

<pre class="long">linear-gradient([&lt;bg-position&gt; || &lt;angle&gt;,]? &lt;color-stop&gt;, &lt;color-stop&gt;[, &lt;color-stop&gt;]*);</pre>

<p>Currently all color stops are rendered fully opaque, even if
specifying an rgba color value. This is due to a limitation in VML's
linear gradient syntax which does not allow setting opacity for
individual color stops. (See <a href="">issue #7</a>)</p>

<p>Gradients containing color-stops which lie outside the bounding area
of the element are not currently supported, due to limitations in VML's
gradient rendering.</p>

<p>Radial gradients are not supported at this time; this feature is planned
for a future release (see <a href="">issue #2</a>)
but it may turn out to be impossible to implement due to VML's strange radial gradient behavior.</p>

<p>Notes on other browsers:</p>

<p>WebKit's gradient syntax is drastically different than that of the
CSS3 spec. See the
<a href="">Safari documentation</a> for their syntax</p>

<p>Mozilla only supports gradients (via the -moz-linear-gradient
function) as of Firefox 3.6.</p>

<p>Opera currently has no support for CSS gradients, though you can use SVG to generate gradients instead.</p>

<h2 id="rgba">RGBA Color Values</h2>

<p>PIE parses RGBA color values wherever they are allowed. However it
is only able to successfully render their opacity value in a few
contexts. In all other contexts they will be rendered with the correct
RGB color, but fully opaque. Here are the supported contexts in which
the opacity will be rendered correctly:</p>

  <li>The solid background-color as specified in the -pie-background property.</li>
  <li>The color value of box-shadow, if the shadow has no blur.</li>

<h2 id="custom">PIE custom properties</h2>

<h3 id="pie-watch-ancestors">-pie-watch-ancestors</h3>

<p>PIE automatically listens for any attribute or style property
changes on the element to which the behavior is applied. This means
that if you have scripting which modifies any of the recognized CSS3
properties on the fly, those changes will automatically be picked up
and the rendering will be updated to match. For example:</p>

<pre><code>/* JS: */
myElement.onclick = function() { = '20px';

/* CSS: */
#myElement {
    behavior: url(;
    border-radius: 10px;

<p>Assuming myElement has the behavior attached to it, the
above code will work as expected without any extra effort from the
author of the script or CSS. This seamlessness is a big part of why PIE
is so easy to use.</p>

<p>But common best-practices in scripting dictate that instead of
setting styles directly with, scripts should only
add/remove elements' class names, letting the actual styles
corresponding to those class names be maintained in the CSS. So
reworking the above example:</p>

<pre><code>/* JS: */
myElement.onclick = function() {
    this.className += ' poked';

/* CSS: */
#myElement {
    behavior: url(;
    border-radius: 10px;
#myElement.poked {
    border-radius: 20px;

<p>Again, since the className is being changed on the element to which
the behavior is applied, PIE will automatically be notified of the
change and update the border-radius rendering to match the new value.</p>

<p>However, what if the className is changed not on the element itself
but on one of its ancestors?</p>

<pre><code>/* JS: */
myElement.onclick = function() {
    this.parentNode.className += ' poked';

/* CSS: */
#myElement {
    behavior: url(;
    border-radius: 10px;
.poked #myElement {
    border-radius: 20px;

<p>This is a very common pattern which allows a lot of flexibility.
However, in this case, PIE will not be automatically notified of the
className change. To be notified, it will also have to add a listener
to the ancestor element. We could brute-force this by automatically
adding propertychange listeners to all the ancestors of every
PIE-targeted element, but that would be bad for performance and memory
usage. So instead, we have introduced a custom CSS property which
allows authors to tell PIE that certain ancestors should be watched:</p>

<pre><code>/* JS: */
myElement.onclick = function() {
    this.parentNode.className += ' poked';

/* CSS: */
#myElement {
    behavior: url(;
    border-radius: 10px;
    <strong>-pie-watch-ancestors: 1;</strong>
.poked #myElement {
    border-radius: 20px;

<p>This tells PIE that it should watch for changes on ancestors one
level up from the element. It will attach the propertychange listener
to the element's parent and therefore be notified when the parent's
className gets changed, and update the rendering correctly.

<h3 id="pie-png-fix">PNG alpha transparency and -pie-png-fix</h3>

<p>A nice side-effect of PIE's use of VML for rendering is that it causes PNG images
with alpha channel transparency to be correctly displayed in IE6 when they are rendered
by PIE's engine. This includes:</p>
    <li>Background images specified using the <a href="#pie-background">-pie-background</a> property</li>
    <li>Background images specified using the standard <code>background-image</code> style, when used
        in conjunction with other CSS3 properties that trigger re-rendering of the background
        (border-radius, border-image)</li>
    <li>&lt;img> elements that have border-radius applied</li>

<p>Sometimes you might want the benefit of the fixed PNG transparency, on elements that do not meet
the criteria above. In that case, you can add the custom property <code>-pie-png-fix: true;</code> to
force re-rendering of the background-image or &lt;img>. (The behavior must also be
attached to the element.)</p>

<h3 id="pie-lazy-init">Lazy Initialization (-pie-lazy-init)</h3>

<p>While PIE has been optimized for speed, there is still a small cost in rendering performance for each element
it is applied to. When you have dozens or hundreds of elements on your page with CSS3 styles applied, this
can add up to a noticeable rendering delay.</p>

<p>When you have that many elements on one page, chances are that only a small number of them are visible
in the browser viewport initially, as viewing the rest would require scrolling. PIE allows an optional
optimization for this case: if you apply the custom <code>-pie-lazy-init:true;</code> property to elements
PIE will delay the initialization of their CSS3 rendering until they are scrolled into the viewport. This
keeps the initial page load snappy without severely limiting the number of elements you can render.</p>

<h3 id="pie-poll">Layout Polling (-pie-poll)</h3>

<p>In general PIE is quite good at detecting changes to the size and position of the elements to which it
is attached and automatically adjusting its rendering to match. It does this by listening to the IE-specific
<code>onmove</code> and <code>onresize</code> events for each target element. In the majority of cases this
works seamlessly; in rare cases, however, IE does not fire these events when it should, and PIE gets out of sync.</p>

<p>To help users get around these cases, PIE has a second method for tracking size and position changes: polling.
When polling is enabled for an element, PIE will manually query that element's layout several times a second, and
if the layout has changed then it will adjust the rendering.</p>

<p>Polling is enabled by default for all elements in IE8 (as that version is particularly bad about not firing
the events) and disabled in IE 6 and 7. Users can override these defaults
to force polling on or off for individual elements by setting a custom CSS property: just specify
<code>-pie-poll:true;</code> to force polling on for an element, or <code>-pie-poll:false;</code> to disable it.</p>

<!-- noformat off -->

Something went wrong with that request. Please try again.