Core Features

Auto prefixing

Edit ‘Auto prefixing’ on Github

Vendor prefixes for properties, functions, @-rules and declarations are automatically generated – based on trusted sources – so you can maintain cross-browser support while keeping your source code clean and easy to maintain.

.foo {
  background: linear-gradient(to right, red, white);
}
.foo {
  background: -webkit-linear-gradient(to right, red, white);
  background: linear-gradient(to right, red, white);
}
Example #1
@keyframes bounce {
  50% { transform: scale(1.4); }
}
@-webkit-keyframes bounce {
  50% {-webkit-transform: scale(1.4);
               transform: scale(1.4);}
}
@keyframes bounce {
  50% {-webkit-transform: scale(1.4);
               transform: scale(1.4);}
}
Example #2

Nesting

Edit ‘Nesting’ on Github

Rules can be nested to avoid repetitive typing when scoping to a common parent selector.

.homepage {
  color: #333;
  background: white;
  .content {
    p {
      font-size: 110%;
    }
  }
}
.homepage {
  color: #333;
  background: white;
}
.homepage .content p {
  font-size: 110%;
}
Example #3

Parent referencing

You can use the parent reference symbol & for placing the parent selector explicitly.

.homepage {
  .no-js & {
    p {
      font-size: 110%;
    }
  }
}
.no-js .homepage p {
  font-size: 110%;
}
Example #4

Variables

Edit ‘Variables’ on Github

Declare variables in your CSS with a @set directive and use them with the $() function.

Variables can also be injected at runtime with the vars option.

/* Defining variables */
@set {
  dark: #333;
  light: #F4F2E2;
  smaller-screen: screen and (max-width: 800px);
}

