Q
Version: 1.0.1
Source on Github

Compass Images

Provides mixins that work across many modern browsers with the latest CSS3 image rendering primitives.

These mixins provide intelligent cross-browser access to properties that accept images or image-like values (e.g. gradients). The syntax is very straightforward, it is exactly like the css syntax that you would use for the corresponding CSS3 properties: Values are comma and space delimited, just as they would be for a property. Vendor prefixes are used only when necessary.

Example (more examples are available by following the links below):

.in-css3 {
  background: url(foo.png),
              linear-gradient(to bottom right, #333, #0c0),
              radial-gradient(#c00, #fff 100px);
}
.with-compass {
  @include background(image-url("foo.png"),
                      linear-gradient(to bottom right, #333, #0c0),
                      radial-gradient(#c00, #fff 100px));
}

To enable SVG gradient support in Opera and IE9, lower the SVG shim threshold $svg-gradient-shim-threshold to 0.1 (or to whatever threshold you feel is best) in your stylesheet.

NOTE: At this time, Opera renders incorrectly an SVG background on a element with a border, repeating the gradient towards the end. You can set background-repeat: no-repeat to avoid this, but the gradient will not fill the area completely.

This file can be imported using: @import "compass/css3/images"

Examples

Background Gradients
css3 mixin for css gradients

Imports

  1. Browser Support – Provides configuration options for the Compass Browser Support Matrix.
  2. Hacks – Mixins for hacking specific browsers.

Configurable Variables help

$graceful-usage-threshold

$graceful-usage-threshold

$graceful-usage-threshold

$graceful-usage-threshold

false

Compass assumes you will use the official gradient syntax, unless otherwise instructed.

Constants

(ie: "9", opera: "9.5-9.6")

These browsers support svg but not gradients so we can shim the gradient with an inline svg file.

(android: ("2.1", "3"))

These browsers require the old webkit gradient syntax

Functions

view source

?
1
2
3
4
5
6
7
8
9
@function linear-gradient($angle, $details...)
  $legacy-syntax: $use-legacy-gradient-syntax
  @if type-of($angle) != "number"
    $angle: compact($angle)
    $legacy-syntax: if(index($angle, "to"), false, true)
  @if $legacy-syntax
    @return _linear-gradient_legacy($angle, $details...)
  @else
    @return _linear-gradient($angle, $details...)
?
1
2
3
4
5
6
7
8
9
10
11
12
13
@function linear-gradient($angle, $details...) {
  $legacy-syntax: $use-legacy-gradient-syntax;
  @if type-of($angle) != "number" {
    $angle: compact($angle);
    $legacy-syntax: if(index($angle, "to"), false, true);
  }
  @if $legacy-syntax {
    @return _linear-gradient_legacy($angle, $details...);
  }
  @else {
    @return _linear-gradient($angle, $details...);
  }
}

Create a linear gradient using standard official or legacy syntax. This function must be included in one of the following image module mixins to work properly.

Mixins

view source

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
=each-gradient-prefix($values)
  @if prefixed(-svg, $values)
    +for-legacy-browsers($browsers-supporting-svg-but-not-gradients, $svg-gradient-shim-threshold)
      +with-prefix(-svg)
        @content
  @if prefixed(-owg, $values)
    +for-legacy-browsers($browsers-supporting-old-webkit-gradients, $owg-threshold)
      +with-prefix(-owg)
        @content
  +with-each-prefix(css-gradients, $gradient-support-threshold)
    @if $current-prefix
      @if prefixed($current-prefix, $values)
        @content
      @else if $debug-browser-support
        /* There is not a value that needs to be prefixed with #{$current-prefix} in: #{$values}
    @else
      @content
?
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
@mixin each-gradient-prefix($values) {
  @if prefixed(-svg, $values) {
    @include for-legacy-browsers($browsers-supporting-svg-but-not-gradients, $svg-gradient-shim-threshold) {
      @include with-prefix(-svg) {
        @content;
      }
    }
  }
  @if prefixed(-owg, $values) {
    @include for-legacy-browsers($browsers-supporting-old-webkit-gradients, $owg-threshold) {
      @include with-prefix(-owg) {
        @content;
      }
    }
  }
  @include with-each-prefix(css-gradients, $gradient-support-threshold) {
    @if $current-prefix {
      @if prefixed($current-prefix, $values) {
        @content;
      }
      @else if $debug-browser-support {
        /* There is not a value that needs to be prefixed with #{$current-prefix} in: #{$values} */
      }
    }
    @else {
      @content;
    }
  }
}
view source

?
1
2
3
4
5
6
7
=image-property($property, $values...)
  +each-gradient-prefix($values)
    @if $current-prefix
      #{$property}: prefix($current-prefix, $values)
    @else
      #{$property}: $values
    @content
?
1
2
3
4
5
6
7
8
9
10
11
@mixin image-property($property, $values...) {
  @include each-gradient-prefix($values) {
    @if $current-prefix {
      #{$property}: prefix($current-prefix, $values);
    }
    @else {
      #{$property}: $values;
    }
    @content;
  }
}
view source

?
1
2
=background($backgrounds...)
  +image-property(background, $backgrounds...)
?
1
2
3
@mixin background($backgrounds...) {
  @include image-property(background, $backgrounds...);
}

Background property support for vendor prefixing within values.

view source

?
1
2
3
4
=background-with-css2-fallback($backgrounds...)
  @if length($backgrounds) > 1 or prefixed(-css2, $backgrounds)
    background: -css2(nth($backgrounds, -1))
  +background($backgrounds...)
?
1
2
3
4
5
6
@mixin background-with-css2-fallback($backgrounds...) {
  @if length($backgrounds) > 1 or prefixed(-css2, $backgrounds) {
    background: -css2(nth($backgrounds, -1));
  }
  @include background($backgrounds...);
}

Set any number of background layers, along with a fallback. The final argument will be output separately, first, as a css2 fallback.

view source

?
1
2
3
4
=background-image($images...)
  +image-property(background-image, $images...)
    @if $current-prefix == -svg
      background-size: 100%
?
1
2
3
4
5
6
7
@mixin background-image($images...) {
  @include image-property(background-image, $images...) {
    @if $current-prefix == -svg {
      background-size: 100%;
    }
  }
}

Background image property support for vendor prefixing within values.

view source

?
1
2
3
4
5
=filter-gradient($start-color, $end-color, $orientation: vertical)
  +for-legacy-browsers((ie: "8"), $gradient-support-threshold)
    +has-layout
    $gradient-type: if($orientation == vertical, 0, 1)
    filter: progid:DXImageTransform.Microsoft.gradient(gradientType=#{$gradient-type}, startColorstr='#{ie-hex-str($start-color)}', endColorstr='#{ie-hex-str($end-color)}')
?
1
2
3
4
5
6
7
@mixin filter-gradient($start-color, $end-color, $orientation: vertical) {
  @include for-legacy-browsers((ie: "8"), $gradient-support-threshold) {
    @include has-layout;
    $gradient-type: if($orientation == vertical, 0, 1);
    filter: progid:DXImageTransform.Microsoft.gradient(gradientType=#{$gradient-type}, startColorstr='#{ie-hex-str($start-color)}', endColorstr='#{ie-hex-str($end-color)}');
  }
}

Emit a IE-Specific filters that renders a simple linear gradient. For use in IE 6 - 8. Best practice would have you apply this via a conditional IE stylesheet, but if you must, you should place this before any background-image properties that you have specified.

For the $orientation parameter, you can pass vertical or horizontal.

view source

?
1
2
3
4
5
6
7
8
9
=border-image($value)
  +with-each-prefix(border-image, $border-image-support-threshold)
    $border-prefix: $current-prefix
    +each-gradient-prefix($value)
      @if $current-prefix and prefixed($current-prefix, $value)
        $legacy-value: reject($value, fill)
        +prefix-prop(border-image, prefix($current-prefix, $legacy-value), $prefix: $border-prefix)
      @else
        +prefix-prop(border-image, $value, $prefix: $border-prefix)
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
@mixin border-image($value) {
  @include with-each-prefix(border-image, $border-image-support-threshold) {
    $border-prefix: $current-prefix;
    @include each-gradient-prefix($value) {
      @if $current-prefix and prefixed($current-prefix, $value) {
        $legacy-value: reject($value, fill);
        @include prefix-prop(border-image, prefix($current-prefix, $legacy-value), $prefix: $border-prefix);
      }
      @else {
        @include prefix-prop(border-image, $value, $prefix: $border-prefix);
      }
    }
  }
}

Border image property support for vendor prefixing properties and values.

view source

?
1
2
=list-style-image($image)
  +image-property(list-style-image, $image)
?
1
2
3
@mixin list-style-image($image) {
  @include image-property(list-style-image, $image);
}

List style image property support for vendor prefixing within values.

view source

?
1
2
=list-style($value)
  +image-property(list-style, $value)
?
1
2
3
@mixin list-style($value) {
  @include image-property(list-style, $value);
}

List style property support for vendor prefixing within values.

view source

?
1
2
=content($value)
  +image-property(content, $value)
?
1
2
3
@mixin content($value) {
  @include image-property(content, $value);
}

content property support for vendor prefixing within values.