Big CSS reference

Hopefully, this page will expand to include descriptions of all CSS properties we support.

Background properties

• The following background properties are supported: background-color, background-image, background-repeat, background-attachment, background-position, background-size and the shorthand background property.
• Not supported are background-origin and background-clip.
• As of version 1.0.7, background-attachment will only support the scroll value.
• Also as of version 1.0.7, all background properties except background-color and the shorthand background accept a comma separated list.
• The background shorthand property also does not accept a background size. Therefore, it is recommended to use the primitive properties rather than the shorthand background property.
• Background properties can be used in @page at-rules.
• The linear-gradient(...) function can be used as an image (support of the standard is pretty complete). There is no support for other gradients.

Issues

• Background images are currently not cached between elements so will be fetched and embedded multiple times if required.
• When using repeating background images, a PDF instruction is included for each image iteration, so be careful not to use too small images.

Syntax description

Property	Syntax
background-color	Hex or rgb(...) or cmyk(...) color or transparent
background-image	One or more url(...) or linear-gradient(...) values separated by commas or none
background-repeat	One or more of repeat, repeat-x, repeat-y or no-repeat separated by commas
background-attachment	One or more of scroll. fixed is removed and not supported as of version 1.0.7.
background-position	One or more of the two value syntax where first is x and second is y. Valid values for x include left, center, right and auto. For y they include top, center, bottom and auto. A percentage or length (px, cm, etc) can also be used for x and y. If only one value is supplied the other (y unless the first is top or bottom) is assumed to be center. Negative values are not allowed and the four value relative syntax is not supported.
background-size	One or more two value syntax where first is width and second is height. Alternatively cover, contain or auto keywords. Both width and height may be specified as percentage , length or auto (which preserves aspect ratio). If only one value is specified, the other is auto.
background	Color followed by image, repeat, attachment and position. If a value is left out it is reset to the initial default for that property.

Examples

div {
  /* Mutiple images are supported as of version 1.0.7. */
  background-image: url(images/cat.png), url(images/flyingsaucer.png);
  background-repeat: no-repeat;
  background-position: left, right;
  background-attachment: scroll;
  background-size: cover, 25% 70%;
}
div.lg {
  background-image: linear-gradient(to top, red, green, blue);
}

Developer notes

Background properties are validated and cleaned up in these classes:

• com.openhtmltopdf.css.parser.property.PrimitiveBackgroundPropertyBuilders in core
• com.openhtmltopdf.css.parser.property.BackgroundPropertyBuilder in core

CSS property values after validation are fetched through com.openhtmltopdf.css.style.CalculatedStyle.getBackgroundImages() in core. Use your IDE's references function to follow usage. This section on background properties is referenced in the code at com.openhtmltopdf.util.WebDocLocations.CSS_BACKGROUND_PROPERTIES in core.