/* Using variables */
@media $(smaller-screen) {
  ul, p {
    color: $(dark);
    /* Using a fallback value with an undefined variable */
    background-color: $(accent-color, #ff0);
  }
}
Example #5

/* Interpolation */
.username::before {
  content: "$(greeting)";
}
Example #6

Conditionals

Sections of CSS can be included and excluded on the basis of variable existence with the @ifset directive:

@set foo #f00;
@set bar true;

@ifset foo {
  p {
    color: $(foo);
  }
}

p {
  font-size: 12px;
  @ifset not foo {
    line-height: 1.5;
  }
  @ifset bar(true) {
    margin-bottom: 5px;
  }
}
Example #7

Direct @import

Edit ‘Direct @import’ on Github

Files referenced with the @import directive are inlined directly to save on http requests. Relative URL paths in the CSS are also updated if necessary.

If you specify a media designation following the import URL — as per the CSS standard — the imported file content is wrapped in a @media block.

/* Standard CSS @import statements */
@import "print.css" print;
@import url( "small-screen.css" ) screen and ( max-width: 500px );
@media print {
  /* Contents of print.css */
}
@media screen and ( max-width: 500px ) {
  /* Contents of small-screen.css */
}
Example #8

Rule inheritance

Edit ‘Rule inheritance’ on Github

By using the @extend directive and passing it a named ruleset or selector from any other rule you can share styles more effectively across a stylesheet.

Abstract rules can be used if you just need to extend a generic set of declarations.

.negative-text {
  overflow: hidden;
  text-indent: -9999px;
}

.sidebar-headline {
  @extend .negative-text;
  background: url( headline.png ) no-repeat;
}
.negative-text,
.sidebar-headline {
  overflow: hidden;
  text-indent: -9999px;
}

.sidebar-headline {
  background: url( headline.png ) no-repeat;
}
Example #9

Inheritance is recursive:

.one { color: pink; }
.two { @extend .one; }
.three { @extend .two; }
.four { @extend .three; }
.one, .two, .three, .four { color: pink; }
Example #10

Referencing by name

If you want to reference a rule without being concerned about later changes to the identifying selector use the @name directive:

.foo123 {
  @name foo;
  text-decoration: underline;
}

.bar {
  @include foo;
}
.baz {
  @extend foo;
}
Example #11

Extending with pseudo classes/elements

@extend arguments can adopt pseudo classes/elements by appending an exclamation mark:

.link-base {
  color: #bada55;
  text-decoration: underline;
}
.link-base:hover,
.link-base:focus {
  text-decoration: none;
}

.link-footer {
  @extend .link-base, .link-base:hover!, .link-base:focus!;
  color: blue;
}
.link-base,
.link-footer {
  color: #bada55;
  text-decoration: underline;
}

.link-base:hover,
.link-base:focus,
.link-footer:hover,
.link-footer:focus {
  text-decoration: none;
}

.link-footer {
  color: blue;
}
Example #12

The same outcome can also be achieved with an Abstract rule wrapper to simplify repeated use:

.link-base {
  color: #bada55;
  text-decoration: underline;
}
.link-base:hover,
.link-base:focus {
  text-decoration: none;
}

@abstract link-base {
  @extend .link-base, .link-base:hover!, .link-base:focus!;
}

.link-footer {
  @extend link-base;
  color: blue;
}
Example #13

Abstract rules

Edit ‘Abstract rules’ on Github

Abstract rules are generic rules that can be extended with the @extend directive or mixed in (without arguments) like regular mixins with the @include directive.

@abstract ellipsis {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
@abstract heading {
  font: bold 1rem serif;
  letter-spacing: .1em;
}

.foo {
  @extend ellipsis;
  display: block;
}
.bar {
  @extend ellipsis;
  @include heading;
}
.foo,
.bar {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
.foo {
  display: block;
}
.bar {
  font: bold 1rem serif;
  letter-spacing: .1em;
}
Example #14

Loops

Edit ‘Loops’ on Github

For...in loops with lists and generator functions.

@for fruit in apple, orange, pear {
  .#(fruit) {
    background-image: url("images/#(fruit).jpg");
  }
}
.apple { background-image: url(images/apple.jpg); }
.orange { background-image: url(images/orange.jpg); }
.pear { background-image: url(images/pear.jpg); }
Example #15
@for base in range(2, 24) {
  @for i in range(1, #(base)) {
    .grid-#(i)-of-#(base) {
      width: math(#(i) / #(base) * 100, %);
    }
  }
}
.grid-1-of-2 { width: 50%; }
.grid-2-of-2 { width: 100%; }
/*
    Intermediate steps ommited.
*/
.grid-23-of-24 { width: 95.83333%; }
.grid-24-of-24 { width: 100%; }
Example #16

Functions

math()

Edit ‘math()’ on Github

Evaluate a raw mathematical expression.

math( expression [, unit] )

Examples

font-size: math( 12 / 16, em );
font-size: 0.75em;
Example #17

h-adjust()

Edit ‘h-adjust()’ on Github

Adjust the hue of a color value.

h-adjust( color, offset )

Parameters

  • color Any valid CSS color value
  • offset The percentage to offset the color hue (percent mark optional)

Returns

The modified color value.

Examples

color: h-adjust( deepskyblue -10 );
Example #18

s-adjust()

Edit ‘s-adjust()’ on Github

Adjust the saturation of a color value.

s-adjust( color, offset )

Parameters

  • color Any valid CSS color value
  • offset The percentage to offset the color hue (percent mark optional)

Returns

The modified color value.

Examples

/* Desaturate */
color: s-adjust( deepskyblue -100 );
Example #19

l-adjust()

Edit ‘l-adjust()’ on Github

Adjust the lightness of a color value.

l-adjust( color, offset )

Parameters

  • color Any valid CSS color value
  • offset The percentage to offset the color hue (percent mark optional)

Returns

The modified color value.

Examples

color: l-adjust( deepskyblue 10 );
Example #20

a-adjust()

Edit ‘a-adjust()’ on Github

Manipulate the opacity (alpha channel) of a color value.

a-adjust( color, offset )

Parameters

  • color Any valid CSS color value
  • offset The percentage to offset the color opacity

Returns

The modified color value

Examples

/* Reduce color opacity by 10% */
color: a-adjust( rgb(50,50,0) -10 );
Example #21

hsl-adjust()

Edit ‘hsl-adjust()’ on Github

Manipulate the hue, saturation and lightness of a color value

hsl-adjust( color, hue-offset, saturation-offset, lightness-offset )

Parameters

  • color Any valid CSS color value
  • hue-offset The percentage to offset the color hue
  • saturation-offset The percentage to offset the color saturation
  • lightness-offset The percentage to offset the color lightness

Returns

The modified color value

Examples

/* Lighten and increase saturation */
color: hsl-adjust( red 0 5 5 );
Example #22

hsla-adjust()

Edit ‘hsla-adjust()’ on Github

Manipulate the hue, saturation, lightness and opacity of a color value.

hsla-adjust( color, hue-offset, saturation-offset, lightness-offset, alpha-offset )

Parameters

  • color Any valid CSS color value
  • hue-offset The percentage to offset the color hue
  • saturation-offset The percentage to offset the color saturation
  • lightness-offset The percentage to offset the color lightness
  • alpha-offset The percentage to offset the color opacity

Returns

The modified color value.

Examples

color: hsla-adjust( #f00 0 5 5 -10 );
Example #23

data-uri()

Edit ‘data-uri()’ on Github

Create a data-uri.

data-uri( url )

Parameters

  • url URL of an asset

url cannot be external, and must not be written with an http protocol prefix.

The following file extensions are supported: jpg, jpeg, gif, png, svg, svgz, ttf, woff

Returns

The created data-uri as a string inside a CSS url().

Examples

background: silver data-uri(../images/stripe.png);
background: silver url(data:<img-data>);
Example #24

this()

Edit ‘this()’ on Github

Reference another property value from the same containing block.

Restricted to referencing properties that don't already reference other properties.

this( property-name, fallback )

Parameters

  • property-name Property name
  • fallback A CSS value

Returns

The referenced property value, or the fallback if it has not been set.

Examples

.foo {
  width: this( height );
  height: 100em;
}
Example #25

/* The following both fail because they create circular references. */
.bar {
  height: this( width );
  width: this( height );
}
Example #26

query()

Edit ‘query()’ on Github

Copy a value from another rule.

query( target [, property-name = default] [, fallback] )

Parameters

  • target A rule selector, an abstract rule name or context keyword: previous, next (also parent and top within nested structures)
  • property-name The CSS property name to copy, or just default to pass over. Defaults to the calling property
  • fallback A CSS value to use if the target property does not exist

Returns

The referenced property value, or the fallback if it has not been set.

Examples

.foo {
  width: 40em;
  height: 100em;
}

.bar {
  width: query( .foo ); /* 40em */
  margin-top: query( .foo, height ); /* 100em */
  margin-bottom: query( .foo, default, 3em ); /* 3em */
}
Example #27

Using context keywords:

.foo {
  width: 40em;
  .bar {
    width: 30em;
    .baz: {
      width: query( parent ); /* 30em */
      .qux {
        width: query( top ); /* 40em */
      }
    }
  }
}
Example #28

Selector grouping

Edit ‘Selector grouping’ on Github

Selector grouping with the :any pseudo class (modelled after CSS4 :matches) simplifies the creation of complex selector chains.

:any( .sidebar, .block ) a:any( :hover, :focus ) {
  color: lemonchiffon;
}
.block a:hover,
.block a:focus,
.sidebar a:hover,
.sidebar a:focus {
  color: lemonchiffon;
}
Example #29

Selector aliases

Edit ‘Selector aliases’ on Github

Selector aliases can be useful for grouping together common selector chains for reuse.

They're defined with the @selector directive, and can be used anywhere you might use a pseudo class.

@selector heading :any(h1, h2, h3, h4, h5, h6);
@selector radio input[type="radio"];
@selector hocus :any(:hover, :focus);

/* Selector aliases with arguments */
@selector class-prefix :any([class^="#(0)"], [class*=" #(0)"]);
@selector col :class-prefix(-col);

.sidebar :heading {
  color: honeydew;
}

:radio {
  margin-right: 4px;
}

:col {
  float: left;
}

p a:hocus {
  text-decoration: none;
}
.sidebar h1, .sidebar h2,
.sidebar h3, .sidebar h4,
.sidebar h5, .sidebar h6 {
  color: honeydew;
}

input[type="radio"] {
  margin-right: 4px;
}

[class^="col-"],
[class*=" col-"] {
  border: 1px solid rgba(0,0,0,.5);
}

p a:hover,
p a:focus {
  text-decoration: none;
}
Example #30

Selector splatting

Selector splats are a special kind of selector alias that expand using passed arguments.

@selector-splat input input[type="#(text)"];

form :input(time, text, url, email, number) {
  border: 1px solid;
}
form input[type="time"],
form input[type="text"],
form input[type="url"],
form input[type="email"],
form input[type="number"] {
  border: 1px solid;
}
Example #31

Mixins

Edit ‘Mixins’ on Github

Mixins make reusing small snippets of CSS much simpler. You define them with the @mixin directive.

Positional arguments via the argument function #() extend the capability of mixins for repurposing in different contexts.

@mixin display-font {
  font-family: "Arial Black", sans-serif;
  font-size: #(0); 
  letter-spacing: #(1);
}

/* Another mixin with default arguments */
@mixin blue-theme {
  color: #(0 navy);
  background-image: url("images/#(1 cross-hatch).png");
}

/* Applying the mixins */
.foo {
  @include display-font(100%, .1em), blue-theme;
}
.foo {
  font-family: "Arial Black", sans-serif;
  font-size: 100%;
  letter-spacing: .1em;
  color: navy;
  background-image: url("images/cross-hatch.png");
}
Example #32

Skipping arguments

Mixin arguments can be skipped by using the default keyword:

@mixin display-font {
  font-size: #(0 100%);
  letter-spacing: #(1);
}

/* Applying the mixin skipping the first argument so the
   default value is used instead */
#foo {
  @include display-font(default, .3em);
}
Example #33

Sometimes you may need to use the same positional argument more than once. In this case the default value only needs to be specified once:

@mixin square {
  width:  #(0 10px);
  height: #(0);
}

.foo {
  @include square;
}
#foo {
  width:  10px;
  height: 10px;
}
Example #34

Mixing-in from other sources

Normal rules and abstract rules can also be used as static mixins without arguments:

@abstract negative-text {
  text-indent: -9999px;
  overflow: hidden;
}

#main-content .theme-border {
  border: 1px solid maroon;
}

