Som en udvidelse til CSS er LESS ikke bare bagudkompatibel med CSS, men de ekstra features det tilføjer bruger eksisterende CSS syntaks. Det gør læring af LESS til en leg, og hvis du bliver i tvivl, lader dig falde tilbage til CSS.

Variabler

Disse er ret selvforklarende:

@nice-blue: #5B83AD;
@light-blue: (@nice-blue + #111);

#header { color: @light-blue; }

Resultat:

#header { color: #6c94be; }

Det er også muligt at definere variabler med et variabelt navn:

@fnord: "I am fnord.";
@var: 'fnord';
content: @@var;

Hvilket kompilerer til:

content: "I am fnord.";

Når du definere en variabel flere gange, er det den seneste definition som bruges, med udgangspunkt i dit aktuelle anvendelsesområde og opad. For eksempel:

@var: 0;
.class1 {
  @var: 1;
  .class {
    @var: 2;
    three: @var;
    @var: 3;
  }
  one: @var;
}

Kompilerer til:

.class1 .class {
  three: 3;
}
.class {
  one: 1;
}

Det minder om CSS, hvor den seneste egenskab i en definition, bruges til at afgøre værdien.

Mixins

I LESS er det muligt at inkludere en række egenskaber fra et regelsæt til et andet. Lad os sige, at vi har den følgende class:

.bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

Og vi ønsker at benytte disse egenskaber inde i andre regelsæt. Godt så, vi skal bare smide navnet class-navnet i det regelsæt, hvor vi ønsker at inkludere dets egenskaber, sådan her:

#menu a {
  color: #111;
  .bordered;
}
.post a {
  color: red;
  .bordered;
}

Egenskaberne for vores .bordered class vil nu optræde i både #menu a og .post a:

#menu a {
  color: #111;
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}
.post a {
  color: red;
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

Ethvert CSS class eller id regelsæt kan blive mixet-ind på den måde.

Bemærk: Variabler bliver også mixet ind, så variabler fra et mixin vil blive placeret i det aktuelle anvendelsesområde. Det er omstridt og vil måske ændre sig i fremtiden.

Parametriske mixins

LESS har en speciel slags regelsæt, der kan mixes ind som en class, men som samtidig accepterer parametre. LESS has a special type of ruleset which can be mixed in like classes, but accepts parameters. Her er det kanoniske eksempel:

.border-radius (@radius) {
  border-radius: @radius;
  -moz-border-radius: @radius;
  -webkit-border-radius: @radius;
}

Og her er hvordan vi kan mixe det ind i forskellige regelsæt:

#header {
  .border-radius(4px);
}
.button {
  .border-radius(6px);
}

Parametriske mixins kan også have standard værdier for deres parametre:

.border-radius (@radius: 5px) {
  border-radius: @radius;
  -moz-border-radius: @radius;
  -webkit-border-radius: @radius;
}

Vi kan nu benytte den sådan her:

#header {
  .border-radius;
}

Og den vil inkludere en 5px border-radius.

Du kan også bruge parametriske mixins som ikke tager parametre. Det er brugbart, hvis du vil skjule regelsættet fra dit stylesheet, men gerne vil inkludere dets egenskaber i andre regelsæt:

.wrap () {
  text-wrap: wrap;
  white-space: pre-wrap;
  white-space: -moz-pre-wrap;
  word-wrap: break-word;
}

pre { .wrap }

Hvilket vil udskrive:

pre {
  text-wrap: wrap;
  white-space: pre-wrap;
  white-space: -moz-pre-wrap;
  word-wrap: break-word;
}

@arguments variablen

@arguments har en speciel betydning inde i mixins. Den indeholder alle argumenterne som blev brugt, da vores mixin blev kaldt. Det er brugbart hvis du ikke gider at håndtere de individuelle parametre:

.box-shadow (@x: 0, @y: 0, @blur: 1px, @color: #000) {
  box-shadow: @arguments;
  -moz-box-shadow: @arguments;
  -webkit-box-shadow: @arguments;
}
.box-shadow(2px, 5px);

Hvilket resulterer i:

  box-shadow: 2px 5px 1px #000;
  -moz-box-shadow: 2px 5px 1px #000;
  -webkit-box-shadow: 2px 5px 1px #000;

Advancerede argumenter og @rest variablen

Du kan bruge ... hvis du vil, at dit mixin skal acceptere et variabelt antal argumenter. Ved at bruge det efter et variabelnavn vil knytte argumenterne til variablen.

