Scrivito.BackgroundImageTag

Renders a CMS content image as a CSS background.

This renders a tag with a CSS backgroundImage style, referencing a CMS image object. The download size and the clipping region of the image are automatically optimized for the current viewport.

Scrivito.BackgroundImageTag supports layered CSS backgrounds. Layered backgrounds can be a mix of CMS images and CSS functions.

Props

  • tag (String) – optional tag name of the DOM element. Default: div
  • style (Object) – optional JavaScript object with camel-cased properties, similar to the style prop of a React component used for specifying string values for CSS properties. However, the background property receives special treatment and must contain a background description instead of a simple string. For style properties other than background, the rules for the React style prop apply.

Other props are rendered as attributes of the resulting tag.

The background description

In order to render the background image, the style prop must include the background key containing the background description. A background description is either a JavaScript object with a set of specific keys (see below) or, for layered backgrounds, an array of such objects. The most important key is image, which must be either a string specifying a CSS function, or a CMS image. Depending on whether the image is a CSS function or a CMS image, different values for the background key are allowed.

Background from a CMS image

In order to set a background using a CMS image, the image must be either an Obj or a Binary. Such a background accepts the keys attachment, position and size. The values for these keys are restricted to:

  • attachment: scroll (default) or fixed
  • position: center (default), left, right, top, bottom
  • position: center (default) or any valid CSS position value [New in 1.41.0]
  • size: cover (default) or contain

In the following example, a “jumbotron” section with a background image is rendered, which can be specified via a widget attribute named backgroundImage:

If any of the above keys is missing, BackgroundImageTag will render a reasonable default for it. If used with unexpected keys or unexpected values, BackgroundImageTag will throw an error.

Note that you can style the element using CSS. However, automatic image optimization only takes account of the style prop. We recommend specifying all background image rules through the style prop.

Background with a CSS function

In order to describe a background with a CSS function, the image key must have a string value, e.g. url() or radial-gradient(). Such a background accepts the following optional keys (with arbitrary strings as their values): attachment, clip, color, origin, position, repeat, size.

Here is an example of rendering a CMS background image with a gradient on top:

For the list of all possible values, please see the documentation of the background CSS property. If a key is missing, BackgroundImageTag renders a reasonable default. If used with unexpected keys or unexpected values, BackgroundImageTag will throw an error.

Note that background images set by a CSS function are not viewport-optimized by Scrivito.

Multiple backgrounds

If background is an array, each item describes a background layer. The first item represents the background image closest to the user. The individual background images can be a mix of CMS images and CSS functions. For more details, please see the documentation on multiple CSS backgrounds.

In the following example, a gradient CSS function is combined with a background image from the CMS content.

Notes

  • When specifying multiple backgrounds using plain CSS, the properties missing in successive backgrounds are inherited from the previous backgrounds. BackgroundImageTag behaves differently: If a property is missing in a background description, a reasonable default is used, so no properties are shared between the backgrounds.
  • The color property can only be specified for the last background.