adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

Increases or decreases one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and are added to or subtracted from the color’s current value for that property.

All properties are optional. You can’t specify both RGB properties ($red, $green, $blue) and HSL properties ($hue, $saturation, $value) at the same time.

adjust-color(#102030, $blue: 5) => #102035
adjust-color(#102030, $red: -5, $blue: 5) => #0b2035
adjust-color(hsl(25, 100%, 80%), $lightness: -30%, $alpha: -0.4) => hsla(25, 100%, 50%, 0.6)

adjust_hue($color, $degrees)

Changes the hue of a color. Takes a color and a number of degrees (usually between -360deg and 360deg), and returns a color with the hue rotated along the color wheel by that amount.

adjust-hue(hsl(120, 30%, 90%), 60deg) => hsl(180, 30%, 90%)
adjust-hue(hsl(120, 30%, 90%), -60deg) => hsl(60, 30%, 90%)
adjust-hue(#811, 45deg) => #886a11

alpha($color)

Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.

This function also supports the proprietary Microsoft alpha(opacity=20) syntax as a special case.

append($list, $val, $separator:auto)

Appends a single value onto the end of a list.

Unless the $separator argument is passed, if the list had only one item, the resulting list will be space-separated.

Like all list functions, append() returns a new list rather than modifying its argument in place.

append(10px 20px, 30px) => 10px 20px 30px
append((blue, red), green) => blue, red, green
append(10px 20px, 30px 40px) => 10px 20px (30px 40px)
append(10px, 20px, comma) => 10px, 20px
append((blue, red), green, space) => blue red green

blue($color)

Gets the blue component of a color. Calculated from HSL where necessary via this algorithm.

call($name, $args...)

Dynamically calls a function. This can call user-defined functions, built-in functions, or plain CSS functions. It will pass along all arguments, including keyword arguments, to the called function.

call(rgb, 10, 100, 255) => #0a64ff
call(scale-color, #0a64ff, $lightness: -10%) => #0058ef

$fn: nth;
call($fn, (a b c), 2) => b

ceil($number)

Rounds a number up to the next whole number.

ceil(10.4px) => 11px
ceil(10.6px) => 11px

change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

Changes one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and replace the color’s current value for that property.

All properties are optional. You can’t specify both RGB properties ($red, $green, $blue) and HSL properties ($hue, $saturation, $value) at the same time.

change-color(#102030, $blue: 5) => #102005
change-color(#102030, $red: 120, $blue: 5) => #782005
change-color(hsl(25, 100%, 80%), $lightness: 40%, $alpha: 0.8) => hsla(25, 100%, 40%, 0.8)

comparable($number1, $number2)

Returns whether two numbers can added, subtracted, or compared.

comparable(2px, 1px) => true
comparable(100px, 3em) => false
comparable(10cm, 3mm) => true

complement($color)

Returns the complement of a color. This is identical to adjust-hue(color, 180deg).

counter($args...)

This function only exists as a workaround for IE7‘s content: counter bug. It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

counter(item, ".") => counter(item,".")

counters($args...)

This function only exists as a workaround for IE7‘s content: counter bug. It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

counters(item, ".") => counters(item,".")

darken($color, $amount)

Makes a color darker. Takes a color and a number between 0% and 100%, and returns a color with the lightness decreased by that amount.

darken(hsl(25, 100%, 80%), 30%) => hsl(25, 100%, 50%)
darken(#800, 20%) => #200

desaturate($color, $amount)

Makes a color less saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation decreased by that value.

desaturate(hsl(120, 30%, 90%), 20%) => hsl(120, 10%, 90%)
desaturate(#855, 20%) => #726b6b

feature_exists($feature)

Returns whether a feature exists in the current Sass runtime.

The following features are supported:

• global-variable-shadowing indicates that a local variable will shadow a global variable unless !global is used.

• extend-selector-pseudoclass indicates that @extend will reach into selector pseudoclasses like :not.

• units-level-3 indicates full support for unit arithmetic using units defined in the Values and Units Level 3 spec.

• at-error indicates that the Sass @error directive is supported.

feature-exists(some-feature-that-exists) => true
feature-exists(what-is-this-i-dont-know) => false

floor($number)

Rounds a number down to the previous whole number.

floor(10.4px) => 10px
floor(10.6px) => 10px

function_exists($name)

Check whether a function with the given name exists.

function-exists(lighten) => true

@function myfunc { @return "something"; }
function-exists(myfunc) => true

global_variable_exists($name)

Check whether a variable with the given name exists in the global scope (at the top level of the file).

$a-false-value: false;
global-variable-exists(a-false-value) => true

.foo {
  $some-var: false;
  @if global-variable-exists(some-var) { /* false, doesn't run */ }
}

grayscale($color)

Converts a color to grayscale. This is identical to desaturate(color, 100%).

green($color)

Gets the green component of a color. Calculated from HSL where necessary via this algorithm.

hsl($hue, $saturation, $lightness)

Creates a Color from hue, saturation, and lightness values. Uses the algorithm from the CSS3 spec.

hsla($hue, $saturation, $lightness, $alpha)

Creates a Color from hue, saturation, lightness, and alpha values. Uses the algorithm from the CSS3 spec.

hue($color)

Returns the hue component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

ie_hex_str($color)

Converts a color into the format understood by IE filters.

ie-hex-str(#abc) => #FFAABBCC
ie-hex-str(#3322BB) => #FF3322BB
ie-hex-str(rgba(0, 255, 0, 0.5)) => #8000FF00

if($condition, $if-true, $if-false)

Returns one of two values, depending on whether or not $condition is true. Just like in @if, all values other than false and null are considered to be true.

if(true, 1px, 2px) => 1px
if(false, 1px, 2px) => 2px

index($list, $value)

Returns the position of a value within a list. If the value isn’t found, returns null instead.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

This can return the position of a pair in a map as well.

index(1px solid red, solid) => 2
index(1px solid red, dashed) => null
index((width: 10px, height: 20px), (height 20px)) => 2

inspect($value)

Return a string containing the value as its Sass representation.

invert($color)

Returns the inverse (negative) of a color. The red, green, and blue values are inverted, while the opacity is left alone.

is_superselector($super, $sub)

Returns whether $super is a superselector of $sub. This means that $super matches all the elements that $sub matches, as well as possibly additional elements. In general, simpler selectors tend to be superselectors of more complex oned.

is-superselector(".foo", ".foo.bar") => true
is-superselector(".foo.bar", ".foo") => false
is-superselector(".bar", ".foo .bar") => true
is-superselector(".foo .bar", ".bar") => false

join($list1, $list2, $separator:auto)

Joins together two lists into one.

Unless $separator is passed, if one list is comma-separated and one is space-separated, the first parameter’s separator is used for the resulting list. If both lists have fewer than two items, spaces are used for the resulting list.

Like all list functions, join() returns a new list rather than modifying its arguments in place.

join(10px 20px, 30px 40px) => 10px 20px 30px 40px
join((blue, red), (#abc, #def)) => blue, red, #abc, #def
join(10px, 20px) => 10px 20px
join(10px, 20px, comma) => 10px, 20px
join((blue, red), (#abc, #def), space) => blue red #abc #def

keywords($args)

Returns the map of named arguments passed to a function or mixin that takes a variable argument list. The argument names are strings, and they do not contain the leading $.

@mixin foo($args...) {
  @debug keywords($args); //=> (arg1: val, arg2: val)
}

@include foo($arg1: val, $arg2: val);

length($list)

Return the length of a list.

This can return the number of pairs in a map as well.

length(10px) => 1
length(10px 20px 30px) => 3
length((width: 10px, height: 20px)) => 2

lighten($color, $amount)

Makes a color lighter. Takes a color and a number between 0% and 100%, and returns a color with the lightness increased by that amount.

lighten(hsl(0, 0%, 0%), 30%) => hsl(0, 0, 30)
lighten(#800, 20%) => #e00

lightness($color)

Returns the lightness component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

list_separator($list)

Returns the separator of a list. If the list doesn’t have a separator due to having fewer than two elements, returns space.

list-separator(1px 2px 3px) => space
list-separator(1px, 2px, 3px) => comma
list-separator('foo') => space

map_get($map, $key)

Returns the value in a map associated with the given key. If the map doesn’t have such a key, returns null.

map-get(("foo": 1, "bar": 2), "foo") => 1
map-get(("foo": 1, "bar": 2), "bar") => 2
map-get(("foo": 1, "bar": 2), "baz") => null

map_has_key($map, $key)

Returns whether a map has a value associated with a given key.

map-has-key(("foo": 1, "bar": 2), "foo") => true
map-has-key(("foo": 1, "bar": 2), "baz") => false

map_keys($map)

Returns a list of all keys in a map.

map-keys(("foo": 1, "bar": 2)) => "foo", "bar"

map_merge($map1, $map2)

Merges two maps together into a new map. Keys in $map2 will take precedence over keys in $map1.

This is the best way to add new values to a map.

All keys in the returned map that also appear in $map1 will have the same order as in $map1. New keys from $map2 will be placed at the end of the map.

Like all map functions, map-merge() returns a new map rather than modifying its arguments in place.

map-merge(("foo": 1), ("bar": 2)) => ("foo": 1, "bar": 2)
map-merge(("foo": 1, "bar": 2), ("bar": 3)) => ("foo": 1, "bar": 3)

map_remove($map, $keys...)

Returns a new map with keys removed.

Like all map functions, map-merge() returns a new map rather than modifying its arguments in place.

map-remove(("foo": 1, "bar": 2), "bar") => ("foo": 1)
map-remove(("foo": 1, "bar": 2, "baz": 3), "bar", "baz") => ("foo": 1)
map-remove(("foo": 1, "bar": 2), "baz") => ("foo": 1, "bar": 2)

map_values($map)

Returns a list of all values in a map. This list may include duplicate values, if multiple keys have the same value.

map-values(("foo": 1, "bar": 2)) => 1, 2
map-values(("foo": 1, "bar": 2, "baz": 1)) => 1, 2, 1

max($numbers...)

Finds the maximum of several numbers. This function takes any number of arguments.

max(1px, 4px) => 4px
max(5em, 3em, 4em) => 5em

min($numbers...)

Finds the minimum of several numbers. This function takes any number of arguments.

min(1px, 4px) => 1px
min(5em, 3em, 4em) => 3em

mix($color1, $color2, $weight:50%)

Mixes two colors together. Specifically, takes the average of each of the RGB components, optionally weighted by the given percentage. The opacity of the colors is also considered when weighting the components.

The weight specifies the amount of the first color that should be included in the returned color. The default, 50%, means that half the first color and half the second color should be used. 25% means that a quarter of the first color and three quarters of the second color should be used.

mix(#f00, #00f) => #7f007f
mix(#f00, #00f, 25%) => #3f00bf
mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)

mixin_exists($name)

Check whether a mixin with the given name exists.

mixin-exists(nonexistent) => false

@mixin red-text { color: red; }
mixin-exists(red-text) => true

nth($list, $n)

Gets the nth item in a list.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

This can return the nth pair in a map as well.

Negative index values address elements in reverse order, starting with the last element in the list.

nth(10px 20px 30px, 1) => 10px
nth((Helvetica, Arial, sans-serif), 3) => sans-serif
nth((width: 10px, length: 20px), 2) => length, 20px

opacify($color, $amount) Also known as: fade_in

Makes a color more opaque. Takes a color and a number between 0 and 1, and returns a color with the opacity increased by that amount.

opacify(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.6)
opacify(rgba(0, 0, 17, 0.8), 0.2) => #001

opacity($color)

Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.

percentage($number)

Converts a unitless number to a percentage.

percentage(0.2) => 20%
percentage(100px / 50px) => 200%

quote($string)

Add quotes to a string if the string isn’t quoted, or returns the same string if it is.

quote("foo") => "foo"
quote(foo) => "foo"

random random($limit)

red($color)

Gets the red component of a color. Calculated from HSL where necessary via this algorithm.

rgb($red, $green, $blue)

Creates a Color object from red, green, and blue values.

rgba($red, $green, $blue, $alpha) rgba($color, $alpha)

Creates a Color from red, green, blue, and alpha values.

round($number)

Rounds a number to the nearest whole number.

round(10.4px) => 10px
round(10.6px) => 11px

saturate($color, $amount)

Makes a color more saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation increased by that amount.

saturate(hsl(120, 30%, 90%), 20%) => hsl(120, 50%, 90%)
saturate(#855, 20%) => #9e3f3f

saturation($color)

Returns the saturation component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])

Fluidly scales one or more properties of a color. Unlike adjust-color, which changes a color’s properties by fixed amounts, scale-color fluidly changes them based on how high or low they already are. That means that lightening an already-light color with scale-color won’t change the lightness much, but lightening a dark color by the same amount will change it more dramatically. This has the benefit of making scale-color($color, ...) have a similar effect regardless of what $color is.

For example, the lightness of a color can be anywhere between 0% and 100%. If scale-color($color, $lightness: 40%) is called, the resulting color’s lightness will be 40% of the way between its original lightness and 100. If scale-color($color, $lightness: -40%) is called instead, the lightness will be 40% of the way between the original and 0.

This can change the red, green, blue, saturation, value, and alpha properties. The properties are specified as keyword arguments. All arguments should be percentages between 0% and 100%.

All properties are optional. You can’t specify both RGB properties ($red, $green, $blue) and HSL properties ($saturation, $value) at the same time.

scale-color(hsl(120, 70%, 80%), $lightness: 50%) => hsl(120, 70%, 90%)
scale-color(rgb(200, 150%, 170%), $green: -40%, $blue: 70%) => rgb(200, 90, 229)
scale-color(hsl(200, 70%, 80%), $saturation: -90%, $alpha: -30%) => hsla(200, 7%, 80%, 0.7)

selector_append($selectors...)

Return a new selector with all selectors in $selectors appended one another as though they had been nested in the stylesheet as $selector1 { &$selector2 { ... } }.

selector-append(".foo", ".bar", ".baz") => .foo.bar.baz
selector-append(".a .foo", ".b .bar") => "a .foo.b .bar"
selector-append(".foo", "-suffix") => ".foo-suffix"

selector_extend($selector, $extendee, $extender)

Returns a new version of $selector with $extendee extended with $extender. This works just like the result of

$selector { ... }
$extender { @extend $extendee }

selector-extend(".a .b", ".b", ".foo .bar") => .a .b, .a .foo .bar, .foo .a .bar

selector_nest($selectors...)

Return a new selector with all selectors in $selectors nested beneath one another as though they had been nested in the stylesheet as $selector1 { $selector2 { ... } }.

Unlike most selector functions, selector-nest allows the parent selector & to be used in any selector but the first.

selector-nest(".foo", ".bar", ".baz") => .foo .bar .baz
selector-nest(".a .foo", ".b .bar") => .a .foo .b .bar
selector-nest(".foo", "&.bar") => .foo.bar

selector_parse($selector)

Parses a user-provided selector into a list of lists of strings as returned by &.

selector-parse(".foo .bar, .baz .bang") => ('.foo' '.bar', '.baz' '.bang')

selector_replace($selector, $original, $replacement)

Replaces all instances of $original with $replacement in $selector

This works by using @extend and throwing away the original selector. This means that it can be used to do very advanced replacements; see the examples below.

selector-replace(".foo .bar", ".bar", ".baz") => ".foo .baz"
selector-replace(".foo.bar.baz", ".foo.baz", ".qux") => ".bar.qux"

selector_unify($selector1, $selector2)

Unifies two selectors into a single selector that matches only elements matched by both input selectors. Returns null if there is no such selector.

Like the selector unification done for @extend, this doesn’t guarantee that the output selector will match all elements matched by both input selectors. For example, if .a .b is unified with .x .y, .a .x .b.y, .x .a .b.y will be returned, but .a.x .b.y will not. This avoids exponential output size while matching all elements that are likely to exist in practice.

selector-unify(".a", ".b") => .a.b
selector-unify(".a .b", ".x .y") => .a .x .b.y, .x .a .b.y
selector-unify(".a.b", ".b.c") => .a.b.c
selector-unify("#a", "#b") => null

set

Return a new list, based on the list provided, but with the nth element changed to the value given.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

Negative index values address elements in reverse order, starting with the last element in the list.

set-nth($list: 10px 20px 30px, $n: 2, $value: -20px) => 10px -20px 30px

simple_selectors($selector)

Returns the simple selectors that comprise the compound selector $selector.

Note that $selector must be a compound selector. That means it cannot contain commas or spaces. It also means that unlike other selector functions, this takes only strings, not lists.

simple-selectors(".foo.bar") => ".foo", ".bar"
simple-selectors(".foo.bar.baz") => ".foo", ".bar", ".baz"

str_index($string, $substring)

Returns the index of the first occurrence of $substring in $string. If there is no such occurrence, returns null.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

str-index(abcd, a)  => 1
str-index(abcd, ab) => 1
str-index(abcd, X)  => null
str-index(abcd, c)  => 3

str_insert($string, $insert, $index)

Inserts $insert into $string at $index.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

str-insert("abcd", "X", 1) => "Xabcd"
str-insert("abcd", "X", 4) => "abcXd"
str-insert("abcd", "X", 5) => "abcdX"

str_length($string)

Returns the number of characters in a string.

str-length("foo") => 3

str_slice($string, $start-at, $end-at:-1)

Extracts a substring from $string. The substring will begin at index $start-at and ends at index $end-at.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

str-slice("abcd", 2, 3)   => "bc"
str-slice("abcd", 2)      => "bcd"
str-slice("abcd", -3, -2) => "bc"
str-slice("abcd", 2, -2)  => "bc"

to_lower_case($string)

Convert a string to lower case,

to-lower-case(ABCD) => abcd

to_upper_case($string)

Converts a string to upper case.

to-upper-case(abcd) => ABCD

transparentize($color, $amount) Also known as: fade_out

Makes a color more transparent. Takes a color and a number between 0 and 1, and returns a color with the opacity decreased by that amount.

transparentize(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.4)
transparentize(rgba(0, 0, 0, 0.8), 0.2) => rgba(0, 0, 0, 0.6)

type_of($value)

Returns the type of a value.

type-of(100px)  => number
type-of(asdf)   => string
type-of("asdf") => string
type-of(true)   => bool
type-of(#fff)   => color
type-of(blue)   => color

unique_id

Returns a unique CSS identifier. The identifier is returned as an unquoted string. The identifier returned is only guaranteed to be unique within the scope of a single Sass run.

unit($number)

Returns the unit(s) associated with a number. Complex units are sorted in alphabetical order by numerator and denominator.

unit(100) => ""
unit(100px) => "px"
unit(3em) => "em"
unit(10px * 5em) => "em*px"
unit(10px * 5em / 30cm / 1rem) => "em*px/cm*rem"

unitless($number)

Returns whether a number has units.

unitless(100) => true
unitless(100px) => false

unquote($string)

Removes quotes from a string. If the string is already unquoted, this will return it unmodified.

unquote("foo") => foo
unquote(foo) => foo

variable_exists($name)

Check whether a variable with the given name exists in the current scope or in the global scope.

$a-false-value: false;
variable-exists(a-false-value) => true

variable-exists(nonexistent) => false

zip($lists...)

Combines several lists into a single multidimensional list. The nth value of the resulting list is a space separated list of the source lists’ nth values.

The length of the resulting list is the length of the shortest list.

zip(1px 1px 3px, solid dashed solid, red green blue)
=> 1px solid red, 1px dashed green, 3px solid blue