.foo {
  @include negative-text, #main-content .theme-border;
}
Example #35

Fragments

Edit ‘Fragments’ on Github

Fragments – defined and invoked with the @fragment directive – work in a similar way to mixins, except that they work at block level:

@fragment input-placeholder {
  #(1)::-webkit-input-placeholder { color: #(0); }
  #(1):-moz-placeholder           { color: #(0); }
  #(1)::placeholder               { color: #(0); }
  #(1).placeholder-state          { color: #(0); }
}

@fragment input-placeholder(#777, textarea);
textarea::-webkit-input-placeholder { color: #777; }
textarea:-moz-placeholder           { color: #777; }
textarea::placeholder               { color: #777; }
textarea.placeholder-state          { color: #777; }
Example #36

Plugins

aria

Edit ‘aria’ on Github

Pseudo classes for working with ARIA roles, states and properties.

:role(tablist) {...}
:aria-expanded {...}
:aria-expanded(false) {...}
:aria-label {...}
:aria-label(foobarbaz) {...}
[role="tablist"] {...}
[aria-expanded="true"] {...}
[aria-expanded="false"] {...}
[aria-label] {...}
[aria-label="foobarbaz"] {...}
Example #37

canvas

Edit ‘canvas’ on Github

Bitmap image generator.

Requires the GD image library bundled with PHP.

/* Create square semi-opaque png. */
@canvas foo {
  width: 50;
  height: 50;
  fill: rgba(255, 0, 0, .5);
}

body {
  background: white canvas(foo);
}
Example #38

/* White to transparent east facing gradient with 10px
   margin and background fill. */
@canvas horz-gradient {
  width: #(0);
  height: 150;
  fill: canvas-linear-gradient(to right, #(1 white), #(2 rgba(255,255,255,0)));
  background-fill: powderblue;
  margin: 10;
}

/* Rectangle 300x150. */
body {
  background: canvas(horz-gradient, 300);
}
/* Flipped gradient, using canvas-data() to generate a data URI. */
.bar {
  background: canvas-data(horz-gradient, 100, rgba(255,255,255,0), white);
}
Example #39

/* Google logo resized to 400px width and given a sepia effect. */
@canvas sepia {
  src: url(http://www.google.com/images/logo.png);
  width: 400;
  canvas-filter: greyscale() colorize(45, 45, 0);
}

.bar {
  background: canvas(sepia);
}
Example #40

ease

Edit ‘ease’ on Github

Expanded easing keywords for transitions.

  • ease-in-out-back
  • ease-in-out-circ
  • ease-in-out-expo
  • ease-in-out-sine
  • ease-in-out-quint
  • ease-in-out-quart
  • ease-in-out-cubic
  • ease-in-out-quad
  • ease-out-back
  • ease-out-circ
  • ease-out-expo
  • ease-out-sine
  • ease-out-quint
  • ease-out-quart
  • ease-out-cubic
  • ease-out-quad
  • ease-in-back
  • ease-in-circ
  • ease-in-expo
  • ease-in-sine
  • ease-in-quint
  • ease-in-quart
  • ease-in-cubic
  • ease-in-quad

See easing demos for live examples.

transition: .2s ease-in-quad;
transition: .2s cubic-bezier(.550,.085,.680,.530);
Example #41

forms

Edit ‘forms’ on Github

Pseudo classes for working with forms.

:input(date, search, email) {...}
:checkbox {...}
:radio {...}
:text {...}
input[type="date"], input[type="search"], input[type="email"] {...}
input[type="checkbox"] {...}
input[type="radio"] {...}
input[type="text"] {...}
Example #42

hocus-pocus

Edit ‘hocus-pocus’ on Github

Composite :hover/:focus/:active pseudo classes.

a:hocus { color: red; }
a:pocus { color: red; }
a:hover, a:focus { color: red; }
a:hover, a:focus, a:active { color: red; }
Example #43

property-sorter

Edit ‘property-sorter’ on Github

Property sorting.

Examples use the predefined property sorting table. To define a custom sorting order pass an array to csscrush_set_property_sort_order()

color: red;
background: #000;
opacity: .5;
display: block;
position: absolute;
position: absolute;
display: block;
opacity: .5;
color: red;
background: #000;
Example #44

svg

Edit ‘svg’ on Github

Define and embed simple SVG elements, paths and effects inside CSS

@svg foo {
  type: star;
  star-points: #(0 5);
  radius: 100 50;
  margin: 20;
  stroke: black;
  fill: red;
  fill-opacity: .5;
}

/* Embed SVG with svg() function (generates an svg file). */
body {
  background: svg(foo);
}
/* As above but a 3 point star creating a data URI instead of a file. */
body {
  background: svg-data(foo, 3);
}
Example #45

/* Using path data and stroke styles to create a plus sign. */
@svg plus {
  d: "M0,5 h10 M5,0 v10";
  width: 10;
  height: 10;
  stroke: white;
  stroke-linecap: round;
  stroke-width: 2;
}
Example #46

/* Skewed circle with radial gradient fill and drop shadow. */
@svg circle {
  type: circle;
  transform: skewX(30);
  diameter: 60;
  margin: 20;
  fill: svg-radial-gradient(at top right, gold 50%, red);
  drop-shadow: 2 2 0 rgba(0,0,0,1);
}
Example #47

/* 8-sided polygon with an image fill.
   Note: images usually have to be converted to data URIs, see known issues below. */
@svg pattern {
  type: polygon;
  sides: 8;
  diameter: 180;
  margin: 20;
  fill: pattern(data-uri(kitten.jpg), scale(1) translate(-100 0));
  fill-opacity: .8;
}
Example #48

Known issues

Firefox does not allow linked images (or other svg) when svg is in "svg as image" mode.

API

API functions

Edit ‘API functions’ on Github

csscrush_file()

Process CSS file and return the compiled file URL.

csscrush_file( string $file [, array $options ] )


csscrush_tag()

Process CSS file and return an html link tag with populated href.

csscrush_tag( string $file [, array $options [, array $tag_attributes ]] )


csscrush_inline()

Process CSS file and return CSS as text wrapped in html style tags.

csscrush_inline( string $file [, array $options [, array $tag_attributes ]] )


csscrush_string()

Compile a raw string of CSS string and return it.

csscrush_string( string $string [, array $options ] )


csscrush_get()

Retrieve a config setting or option default.

csscrush_get( string $object_name, string $property )

Parameters

  • $object_name Name of object you want to inspect: 'config' or 'options'.
  • $property

csscrush_set()

Set a config setting or option default.

csscrush_set( string $object_name, mixed $settings )

Parameters

  • $object_name Name of object you want to modify: 'config' or 'options'.
  • $settings Associative array of keys and values to set, or callable which argument is the object specified in $object_name.

csscrush_plugin()

Register a plugin.

csscrush_plugin( string $name, callable $callback )


csscrush_stat()

Get compilation stats from the most recent compiled file.

csscrush_stat()

Options

Edit ‘Options’ on Github
Option Values (default in bold) Description
minify true | false | Array Enable or disable minification. Optionally specify an array of advanced minification parameters. Currently the only advanced option is 'colors', which will compress all color values in any notation.
formatter block | single-line | padded Set the formatting mode. Overrides minify option if both are set.
newlines use-platform | windows/win | unix Set the output style of newlines
boilerplate true | false | Path Prepend a boilerplate to the output file
versioning true | false Append a timestamped querystring to the output filename
vars Array An associative array of CSS variables to be applied at runtime. These will override variables declared globally or in the CSS.
cache true | false Turn caching on or off.
output_dir Path Specify an output directory for compiled files. Defaults to the same directory as the host file.
output_file Output filename Specify an output filename (suffix is added).
asset_dir Path Directory for SVG and image files generated by plugins (defaults to the main file output directory).
stat_dump false | true | Path Save compile stats and variables to a file in json format.
vendor_target "all" | "moz", "webkit", ... | Array Limit aliasing to a specific vendor, or an array of vendors.
rewrite_import_urls true | false | "absolute" Rewrite relative URLs inside inlined imported files.
import_paths Array Additional paths to search when resolving relative import URLs.
plugins Array An array of plugin names to enable.
source_map true | false Output a source map (compliant with the Source Map v3 proposal).
context Path Context for importing resources from relative urls (Only applies to `csscrush_string()` and command line utility).
doc_root Path Specify an alternative server document root for situations where the CSS is being served behind an alias or url rewritten path.

Getting Started

PHP

Edit ‘PHP’ on Github

If you're using Composer you can use Crush in your project with the following line in your terminal:

composer require css-crush/css-crush
Example #49

If you're not using Composer yet just download the library (zip or tar) into a convenient location and require the bootstrap file:

<?php require_once 'path/to/CssCrush.php'; ?>
Example #50

JavaScript

Edit ‘JavaScript’ on Github

This preprocessor is written in PHP, so as prerequisite you will need to have PHP installed on your system to use the JS api.

npm install csscrush
Example #51

All methods can take the standard options (camelCase) as the second argument.

const csscrush = require('csscrush');

// Compile. Returns promise.
csscrush.file('./styles.css', {sourceMap: true});

// Compile string of CSS. Returns promise.
csscrush.string('* {box-sizing: border-box;}');

// Compile and watch file. Returns event emitter (triggers 'data' on compile).
csscrush.watch('./styles.css');
Example #52