Background Image Sass Mixin

Background Image

Type: Mixin

@include background-image();

* You can call mixins with or without the gls- namespace (e.g. @include gls-background-image();).

The Background Image Sass mixin allows you to apply background images to the selected elements. It gives you an easy, one-line method.

Arguments

Name	Type	Description
`$image-url`	string, function	The URL of the background image, as a string. A value that already is an image, `var()`, `url()`, `image-set()` or a gradient, is written as it is rather than wrapped in `url()`. A list, a number, a colour or a boolean is refused.
`$filter-color`	color \| list	The color or list of colors you want to apply as a filter over the background image. Multiple color values must be separated by a space. Several colours are the stops of a gradient and take the forms Linear Gradient takes. When `$image-url` is `null` and the image is set in the markup, the filter is a layer over it, so it can also be an image: a `linear-gradient()` for a scrim, a `radial-gradient()` for a vignette, or a `url()` for a pattern.
`$filter-direction`	string	The direction of the gradient. It only works when you pass multiple color values for the `$filter-color` argument, but a value it does not accept is refused with an error whatever the number of colors. Accepts the values `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`, and `top-left`. The default value is `top`.

Use null if you want to skip an argument. See [the examples](#examples) for more.

Examples

Simply call the mixin in a selector and pass the URL of the background image.

Sass

.element{
  @include background-image("/images/backgrounds/07.jpg");
}

CSS

.element {
  background-image: url("/images/backgrounds/07.jpg");
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

Now let's apply a color filter to it by passing a color value for the $filter-color argument.

Sass

.element{
  @include background-image("/images/backgrounds/07.jpg", rgba(255, 204, 153, 0.5));
}

CSS

.element {
  background-image: linear-gradient(to top, rgba(255, 204, 153, 0.5), rgba(255, 204, 153, 0.5)), url("/images/backgrounds/07.jpg");
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

Important: Multiple color values must be separated by a space.

Now let's pass multiple color values for $filter-color to make the background image look even more interesting.

Sass

.element{
  @include background-image("/images/backgrounds/07.jpg", rgba(0, 0, 0, 0.5) rgba(40, 102, 100, 0.8));
}

CSS

.element {
  background-image: linear-gradient(to top, rgba(0, 0, 0, 0.5), rgba(40, 102, 100, 0.8)), url("/images/backgrounds/07.jpg");
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

Tip: The value you pass for $filter-direction indicates the position of the final color stop.

Now let's try the $filter-direction option. While we do, let's use sharper color transitions to see the effect clearly.

Sass

.element{
  @include background-image("/images/backgrounds/07.jpg", rgba(0, 128, 128, 0.7) rgba(255, 192, 203, 0.8), right);
}

CSS

.element {
  background-image: linear-gradient(to right, rgba(0, 128, 128, 0.7), rgba(255, 192, 203, 0.8)), url("/images/backgrounds/07.jpg");
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

Important: Please examine the CSS output. When you add a background image to an element using the style attribute, the CSS output is different from the others. This prevents the background-image declarations on both sides from overriding each other.

There will be times when you want to add a background image to an element using the style attribute, like in the example below. In those cases, just use null to skip the $image-url argument.

HTML

<div class="element" style="background-image: url(/images/backgrounds/07.jpg)"></div>

Sass

.element{
  @include background-image(null, rgba(teal, 0.7) rgba(pink, 0.8), right);
}

CSS

.element {
  position: relative;
}
.element::after {
  content: "";
  display: block;
  position: absolute;
  left: 0;
  top: 0;
  width: 100%;
  height: 100%;
  background: linear-gradient(to right, rgba(0, 128, 128, 0.7), rgba(255, 192, 203, 0.8));
}
.element > * {
  position: relative;
  z-index: 1;
}
.element {
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

You are probably wondering why those position: relative and z-index: 1 style rules are applied to the direct children of the selected element. These rules exist to prevent the color filter from covering the direct children when you add the background image to an element using the style attribute. Let's try it with a title placed inside the selected element to see it in action.

HTML

<div class="element" style="background-image: url(/images/backgrounds/07.jpg)">
  <h2>A beautiful title text standing over the color filter.</h2>
</div>

Sass

.element{
  @include background-image(null, rgba(teal, 0.7) rgba(pink, 0.8), right);
}

CSS

.element {
  position: relative;
}
.element::after {
  content: "";
  display: block;
  position: absolute;
  left: 0;
  top: 0;
  width: 100%;
  height: 100%;
  background: linear-gradient(to right, rgba(0, 128, 128, 0.7), rgba(255, 192, 203, 0.8));
}
.element > * {
  position: relative;
  z-index: 1;
}
.element {
  background-position: center center;
  background-repeat: no-repeat;
  background-size: cover;
}

Result

What it refuses

An image that is not one path stops the build. Until 2.3.1 anything went into url(): measured in Chrome 152, a list such as url(16 9) is dropped, and url(42) or url(true) is kept but asks for a file of that name, which is never the image meant.

Sass

.element {
  @include background-image(16 9);
}

Error: `16 9` is not a valid $image-url for `background-image`: it is a list where one image is meant, and a browser drops `url()` with a list in it. Pass one path as a string, such as `"/img/hero.png"`.

A filter colour that is not a colour is refused too, since 2.3.1. Measured in Chrome 152, a word drops the filter, and a length written into background is read as a position rather than a colour.

Sass

.element {
  @include background-image("/img/a.png", huge);
}

Error: `huge` is not a valid $filter-color for `background-image`: it is not a colour. Pass a colour, such as `rgba(0, 0, 0, 0.5)`, or several for a gradient.