Gerillass 3.0.0 is out. One gradient mixin replaces two, and text-gradient takes its colours first, so read the migration guide before you upgrade.
Gerillass
v3.0.0* You can call mixins with or without the gls- namespace (e.g. @include gls-sprite();).
The Sprite Sass mixin helps you apply background images to the selected elements using the CSS sprite technique.
Arguments
| Name | Type | Description |
|---|---|---|
$image-url | string | The URL of the sprite image. Important: Don't forget that the image link must be either absolute or relative to the generated CSS file. |
$position | number | string | Sets the position of the background-image. Multiple values must be separated by a space. Each is a length, a percentage, left, center, right, top, bottom, var() or a maths function; a CSS-wide keyword works alone. |
To learn more about the background-position property values, check out the [links](#related-links) at the end of the page.
Examples
Every example on this page draws from one sheet, sprite.png: six frames of a
walk cycle laid out in a row, each 100 by 100, in a 600 by 100 image.
Give the element a width and a height. The mixin sets the image and the
position; it cannot know how much of the sheet you want. Those two values are
the size of one tile, and you need to know it.
One tile. Pass the sheet and the position of the frame you want, and size the element to match a single tile.
.element {
width: 100px;
height: 100px;
@include sprite("/images/docs/sprite.png", 0 0);
}.element {
width: 100px;
height: 100px;
display: inline-block;
background-image: url("/images/docs/sprite.png");
background-position: 0 0;
background-repeat: no-repeat;
}Several tiles from the same sheet. The mixin is called once with the sheet, and once per element with only a position: each frame sits 100px further to the left, so the offsets run 0, -100px, -200px and so on.
.frame {
width: 100px;
height: 100px;
@include sprite("/images/docs/sprite.png");
}
.frame--1 { @include sprite(0 0); }
.frame--2 { @include sprite(-100px 0); }
.frame--3 { @include sprite(-200px 0); }
.frame--4 { @include sprite(-300px 0); }.frame {
width: 100px;
height: 100px;
display: inline-block;
background-image: url("/images/docs/sprite.png");
background-repeat: no-repeat;
}
.frame--1 {
background-position: 0 0;
}
.frame--2 {
background-position: -100px 0;
}
.frame--3 {
background-position: -200px 0;
}
.frame--4 {
background-position: -300px 0;
}Why a sheet in the first place. The six frames are a walk cycle, so stepping the background position across them in one animation plays it, out of a single request rather than six.
.element {
width: 100px;
height: 100px;
@include sprite("/images/docs/sprite.png", 0 0);
animation: walk 0.7s steps(6) infinite;
}
@keyframes walk {
to {
background-position: -600px 0;
}
}.element {
width: 100px;
height: 100px;
display: inline-block;
background-image: url("/images/docs/sprite.png");
background-position: 0 0;
background-repeat: no-repeat;
animation: walk 0.7s steps(6) infinite;
}
@keyframes walk {
to {
background-position: -600px 0;
}
}What it refuses
With two arguments the first has to be one path. Until 2.3.1 it was not checked, so a list went into url(), which a browser drops, leaving the element without its sheet.
.element {
@include sprite("/img/a.png" "/img/b.png", 0 -40px);
}Error: `"/img/a.png" "/img/b.png"` is not a valid image path for `sprite`: with two arguments the first is one path as a string, and a browser drops a list in `url()`. Pass a path such as `"/img/sprite.png"`, then the position.A position the browser drops stops the build too. Measured in Chrome 152, background-position drops a word other than left, center, right, top or bottom, a unitless number other than 0, a unit that is not a length, and three or four lengths with no keyword. Until 2.3.1 these compiled, and the browser dropped the declaration without a word.
.element {
@include sprite("/img/sprite.png", auto);
}Error: `auto` is not a valid position for `sprite`: `auto` is not a length or one of left, center, right, top or bottom. A browser drops the declaration.