CSS preprocessor
Core Features
Auto prefixing
Edit ‘Auto prefixing’ on GithubVendor 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.
Nesting
Edit ‘Nesting’ on GithubRules can be nested to avoid repetitive typing when scoping to a common parent selector.
Parent referencing
You can use the parent reference symbol &
for placing the parent selector explicitly.
Variables
Edit ‘Variables’ on GithubDeclare 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.
Conditionals
Sections of CSS can be included and excluded on the basis of variable existence with the @ifset
directive:
Direct @import
Edit ‘Direct @import’ on GithubFiles 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.
Rule inheritance
Edit ‘Rule inheritance’ on GithubBy 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.
Inheritance is recursive:
Referencing by name
If you want to reference a rule without being concerned about later changes to the identifying selector use the @name
directive:
Extending with pseudo classes/elements
@extend
arguments can adopt pseudo classes/elements by appending an exclamation mark:
The same outcome can also be achieved with an Abstract rule wrapper to simplify repeated use:
Abstract rules
Edit ‘Abstract rules’ on GithubAbstract rules are generic rules that can be extended with the @extend
directive or mixed in (without arguments) like regular mixins with the @include
directive.
Loops
Edit ‘Loops’ on GithubFor...in loops with lists and generator functions.
Functions
math()
Edit ‘math()’ on GithubEvaluate a raw mathematical expression.
math( expression [, unit] )
Examples
h-adjust()
Edit ‘h-adjust()’ on GithubAdjust the hue of a color value.
h-adjust( color, offset )
Parameters
color
Any valid CSS color valueoffset
The percentage to offset the color hue (percent mark optional)
Returns
The modified color value.
Examples
s-adjust()
Edit ‘s-adjust()’ on GithubAdjust the saturation of a color value.
s-adjust( color, offset )
Parameters
color
Any valid CSS color valueoffset
The percentage to offset the color hue (percent mark optional)
Returns
The modified color value.
Examples
l-adjust()
Edit ‘l-adjust()’ on GithubAdjust the lightness of a color value.
l-adjust( color, offset )
Parameters
color
Any valid CSS color valueoffset
The percentage to offset the color hue (percent mark optional)
Returns
The modified color value.
Examples
a-adjust()
Edit ‘a-adjust()’ on GithubManipulate the opacity (alpha channel) of a color value.
a-adjust( color, offset )
Parameters
color
Any valid CSS color valueoffset
The percentage to offset the color opacity
Returns
The modified color value
Examples
hsl-adjust()
Edit ‘hsl-adjust()’ on GithubManipulate the hue, saturation and lightness of a color value
hsl-adjust( color, hue-offset, saturation-offset, lightness-offset )
Parameters
color
Any valid CSS color valuehue-offset
The percentage to offset the color huesaturation-offset
The percentage to offset the color saturationlightness-offset
The percentage to offset the color lightness
Returns
The modified color value
Examples
hsla-adjust()
Edit ‘hsla-adjust()’ on GithubManipulate 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 valuehue-offset
The percentage to offset the color huesaturation-offset
The percentage to offset the color saturationlightness-offset
The percentage to offset the color lightnessalpha-offset
The percentage to offset the color opacity
Returns
The modified color value.
Examples
data-uri()
Edit ‘data-uri()’ on GithubCreate 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
this()
Edit ‘this()’ on GithubReference 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 namefallback
A CSS value
Returns
The referenced property value, or the fallback if it has not been set.
Examples
query()
Edit ‘query()’ on GithubCopy 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
(alsoparent
andtop
within nested structures)property-name
The CSS property name to copy, or justdefault
to pass over. Defaults to the calling propertyfallback
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
Using context keywords:
Selector grouping
Edit ‘Selector grouping’ on GithubSelector grouping with the :any
pseudo class (modelled after CSS4 :matches) simplifies the creation of complex selector chains.
Selector aliases
Edit ‘Selector aliases’ on GithubSelector 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 splatting
Selector splats are a special kind of selector alias that expand using passed arguments.
Mixins
Edit ‘Mixins’ on GithubMixins 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.
Skipping arguments
Mixin arguments can be skipped by using the default keyword:
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:
Mixing-in from other sources
Normal rules and abstract rules can also be used as static mixins without arguments:
Fragments
Edit ‘Fragments’ on GithubFragments – defined and invoked with the @fragment
directive – work in a similar way to mixins, except that they work at block level:
Plugins
aria
Edit ‘aria’ on GithubPseudo classes for working with ARIA roles, states and properties.
canvas
Edit ‘canvas’ on GithubBitmap image generator.
Requires the GD image library bundled with PHP.
ease
Edit ‘ease’ on GithubExpanded 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.
forms
Edit ‘forms’ on GithubPseudo classes for working with forms.
hocus-pocus
Edit ‘hocus-pocus’ on GithubComposite :hover/:focus/:active pseudo classes.
property-sorter
Edit ‘property-sorter’ on GithubProperty sorting.
Examples use the predefined property sorting table. To define a custom sorting order pass an array to csscrush_set_property_sort_order()
svg
Edit ‘svg’ on GithubDefine and embed simple SVG elements, paths and effects inside CSS
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 Githubcsscrush_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 GithubOption | 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 GithubIf you're using Composer you can use Crush in your project with the following line in your terminal:
If you're not using Composer yet just download the library (zip or tar) into a convenient location and require the bootstrap file:
JavaScript
Edit ‘JavaScript’ on GithubThis preprocessor is written in PHP, so as prerequisite you will need to have PHP installed on your system to use the JS api.
All methods can take the standard options (camelCase) as the second argument.