.mixin (...) {        // matcher 0-N argumenter
.mixin () {           // matcher præcis 0 argumenter
.mixin (@a: 1) {      // matcher 0-1 argumenter
.mixin (@a: 1, ...) { // matcher 0-N argumenter
.mixin (@a, ...) {    // matcher 1-N argumenter

Endvidere:

.mixin (@a, @rest...) {
   // @rest indeholder argumenter efter @a
   // @arguments indeholder alle argumenter
}

Pattern-matching and Guard expressions

Sometimes, you may want to change the behaviour of a mixin, based on the parameters you pass to it. Let’s start with something basic:

.mixin (@s, @color) { ... }

.class {
  .mixin(@switch, #888);
}

Now let’s say we want .mixin to behave differently, based on the value of @switch, we could define .mixin as such:

.mixin (dark, @color) {
  color: darken(@color, 10%);
}
.mixin (light, @color) {
  color: lighten(@color, 10%);
}
.mixin (@_, @color) {
  display: block;
}

Now, if we run:

@switch: light;

.class {
  .mixin(@switch, #888);
}

We will get the following CSS:

.class {
  color: #a2a2a2;
  display: block;
}

Where the color passed to .mixin was lightened. If the value of @switch was dark, the result would be a darker color.

Here’s what happened:

• The first mixin definition didn’t match because it expected dark as the first argument.
• The second mixin definition matched, because it expected light.
• The third mixin definition matched because it expected any value.

Only mixin definitions which matched were used. Variables match and bind to any value. Anything other than a variable matches only with a value equal to itself.

We can also match on arity, here’s an example:

.mixin (@a) {
  color: @a;
}
.mixin (@a, @b) {
  color: fade(@a, @b);
}

Now if we call .mixin with a single argument, we will get the output of the first definition, but if we call it with two arguments, we will get the second definition, namely @a faded to @b.

Guards

Guards are useful when you want to match on expressions, as opposed to simple values or arity. If you are familiar with functional programming, you have probably encountered them already.

In trying to stay as close as possible to the declarative nature of CSS, LESS has opted to implement conditional execution via guarded mixins instead of if/else statements, in the vein of @media query feature specifications.

Let’s start with an example:

.mixin (@a) when (lightness(@a) >= 50%) {
  background-color: black;
}
.mixin (@a) when (lightness(@a) < 50%) {
  background-color: white;
}
.mixin (@a) {
  color: @a;
}

The key is the when keyword, which introduces a guard sequence (here with only one guard). Now if we run the following code:

.class1 { .mixin(#ddd) }
.class2 { .mixin(#555) }

Here’s what we’ll get:

.class1 {
  background-color: black;
  color: #ddd;
}
.class2 {
  background-color: white;
  color: #555;
}

The full list of comparison operators usable in guards are: > >= = =< <. Additionally, the keyword true is the only truthy value, making these two mixins equivalent:

.truth (@a) when (@a) { ... }
.truth (@a) when (@a = true) { ... }

Any value other than the keyword true is falsy:

.class {
  .truth(40); // Will not match any of the above definitions.
}

Guards can be separated with a comma ‘,’—if any of the guards evaluates to true, it’s considered as a match:

.mixin (@a) when (@a > 10), (@a < -10) { ... }

Note that you can also compare arguments with each other, or with non-arguments:

@media: mobile;

.mixin (@a) when (@media = mobile) { ... }
.mixin (@a) when (@media = desktop) { ... }

.max (@a, @b) when (@a > @b) { width: @a }
.max (@a, @b) when (@a < @b) { width: @b }

Lastly, if you want to match mixins based on value type, you can use the is* functions:

.mixin (@a, @b: 0) when (isnumber(@b)) { ... }
.mixin (@a, @b: black) when (iscolor(@b)) { ... }

Here are the basic type checking functions:

• iscolor
• isnumber
• isstring
• iskeyword
• isurl

If you want to check if a value, in addition to being a number, is in a specific unit, you may use one of:

• ispixel
• ispercentage
• isem

Last but not least, you may use the and keyword to provide additional conditions inside a guard:

.mixin (@a) when (isnumber(@a)) and (@a > 0) { ... }

And the not keyword to negate conditions:

.mixin (@b) when not (@b > 0) { ... }

Indlejrede regler

LESS giver dig mulighed for at bruge indlejring i stedet for, eller i kombination med overlapning. Lad os sige, at vi har det følgende CSS:

#header { color: black; }
#header .navigation {
  font-size: 12px;
}
#header .logo {
  width: 300px;
}
#header .logo:hover {
  text-decoration: none;
}

I LESS kan vi også skrive det sådan her:

#header {
  color: black;

  .navigation {
    font-size: 12px;
  }
  .logo {
    width: 300px;
    &:hover { text-decoration: none }
  }
}

Eller sådan her:

#header        { color: black;
  .navigation  { font-size: 12px }
  .logo        { width: 300px;
    &:hover    { text-decoration: none }
  }
}

Resultatet er mere kortfattet og efterligner strukturen af dit DOM træ.

Bemærk & kombinatoren—den bruges når du ønsker en indlejret selector skal sammenkædes med sin forælder, i stedet for at være nedstammet herfra. Det er specielt vigtigt for pseudo-klasser som :hover og :focus.

For eksempel:

.bordered {
  &.float {
    float: left;
  }
  .top {
    margin: 5px;
  }
}

Vil udskrive

.bordered.float {
  float: left;
}
.bordered .top {
  margin: 5px;
}

Indlejrede media queries

Media queries kan indlejres på samme måde som en selector, fx

.one {
    @media (width: 400px) {
        font-size: 1.2em;
        @media print and color {
            color: blue;
        }           
    }
}

Vil udskrive

@media (width: 400px) {
  .one {
    font-size: 1.2em;
  }
}
@media (width: 400px) and print and color {
  .one {
    color: blue;
  }
}

Advanceret brug af &

& symbolet kan bruges i en selector for at vende indlejringens rækkefølge og gentagelse af klasser.

For eksempel:

.child, .sibling {
    .parent & {
        color: black;
    }
    & + & {
        color: red;
    }
}

Vil udskrive

.parent .child,
.parent .sibling {
    color: black;
}
.child + .child,
.child + .sibling,
.sibling + .child,
.sibling + .sibling {
    color: red;
}

Du kan også bruge & i mixins for at referere indlejring som ligger uden for dit mixin.

Operationer

Der kan udføres operationer på alle tal, farver og variabler. Operationer bør udføres i parenteser. Her er et pat eksempler:

@base: 5%;
@filler: (@base * 2);
@other: (@base + @filler);

color: (#888 / 4);
background-color: (@base-color + #111);
height: (100% / 2 + @filler);

Resultatet er meget som du forventer-LESS forstår forskellen på farver og enheder. Hvis en enhed bruges i en operation, som i:

@var: (1px + 5);

Vil LESS bruge enheden til det endelige resultat-6px i denne situation.

Ekstra parenteser er også tilladt i operationer:

width: ((@var + 5) * 2);

Funktioner

LESS indeholder en række forskellige funktioner som transformerer farver, manipulerer strenge og laver beregninger. De er fuldt ud dokumenteret under funktions reference.

Brugen af dem er ret ligetil. Det følgende eksempel bruger percentage til at konvertere 0.5 til 50%, øger mætningen af en farve med 5% og sætter baggrundsfarven til en farve der er lysnet med 25% og spundet 8 grader:

@base: #f04615;
@width: 0.5;

.class {
  width: percentage(0.5); // returnerer `50%`
  color: saturate(@base, 5%);
  background-color: spin(lighten(@base, 25%), 8);
}

Navnerum

Nogle gange ønsker du måske at gruppere dine variabler og mixins, af organisatoriske formål eller for at åbne en indkapsling. Du kan gøre dette ret intuitivt i LESS-lad os sige, at du vil samle nogle mixins og variabler under #bundle til senere brug eller distribution:

#bundle {
  .button () {
    display: block;
    border: 1px solid black;
    background-color: grey;
    &:hover { background-color: white }
  }
  .tab { ... }
  .citation { ... }
}

Hvis vi nu vil mixe vores .button class ind i #header a, kan vi gøre det sådan:

#header a {
  color: orange;
  #bundle > .button;
}

Anvendelsesområde

Anvendelsesområdet i LESS er meget lig, hvad vi kender fra programmeringssprog. Variabler og mixins bliver først slået op lokalt, og hvis de ikke bliver fundet, så kigger kompilatoren i det overordnede anvendelsesområde, og så videre.

@var: red;

#page {
  @var: white;
  #header {
    color: @var; // white
  }
}

#footer {
  color: @var; // red
}

Kommentarer

CSS-kommentarer bevares af LESS:

/* Hej, jeg er en CSS-kommentar */
.class { color: black }

Enkelt-linje kommentarer er også gyldige i LESS, men de er ‘lydløse’, de bliver ikke udskrevet i det kompilerede CSS:

// Hej, jeg er en lydløs kommentar, jeg dukker ikke op i din CSS
.class { color: white }

Import

You can import both css and less files. Only less files import statements are processed, css file import statements are kept as they are. If you want to import a CSS file, and don’t want LESS to process it, just use the .css extension:

@import "lib.css";

Compilation makes only one change to css file imports: top level css file imports are moved on top of the sheet, right after @charset declarations.

Input file with import statement:

h1 { color: green; }
@import-once "import/official-branding.css?urlParameter=23";

import statement has been moved on top:

@import "import/official-branding.css?urlParameter=23";
h1 { color: green; }

Any file that does not end with .css is considered less file and processed. In addition, if the file name has no extension or parameters, the “.less” suffix is added on the end. Both of these are equivalent:

@import "lib.less";
@import "lib";

Content of imported less file is copied into importing style sheet and compiled together with it. Importing and imported files share all mixins, namespaces, variables and other structures. In addition, if the import statement had media queries, imported content is enclosed in @Media declaration.

Imported “library.less”:

@imported-color: red;
h1 { color: green; }

Main file imports the above library.less file:

@import-multiple "library.less" screen and (max-width: 400px); // import with media queries
@import-multiple "library.less"; // import without media queries

.class {
  color: @importedColor; // use imported variable
}

Compiled output:

// Corresponds to import with media queries
@media screen and (max-width: 400px) {
  h1 { color: green; }
}

// Corresponds to import without media queries
h1 { color: green; }
.class {
  // Use imported variable
  color: #ff0000;
}

Less file import statement does not have to be located on top of the style sheet. It can be placed also inside rulesets, mixins or other less structures.

Import into ruleset:

pre {
  @import "library.less";
  color: @importedColor;
}

both variable and ruleset defined in “library.less” have been copied into the pre ruleset:

pre {
  color: #ff0000; // variable defined in library.less was available
}
pre h1 { // ruleset defined in library.less was nested into 'pre' ruleset
  color: green;
}

Less supports three different @import statements: * @import-once, * @import-multiple – available only for 1.4.0 or higher versions, * @import.

If you want to import a file only if it has not been imported already, use @import-once:

@import-once "lib.less";
@import-once "lib.less"; // will be ignored
@import-once "lib.less" handheld; // will be ignored
pre {
  @import-once "lib.less"; // will be ignored
}

If you want to import a file whether it was already imported or not, use @import-multiple

@import-once "lib.less";
@import-multiple "lib.less"; // will be imported
@import-multiple "lib.less" handheld; // will be imported
pre {
  @import-multiple "lib.less"; // will be imported
}

The statement @import acts differently before and after 1.4.0. It acts as @import-multiple in all older versions and as @import-once in all less.js versions after 1.4.0.

Interpolation med strenge

Variabler kan indlejres inde i strenge, på en måde lignende Ruby eller PHP, med @{name} konstruktionen:

@base-url: "http://assets.fnord.com";
background-image: url("@{base-url}/images/bg.png");

Escaping

Sometimes you might need to output a CSS value which is either not valid CSS syntax, or uses proprietary syntax which LESS doesn’t recognize.

To output such value, we place it inside a string prefixed with ~, for example:

.class {
  filter: ~"ms:alwaysHasItsOwnSyntax.For.Stuff()";
}

This is called an “escaped value”, which will result in:

.class {
  filter: ms:alwaysHasItsOwnSyntax.For.Stuff();
}

Selector Interpolation

Hvis du ønsker at bruge LESS variabler inde i en selector, kan du gøre det ved at referere variablen med @{selector} som i interpolation med strenge. For eksempel:

@name: blocked;
.@{name} {
    color: black;
}

vil udskrive

.blocked {
    color: black;
}

Bemærk: før LESS 1.3.1 var en selector af formen (~"@{name}") understøttet. I version 1.4.0 vil denne understøttelse blive fjernet.

JavaScript evaluering

JavaScript expressions can be evaluated as values inside .less files. We reccomend using caution with this feature as the less will not be compilable by ports and it makes the less harder to mantain. If possible, try to think of a function that can be added to achieve the same purpose and ask for it on github. We have plans to allow expanding the default functions available. However, if you still want to use JavaScript in .less, this is done by wrapping the expression with back-ticks:

@var: `"hello".toUpperCase() + '!'`;

Bliver til:

@var: "HELLO!";

Bemærk at du også kan bruge interpolation og escaping som med strenge:

@str: "hello";
@var: ~`"@{str}".toUpperCase() + '!'`;

Bliver til:

@var: HELLO!;

Det er også muligt at tilgå JavaScript miljøet:

@height: `document.body.clientHeight`;

Hvis du ønsker at fortolke en JavaScript streng som en hex farve, kan du bruge color funktionen:

@color: color(`window.colors.baseColor`);
@darkcolor: darken(@color, 10%);

Index

escape(@string);               // URL encodes a string
e(@string);                    // escape string content
%(@string, values...);         // formats a string

unit(@dimension, [@unit: ""]); // remove or change the unit of a dimension
color(@string);                // parses a string to a color

ceil(@number);                 // rounds up to an integer
floor(@number);                // rounds down to an integer
percentage(@number);           // converts to a %, e.g. 0.5 -> 50%
round(number, [places: 0]);    // rounds a number to a number of places

rgb(@r, @g, @b);                             // converts to a color
rgba(@r, @g, @b, @a);                        // converts to a color
argb(@color);                                // creates a #AARRGGBB
hsl(@hue, @saturation, @lightness);          // creates a color
hsla(@hue, @saturation, @lightness, @alpha); // creates a color
hsv(@hue, @saturation, @value);              // creates a color
hsva(@hue, @saturation, @value, @alpha);     // creates a color

hue(@color);        // returns the `hue` channel of @color
saturation(@color); // returns the `saturation` channel of @color
lightness(@color);  // returns the 'lightness' channel of @color
red(@color);        // returns the 'red' channel of @color
green(@color);      // returns the 'green' channel of @color
blue(@color);       // returns the 'blue' channel of @color
alpha(@color);      // returns the 'alpha' channel of @color
luma(@color);       // returns the 'luma' value (perceptual brightness) of @color

saturate(@color, 10%);                  // return a color 10% points *more* saturated
desaturate(@color, 10%);                // return a color 10% points *less* saturated
lighten(@color, 10%);                   // return a color 10% points *lighter*
darken(@color, 10%);                    // return a color 10% points *darker*
fadein(@color, 10%);                    // return a color 10% points *less* transparent
fadeout(@color, 10%);                   // return a color 10% points *more* transparent
fade(@color, 50%);                      // return @color with 50% transparency
spin(@color, 10);                       // return a color with a 10 degree larger in hue
mix(@color1, @color2, [@weight: 50%]);  // return a mix of @color1 and @color2
greyscale(@color);                      // returns a grey, 100% desaturated color
contrast(@color1, [@darkcolor: black], [@lightcolor: white], [@threshold: 43%]); 
                                        // return @darkcolor if @color1 is > 43% luma  
                                        // otherwise return @lightcolor

multiply(@color1, @color2);
screen(@color1, @color2);
overlay(@color1, @color2);
softlight(@color1, @color2);
hardlight(@color1, @color2);
difference(@color1, @color2);
exclusion(@color1, @color2);
average(@color1, @color2);
negation(@color1, @color2);

String functions

escape

Applies URL-encoding to special characters found in the input string.

• Following characters are exceptions and not encoded: ,, /, ?, @, &, +, ', ~, ! and $.
• Most common encoded characters are: <space>, #, ^, (, ), {, }, |, :, >, <, ;, ], [ and =.

Parameters:

• string: A string to escape

Returns: escaped string content without quotes.

Example:

escape('a=1')

Output:

a%3D1

Note: Function behavior if a parameter is non-string parameters is not defined. Current implementation returns undefined on color and unchanged input on any other kind of argument. This behaviour should not be relied on and can change in the future.

e

CSS escaping similar to ~"value" syntax. It expects string as a parameter and return its content as is, but without quotes. It can be used to output CSS value which is either not valid CSS syntax, or uses proprietary syntax which LESS doesn’t recognize.

Parameters:

• string: A string to escape

Returns: string content without quotes.

Example:

filter: ~"ms:alwaysHasItsOwnSyntax.For.Stuff()";

Output:

filter: ms:alwaysHasItsOwnSyntax.For.Stuff();

Note: The function accepts also ~"" escaped values and numbers as parameters. Anything else returns an error.

% format

The function %("format", arguments ...) formats a string. The first argument is string with placeholders. All placeholders start with percentage symbol % followed by letter s,S,d,D,a, or A. Remaining arguments contain expressions to replace placeholders. If you need to print the percentage symbol, escape it by another percentage %%.

Use uppercase placeholders if you need to escape special characters into their utf-8 escape codes. The function escapes all special characters except ()'~!. Space is encoded as %20. Lowercase placeholders leave special characters as they are.

Placeholders: * d, D, a, A – can be replaced by any kind of argument (color, number, escaped value, expression, …). If you use them in combination with string, the whole string will be used – including its quotes. However, the quotes are placed into the string as they are, they are not escaped by “/” nor anything similar. * s, S – can be replaced by any kind of argument except color. If you use them in combination with string, only the string value will be used – string quotes are omitted.

Parameters:

• string: format string with placeholders,
• anything* : values to replace placeholders.

Returns: formatted string.

Example:

format-a-d: %("repetitions: %a file: %d", 1 + 2, "directory/file.less");
format-a-d-upper: %('repetitions: %A file: %D', 1 + 2, "directory/file.less");
format-s: %("repetitions: %s file: %s", 1 + 2, "directory/file.less");
format-s-upper: %('repetitions: %S file: %S', 1 + 2, "directory/file.less");

Output:

format-a-d: "repetitions: 3 file: "directory/file.less"";
format-a-d-upper: "repetitions: 3 file: %22directory%2Ffile.less%22";
format-s: "repetitions: 3 file: directory/file.less";
format-s-upper: "repetitions: 3 file: directory%2Ffile.less";

Misc functions

color

Parses a color, so a string representing a color becomes a color.

Parameters:

• string: A string of the color

Example:

color("#aaa");

Output:

#aaa

unit

Remove or change the unit of a dimension

Parameters:

• dimension: A number, with or without a dimension
• unit: Optional: the unit to change to, or if omitted it will remove the unit

Example:

unit(5, px)

Output:

5px

Example:

unit(5em)

Output:

5

Math functions

ceil

Rounds up to the next highest integer.

Parameters:

• number: A floating point number.

Returns: integer

Example:

ceil(2.4)

Output:

3

floor

Rounds down to the next lowest integer.

Parameters:

• number: A floating point number.

Returns: integer

Example:

floor(2.6)

Output:

2

percentage

Converts a floating point number into a percentage string.

Parameters:

• number: A floating point number.

Returns: string

Example:

percentage(0.5)

Output:

50%

round

Applies rounding.

Parameters:

• number: A floating point number.
• decimalPlaces: Optional: The number of decimal places to round to. Defaults to 0.

Returns: number

Example:

round(1.67)

Output:

2

Example:

round(1.67, 1)

Output:

1.7

Color functions

Color definition

rgb

Creates an opaque color object from decimal red, green and blue (RGB) values. Literal color values in standard HTML/CSS formats may also be used to define colors, for example #ff0000.

Parameters:

• red: An integer 0-255 or percentage 0-100%.
• green: An integer 0-255 or percentage 0-100%.
• blue: An integer 0-255 or percentage 0-100%.

Returns: color

Example:

rgb(90, 129, 32)

Output:

#5a8120

rgba

Creates a transparent color object from decimal red, green, blue and alpha (RGBA) values.

Parameters:

• red: An integer 0-255 or percentage 0-100%.
• green: An integer 0-255 or percentage 0-100%.
• blue: An integer 0-255 or percentage 0-100%.
• alpha: An number 0-1 or percentage 0-100%.

Returns: color

Example:

rgba(90, 129, 32, 0.5)

Output:

rgba(90, 129, 32, 0.5)

argb

Creates a hex representation of a color in #AARRGGBB format (NOT #RRGGBBAA!).

Parameters:

• color: A color object.

Returns: string

Example:

argb(rgba(90, 23, 148, 0.5));

Output:

#805a1794

hsl

Creates an opaque color object from hue, saturation and lightness (HSL) values.

Parameters:

• hue: An integer 0-360 representing degrees.
• saturation: A percentage 0-100% or number 0-1.
• lightness: A percentage 0-100% or number 0-1.

Returns: color

Example:

hsl(90, 100%, 50%)

Output:

#80ff00

This is useful if you want to create a new color based on another color’s channel, for example:

@new: hsl(hue(@old), 45%, 90%);

@new will have @old’s hue, and its own saturation and lightness.

hsla

Creates a transparent color object from hue, saturation, lightness and alpha (HSLA) values.

Parameters:

• hue: An integer 0-360 representing degrees.
• saturation: A percentage 0-100% or number 0-1.
• lightness: A percentage 0-100% or number 0-1.
• alpha: A percentage 0-100% or number 0-1.

Returns: color

Example:

hsl(90, 100%, 50%, 0.5)

Output:

rgba(128, 255, 0, 0.5)

hsv

Creates an opaque color object from hue, saturation and value (HSV) values. Note that this is not the same as hsl.

Parameters:

• hue: An integer 0-360 representing degrees.
• saturation: A percentage 0-100% or number 0-1.
• value: A percentage 0-100% or number 0-1.

Returns: color

Example:

hsv(90, 100%, 50%)

Output:

#408000

hsva

Creates a transparent color object from hue, saturation, value and alpha (HSVA) values. Note that this is not the same as hsla.

Parameters:

• hue: An integer 0-360 representing degrees.
• saturation: A percentage 0-100% or number 0-1.
• value: A percentage 0-100% or number 0-1.
• alpha: A percentage 0-100% or number 0-1.

Returns: color

Example:

hsva(90, 100%, 50%, 0.5)

Output:

rgba(64, 128, 0, 0.5)

Color channel information

hue

Extracts the hue channel of a color object.

Parameters:

• color: A color object.

Returns: integer 0-360

Example:

hue(hsl(90, 100%, 50%))

Output:

90

saturation

Extracts the saturation channel of a color object.

Parameters:

• color: A color object.

Returns: percentage 0-100

Example:

saturation(hsl(90, 100%, 50%))

Output:

100%

lightness

Extracts the lightness channel of a color object.

Parameters:

• color: A color object.

Returns: percentage 0-100

Example:

lightness(hsl(90, 100%, 50%))

Output:

50%

red

Extracts the red channel of a color object.

Parameters:

• color: A color object.

Returns: integer 0-255

Example:

red(rgb(10, 20, 30))

Output:

10

green

Extracts the green channel of a color object.

Parameters:

• color: A color object.

Returns: integer 0-255

Example:

green(rgb(10, 20, 30))

Output:

20

blue

Extracts the blue channel of a color object.

Parameters:

• color: A color object.

Returns: integer 0-255

Example:

blue(rgb(10, 20, 30))

Output:

30

alpha

Extracts the alpha channel of a color object.

Parameters:

• color: A color object.

Returns: float 0-1

Example:

alpha(rgba(10, 20, 30, 0.5))

Output:

0.5

luma

Calculates the luma) (perceptual brightness) of a color object. Uses SMPTE C / Rec. 709 coefficients, as recommended in WCAG 2.0. This calculation is also used in the contrast function.

Parameters:

• color: A color object.

Returns: percentage 0-100%

Example:

luma(rgb(100, 200, 30))

Output:

65%

Color operations

Color operations generally take parameters in the same units as the values they are changing, and percentage are handled as absolutes, so increasing a 10% value by 10% results in 20%, not 11%, and values are clamped to their allowed ranges; they do not wrap around. Where return values are shown, we’ve also shown formats that make it clear what each function has done, in addition to the hex versions that you will usually be be working with.

saturate

Increase the saturation of a color by an absolute amount.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

saturate(hsl(90, 90%, 50%), 10%)

Output:

#80ff00 // hsl(90, 100%, 50%)

desaturate

Decrease the saturation of a color by an absolute amount.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

desaturate(hsl(90, 90%, 50%), 10%)

Output:

#80e51a // hsl(90, 80%, 50%)

lighten

Increase the lightness of a color by an absolute amount.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

lighten(hsl(90, 90%, 50%), 10%)

Output:

#99f53d // hsl(90, 90%, 60%)

darken

Decrease the lightness of a color by an absolute amount.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

darken(hsl(90, 90%, 50%), 10%)

Output:

#66c20a // hsl(90, 90%, 40%)

fadein

Decrease the transparency (or increase the opacity) of a color, making it more opaque. Has no effect on opaque colours. To fade in the other direction use fadeout.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

fadein(hsla(90, 90%, 50%, 0.5), 10%)

Output:

rgba(128, 242, 13, 0.6) // hsla(90, 90%, 50%, 0.6)

fadeout

Increase the transparency (or decrease the opacity) of a color, making it less opaque. To fade in the other direction use fadein.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

fadeout(hsla(90, 90%, 50%, 0.5), 10%)

Output:

rgba(128, 242, 13, 0.4) // hsla(90, 90%, 50%, 0.6)

fade

Set the absolute transparency of a color. Can be applied to colors whether they already have an opacity value or not.

Parameters:

• color: A color object.
• amount: A percentage 0-100%.

Returns: color

Example:

fade(hsl(90, 90%, 50%), 10%)

Output:

rgba(128, 242, 13, 0.1) //hsla(90, 90%, 50%, 0.1)

spin

Rotate the hue angle of a color in either direction. While the angle range is 0-360, it applies a mod 360 operation, so you can pass in much larger (or negative) values and they will wrap around e.g. angles of 360 and 720 will produce the same result. Note that colours are passed through an RGB conversion, which doesn’t retain hue value for greys (because hue has no meaning when there is no saturation), so make sure you apply functions in a way that preserves hue, for example don’t do this:

@c: saturate(spin(#aaaaaa, 10), 10%);

Do this instead:

@c: spin(saturate(#aaaaaa, 10%), 10);

Colors are always returned as RGB values, so applying spin to a grey value will do nothing.

Parameters:

• color: A color object.
• angle: A number of degrees to rotate (+ or –).

Returns: color

Example:

spin(hsl(10, 90%, 50%), 20)
spin(hsl(10, 90%, 50%), -20)

Output:

#f27f0d // hsl(30, 90%, 50%)
#f20d33 // hsl(350, 90%, 50%)

mix

Mix two colors together in variable proportion. Opacity is included in the calculations.

Parameters:

• color1: A color object.
• color1: A color object.
• weight: Optional, a percentage balance point between the two colors, defaults to 50%.

Returns: color

Example:

mix(#ff0000, #0000ff, 50%)
mix(rgba(100,0,0,1.0), rgba(0,100,0,0.5), 50%)

Output:

#800080
rgba(75, 25, 0, 0.75)

greyscale

Remove all saturation from a color; the same as calling desaturate(@color, 100%). Because the saturation is not affected by hue, the resulting color mapping may be somewhat dull or muddy; luma may provide a better result as it extracts perceptual rather than linear brightness, for example greyscale('#0000ff') will return the same value as greyscale('#00ff00'), though they appear quite different in brightness to the human eye.

Parameters:

• color: A color object.

Returns: color

Example:

greyscale(hsl(90, 90%, 50%))

Output:

#808080 // hsl(90, 0%, 50%)

contrast

Choose which of two colors provides the greatest contrast with another. This is useful for ensuring that a color is readable against a background, which is also useful for accessibility compliance. This function works the same way as the contrast function in Compass for SASS. In accordance with WCAG 2.0, colors are compared using their luma value, not their lightness.

Parameters:

• color: A color object to compare against.
• dark: optional – A designated dark color (defaults to black).
• light: optional – A designated light color (defaults to white).
• threshold: optional – A percentage 0-100% specifying where the transition from “dark” to “light” is (defaults to 43%). This is used to bias the contrast one way or another, for example to allow you to decide whether a 50% grey background should result in black or white text. You would generally set this lower for ‘lighter’ palettes, higher for ‘darker’ ones. Defaults to 43%.

Returns: color

Example:

contrast(#aaaaaa)
contrast(#222222, #101010)
contrast(#222222, #101010, #dddddd)
contrast(hsl(90, 100%, 50%),#000000,#ffffff,40%);
contrast(hsl(90, 100%, 50%),#000000,#ffffff,60%);

Output:

#000000 // black
#ffffff // white
#dddddd
#000000 // black
#ffffff // white

Color blending

These operations are similar as the blend modes found in image editors like Photoshop, Firework or GIMP, so you can use them to make your CSS colors match your images.

multiply

Multiply two colors. For each two colors their RGB channel are multiplied then divided by 255. The result is a darker color.

Parameters:

• color1: A color object to multiply against.
• color2: A color object to multiply against.

Returns: color

Examples:

multiply(#ff6600, #000000);

multiply(#ff6600, #333333);

multiply(#ff6600, #666666);

multiply(#ff6600, #999999);

multiply(#ff6600, #cccccc);

multiply(#ff6600, #ffffff);

multiply(#ff6600, #ff0000);

multiply(#ff6600, #00ff00);

multiply(#ff6600, #0000ff);

screen

Do the opposite effect from multiply. The result is a brighter color.

Parameters:

• color1: A color object to screen against.
• color2: A color object to screen against.

Returns: color

Example:

screen(#ff6600, #000000);

screen(#ff6600, #333333);

screen(#ff6600, #666666);

screen(#ff6600, #999999);

screen(#ff6600, #cccccc);

screen(#ff6600, #ffffff);

screen(#ff6600, #ff0000);

screen(#ff6600, #00ff00);

screen(#ff6600, #0000ff);

overlay

Combines the effect from both multiply and screen. Conditionally make light channels lighter and dark channels darker. Note: The results of the conditions are determined by the first color parameter.

Parameters:

• color1: A color object to overlay another. Also it is the determinant color to make the result lighter or darker.
• color2: A color object to be overlayed.

Returns: color

Example:

overlay(#ff6600, #000000);

overlay(#ff6600, #333333);

overlay(#ff6600, #666666);

overlay(#ff6600, #999999);

overlay(#ff6600, #cccccc);

overlay(#ff6600, #ffffff);

overlay(#ff6600, #ff0000);

overlay(#ff6600, #00ff00);

overlay(#ff6600, #0000ff);

softlight

Similar to overlay but avoid pure black resulting in pure black, and pure white resulting in pure white.

Parameters:

• color1: A color object to soft light another.
• color2: A color object to be soft lighten.

Returns: color

Example:

softlight(#ff6600, #000000);

softlight(#ff6600, #333333);

softlight(#ff6600, #666666);

softlight(#ff6600, #999999);

softlight(#ff6600, #cccccc);

softlight(#ff6600, #ffffff);

softlight(#ff6600, #ff0000);

softlight(#ff6600, #00ff00);

softlight(#ff6600, #0000ff);

hardlight

Similar to overlay but use the second color to detect light and dark channels instead of using the first color.

Parameters:

• color1: A color object to overlay another.
• color2: A color object to be overlayed. Also it is the determinant color to make the result lighter or darker.

Returns: color

Example:

hardlight(#ff6600, #000000);

hardlight(#ff6600, #333333);

hardlight(#ff6600, #666666);

hardlight(#ff6600, #999999);

hardlight(#ff6600, #cccccc);

hardlight(#ff6600, #ffffff);

hardlight(#ff6600, #ff0000);

hardlight(#ff6600, #00ff00);

hardlight(#ff6600, #0000ff);

difference

Substracts the second color from the first color. The operation is made per RGB channels. The result is a darker color.

Parameters:

• color1: A color object to act as the minuend.
• color2: A color object to act as the subtrahend.

Returns: color

Example:

difference(#ff6600, #000000);

difference(#ff6600, #333333);

difference(#ff6600, #666666);

difference(#ff6600, #999999);

difference(#ff6600, #cccccc);

difference(#ff6600, #ffffff);

difference(#ff6600, #ff0000);

difference(#ff6600, #00ff00);

difference(#ff6600, #0000ff);

exclusion

Similar effect to difference with lower contrast.

Parameters:

• color1: A color object to act as the minuend.
• color2: A color object to act as the subtrahend.

Returns: color

Example:

exclusion(#ff6600, #000000);

exclusion(#ff6600, #333333);

exclusion(#ff6600, #666666);

exclusion(#ff6600, #999999);

exclusion(#ff6600, #cccccc);

exclusion(#ff6600, #ffffff);

exclusion(#ff6600, #ff0000);

exclusion(#ff6600, #00ff00);

exclusion(#ff6600, #0000ff);

average

Compute the average of two colors. The operation is made per RGB channels.

Parameters:

• color1: A color object.
• color2: A color object.

Returns: color

Example:

average(#ff6600, #000000);

average(#ff6600, #333333);

average(#ff6600, #666666);

average(#ff6600, #999999);

average(#ff6600, #cccccc);

average(#ff6600, #ffffff);

average(#ff6600, #ff0000);

average(#ff6600, #00ff00);

average(#ff6600, #0000ff);

negation

Do the opposite effect from difference. The result is a brighter color. Note: The opposite effect doesn’t mean the inverted effect as resulting to an addition operation.

Parameters:

• color1: A color object to act as the minuend.
• color2: A color object to act as the subtrahend.

Returns: color

Example:

negation(#ff6600, #000000);

negation(#ff6600, #333333);

negation(#ff6600, #666666);

negation(#ff6600, #999999);

negation(#ff6600, #cccccc);

negation(#ff6600, #ffffff);

negation(#ff6600, #ff0000);

negation(#ff6600, #00ff00);

negation(#ff6600, #0000ff);