mirror of
https://github.com/danog/sass-site.git
synced 2024-12-15 02:47:36 +01:00
482542ac08
This gives us a place to disambiguate between implementation statuses that refer to the entire feature under discussion, and those that just refer to sub-features.
877 lines
32 KiB
Plaintext
877 lines
32 KiB
Plaintext
---
|
|
title: Color Functions
|
|
---
|
|
|
|
<% function <<SIGNATURE, returns: 'color' do
|
|
adjust-color($color,
|
|
$red: null, $green: null, $blue: null,
|
|
$hue: null, $saturation: null, $lightness: null,
|
|
$alpha: null)
|
|
SIGNATURE
|
|
%>
|
|
Increases or decreases one or more properties of `$color` by fixed amounts.
|
|
|
|
Adds the value passed for each keyword argument to the corresponding property
|
|
of the color, and returns the adjusted color. It's an error to specify an RGB
|
|
property (`$red`, `$green`, and/or `$blue`) at the same time as an HSL
|
|
property (`$hue`, `$saturation`, and/or `$lightness`).
|
|
|
|
All optional arguments must be numbers. The `$red`, `$green`, and `$blue`
|
|
arguments must be [unitless][] and between -255 and 255 (inclusive). The
|
|
`$hue` argument must have either the unit `deg` or no unit. The `$saturation`
|
|
and `$lightness` arguments must be between `-100%` and `100%` (inclusive), and
|
|
may be unitless. The `$alpha` argument must be unitless and between -1 and 1
|
|
(inclusive).
|
|
|
|
[unitless]: ../values/numbers#units
|
|
|
|
See also:
|
|
|
|
* [`scale-color()`](#scale-color) for fluidly scaling a color's properties.
|
|
* [`change-color()`](#change-color) for setting a color's properties.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug adjust-color(#6b717f, $red: 15); // #7a717f
|
|
@debug adjust-color(#d2e1dd, $red: -10, $blue: 10); // #c8e1e7
|
|
@debug adjust-color(#998099, $lightness: -30%, $alpha: -0.4); // rgba(71, 57, 71, 0.6)
|
|
===
|
|
@debug adjust-color(#6b717f, $red: 15) // #7a717f
|
|
@debug adjust-color(#d2e1dd, $red: -10, $blue: 10) // #c8e1e7
|
|
@debug adjust-color(#998099, $lightness: -30%, $alpha: -0.4) // rgba(71, 57, 71, 0.6)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'adjust-hue($color, $degrees)', returns: 'color' do %>
|
|
Increases or decreases `$color`'s hue.
|
|
|
|
The `$hue` must be a number between `-360deg` and `360deg` (inclusive) to add
|
|
to `$color`'s hue. It may be [unitless][].
|
|
|
|
[unitless]: ../values/numbers#units
|
|
|
|
See also [`adjust-color()`](#adjust-color), which can adjust any property of a
|
|
color.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Hue 222deg becomes 282deg.
|
|
@debug adjust-hue(#6b717f, 60deg); // #796b7f
|
|
|
|
// Hue 164deg becomes 104deg.
|
|
@debug adjust-hue(#d2e1dd, -60deg); // #d6e1d2
|
|
|
|
// Hue 210deg becomes 255deg.
|
|
@debug adjust-hue(#036, 45); // #1a0066
|
|
===
|
|
// Hue 222deg becomes 282deg.
|
|
@debug adjust-hue(#6b717f, 60deg) // #796b7f
|
|
|
|
// Hue 164deg becomes 104deg.
|
|
@debug adjust-hue(#d2e1dd, -60deg) // #d6e1d2
|
|
|
|
// Hue 210deg becomes 255deg.
|
|
@debug adjust-hue(#036, 45) // #1a0066
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'alpha($color)', 'opacity($color)', returns: 'number' do %>
|
|
Returns the alpha channel of `$color` as a number between 0 and 1.
|
|
|
|
As a special case, this supports the Internet Explorer syntax
|
|
`alpha(opacity=20)`, for which it returns an [unquoted string][].
|
|
|
|
[unquoted string]: ../values/strings#unquoted
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug alpha(#e1d7d2); // 1
|
|
@debug opacity(rgb(210, 225, 221, 0.4)); // 0.4
|
|
@debug alpha(opacity=20); // alpha(opacity=20)
|
|
===
|
|
@debug alpha(#e1d7d2) // 1
|
|
@debug opacity(rgb(210, 225, 221, 0.4)) // 0.4
|
|
@debug alpha(opacity=20) // alpha(opacity=20)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'blue($color)', returns: 'number' do %>
|
|
Returns the blue channel of `$color` as a number between 0 and 255.
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug blue(#e1d7d2); // 210
|
|
@debug blue(white); // 255
|
|
@debug blue(black); // 0
|
|
===
|
|
@debug blue(#e1d7d2) // 210
|
|
@debug blue(white) // 255
|
|
@debug blue(black) // 0
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function <<SIGNATURE, returns: 'color' do
|
|
change-color($color,
|
|
$red: null, $green: null, $blue: null,
|
|
$hue: null, $saturation: null, $lightness: null,
|
|
$alpha: null)
|
|
SIGNATURE
|
|
%>
|
|
Sets one or more properties of a color to new values.
|
|
|
|
Uses the value passed for each keyword argument in place of the corresponding
|
|
property of the color, and returns the changed color. It's an error to specify
|
|
an RGB property (`$red`, `$green`, and/or `$blue`) at the same time as an HSL
|
|
property (`$hue`, `$saturation`, and/or `$lightness`).
|
|
|
|
All optional arguments must be numbers. The `$red`, `$green`, and `$blue`
|
|
arguments must be [unitless][] and between 0 and 255 (inclusive). The `$hue`
|
|
argument must have either the unit `deg` or no unit. The `$saturation` and
|
|
`$lightness` arguments must be between `0%` and `100%` (inclusive), and may be
|
|
unitless. The `$alpha` argument must be unitless and between -1 and 1
|
|
(inclusive).
|
|
|
|
[unitless]: ../values/numbers#units
|
|
|
|
See also:
|
|
|
|
* [`scale-color()`](#scale-color) for fluidly scaling a color's properties.
|
|
* [`adjust-color()`](#adjust-color) for adjusting a color's properties by fixed
|
|
amounts.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug change-color(#6b717f, $red: 100); // #64717f
|
|
@debug change-color(#d2e1dd, $red: 100, $blue: 50); // #64e132
|
|
@debug change-color(#998099, $lightness: 30%, $alpha: 0.5); // rgba(85, 68, 85, 0.5)
|
|
===
|
|
@debug change-color(#6b717f, $red: 100) // #64717f
|
|
@debug change-color(#d2e1dd, $red: 100, $blue: 50) // #64e132
|
|
@debug change-color(#998099, $lightness: 30%, $alpha: 0.5) // rgba(85, 68, 85, 0.5)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'complement($color)', returns: 'color' do %>
|
|
Returns the RGB [complement][] of `$color`.
|
|
|
|
This is identical to [`adjust-hue($color, 180deg)`](#adjust-hue).
|
|
|
|
[complement]: https://en.wikipedia.org/wiki/Complementary_colors
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Hue 222deg becomes 42deg.
|
|
@debug complement(#6b717f); // #7f796b
|
|
|
|
// Hue 164deg becomes 344deg.
|
|
@debug complement(#d2e1dd); // #e1d2d6
|
|
|
|
// Hue 210deg becomes 30deg.
|
|
@debug complement(#036); // #663300
|
|
===
|
|
// Hue 222deg becomes 42deg.
|
|
@debug complement(#6b717f) // #7f796b
|
|
|
|
// Hue 164deg becomes 344deg.
|
|
@debug complement(#d2e1dd) // #e1d2d6
|
|
|
|
// Hue 210deg becomes 30deg.
|
|
@debug complement(#036) // #663300
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'darken($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` darker.
|
|
|
|
The `$amount` must be a number between `0%` and `100%` (inclusive). Decreases
|
|
the HSL lightness of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `darken()` function decreases lightness by a fixed amount, which is often
|
|
not the desired effect. To make a color a certain percentage darker than it was
|
|
before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// #036 has lightness 20%, so when darken() subtracts 30% it just returns black.
|
|
@debug darken(#036, 30%); // black
|
|
|
|
// scale-color() instead makes it 30% darker than it was originally.
|
|
@debug scale-color(#036, $lightness: -30%); // #002447
|
|
===
|
|
// #036 has lightness 20%, so when darken() subtracts 30% it just returns black.
|
|
@debug darken(#036, 30%) // black
|
|
|
|
// scale-color() instead makes it 30% darker than it was originally.
|
|
@debug scale-color(#036, $lightness: -30%) // #002447
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Lightness 92% becomes 72%.
|
|
@debug darken(#b37399, 20%); // #7c4465
|
|
|
|
// Lightness 85% becomes 45%.
|
|
@debug darken(#f2ece4, 40%); // #b08b5a
|
|
|
|
// Lightness 20% becomes 0%.
|
|
@debug darken(#036, 30%); // black
|
|
===
|
|
// Lightness 92% becomes 72%.
|
|
@debug darken(#b37399, 20%) // #7c4465
|
|
|
|
// Lightness 85% becomes 45%.
|
|
@debug darken(#f2ece4, 40%) // #b08b5a
|
|
|
|
// Lightness 20% becomes 0%.
|
|
@debug darken(#036, 30%) // black
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'desaturate($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` less saturated.
|
|
|
|
The `$amount` must be a number between `0%` and `100%` (inclusive). Decreases
|
|
the HSL saturation of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `desaturate()` function decreases saturation by a fixed amount, which is
|
|
often not the desired effect. To make a color a certain percentage less
|
|
saturated than it was before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// #d2e1dd has saturation 20%, so when desaturate() subtracts 30% it just
|
|
// returns gray.
|
|
@debug desaturate(#d2e1dd, 30%); // #dadada
|
|
|
|
// scale-color() instead makes it 30% less saturated than it was originally.
|
|
@debug scale-color(#6b717f, $saturation: -30%); // #6e727c
|
|
===
|
|
// #6b717f has saturation 20%, so when desaturate() subtracts 30% it just
|
|
// returns gray.
|
|
@debug desaturate(#d2e1dd, 30%) // #dadada
|
|
|
|
// scale-color() instead makes it 30% less saturated than it was originally.
|
|
@debug scale-color(#6b717f, $saturation: -30%) // #6e727c
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Saturation 100% becomes 80%.
|
|
@debug desaturate(#036, 20%); // #0a335c
|
|
|
|
// Saturation 35% becomes 15%.
|
|
@debug desaturate(#f2ece4, 20%); // #eeebe8
|
|
|
|
// Saturation 20% becomes 0%.
|
|
@debug desaturate(#d2e1dd, 30%); // #dadada
|
|
===
|
|
// Saturation 100% becomes 80%.
|
|
@debug desaturate(#036, 20%) // #0a335c
|
|
|
|
// Saturation 35% becomes 15%.
|
|
@debug desaturate(#f2ece4, 20%) // #eeebe8
|
|
|
|
// Saturation 20% becomes 0%.
|
|
@debug desaturate(#d2e1dd, 30%) // #dadada
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'grayscale($color)', returns: 'color' do %>
|
|
Returns a gray color with the same lightness as `$color`.
|
|
|
|
This is identical to [`change-color($color, $saturation: 0%)`](#change-color).
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug grayscale(#6b717f); // #757575
|
|
@debug grayscale(#d2e1dd); // #dadada
|
|
@debug grayscale(#036); // #333333
|
|
===
|
|
@debug grayscale(#6b717f) // #757575
|
|
@debug grayscale(#d2e1dd) // #dadada
|
|
@debug grayscale(#036) // #333333
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'green($color)', returns: 'number' do %>
|
|
Returns the green channel of `$color` as a number between 0 and 255.
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug green(#e1d7d2); // 215
|
|
@debug green(white); // 255
|
|
@debug green(black); // 0
|
|
===
|
|
@debug green(#e1d7d2) // 215
|
|
@debug green(white) // 255
|
|
@debug green(black) // 0
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'hsl($hue $saturation $lightness)',
|
|
'hsl($hue $saturation $lightness / $alpha)',
|
|
'hsl($hue, $saturation, $lightness, $alpha: 1)',
|
|
'hsla($hue $saturation $lightness)',
|
|
'hsla($hue $saturation $lightness / $alpha)',
|
|
'hsla($hue, $saturation, $lightness, $alpha: 1)',
|
|
returns: 'color' do %>
|
|
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
|
|
LibSass and Ruby Sass only support the following signatures:
|
|
|
|
* `hsl($hue, $saturation, $lightness)`
|
|
* `hsla($hue, $saturation, $lightness, $alpha)`
|
|
|
|
Note that for these implementations, the `$alpha` argument is *required* if
|
|
the function name `hsla()` is used, and *forbidden* if the function name
|
|
`hsl()` is used.
|
|
<% end %>
|
|
|
|
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified as
|
|
percentages.
|
|
<% end %>
|
|
|
|
Returns a color with the given [hue, saturation, and lightness][] and the given
|
|
alpha channel.
|
|
|
|
[hue, saturation, and lightness]: https://en.wikipedia.org/wiki/HSL_and_HSV
|
|
|
|
The hue is a number between `0deg` and `360deg` (inclusive). The saturation
|
|
and lightness are numbers between `0%` and `100%` (inclusive). All these
|
|
numbers may be [unitless][]. The alpha channel can be specified as either a
|
|
unitless number between 0 and 1 (inclusive), or a percentage between `0%` and
|
|
`100%` (inclusive).
|
|
|
|
[unitless]: ../values/numbers#units
|
|
|
|
<% fun_fact do %>
|
|
You can pass [special functions][] like `calc()` or `var()` in place of any
|
|
argument to `hsl()`. You can even use `var()` in place of multiple
|
|
arguments, since it might be replaced by multiple values! When a color
|
|
function is called this way, it returns an unquoted string using the same
|
|
signature it was called with.
|
|
|
|
[special functions]: ../syntax/special-functions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug hsl(210deg 100% 20% / var(--opacity)); // hsl(210deg 100% 20% / var(--opacity))
|
|
@debug hsla(var(--peach), 20%); // hsla(var(--peach), 20%)
|
|
===
|
|
@debug hsl(210deg 100% 20% / var(--opacity)) // hsl(210deg 100% 20% / var(--opacity))
|
|
@debug hsla(var(--peach), 20%) // hsla(var(--peach), 20%)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% heads_up do %>
|
|
Sass's [special parsing rules][] for slash-separated values make it
|
|
difficult to pass variables for `$lightness` or `$alpha` when using the
|
|
`hsl($hue $saturation $lightness / $alpha)` signature. Consider using
|
|
`hsl($hue, $saturation, $lightness, $alpha)` instead.
|
|
|
|
[special parsing rules]: ../operators/numeric#slash-separated-values
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug hsl(210deg 100% 20%); // #036
|
|
@debug hsl(34, 35%, 92%); // #f2ece4
|
|
@debug hsl(210deg 100% 20% / 50%); // rgba(0, 51, 102, 0.5)
|
|
@debug hsla(34, 35%, 92%, 0.2); // rgba(242, 236, 228, 0.2)
|
|
===
|
|
@debug hsl(210deg 100% 20%) // #036
|
|
@debug hsl(34, 35%, 92%) // #f2ece4
|
|
@debug hsl(210deg 100% 20% / 50%) // rgba(0, 51, 102, 0.5)
|
|
@debug hsla(34, 35%, 92%, 0.2) // rgba(242, 236, 228, 0.2)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'hue($color)', returns: 'number' do %>
|
|
Returns the hue of `$color` as a number between `0deg` and `255deg`.
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug hue(#e1d7d2); // 20deg
|
|
@debug hue(#f2ece4); // 34.2857142857deg
|
|
@debug hue(#dadbdf); // 228deg
|
|
===
|
|
@debug hue(#e1d7d2) // 20deg
|
|
@debug hue(#f2ece4) // 34.2857142857deg
|
|
@debug hue(#dadbdf) // 228deg
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'ie-hex-str($color)', returns: 'unquoted string' do %>
|
|
Returns an unquoted string that represents `$color` in the `#AARRGGBB` format
|
|
expected by Internet Explorer's [`-ms-filter`][] property.
|
|
|
|
[`-ms-filter`]: https://developer.mozilla.org/en-US/docs/Web/CSS/-ms-filter
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug ie-hex-str(#b37399); // #FFB37399
|
|
@debug ie-hex-str(#808c99); // #FF808C99
|
|
@debug ie-hex-str(rgba(242, 236, 228, 0.6)); // #99F2ECE4
|
|
===
|
|
@debug ie-hex-str(#b37399); // #FFB37399
|
|
@debug ie-hex-str(#808c99); // #FF808C99
|
|
@debug ie-hex-str(rgba(242, 236, 228, 0.6)); // #99F2ECE4
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'invert($color, $weight: 100%)', returns: 'color' do %>
|
|
Returns the inverse or [negative][] of `$color`.
|
|
|
|
[negative]: https://en.wikipedia.org/wiki/Negative_(photography)
|
|
|
|
The `$weight` must be a number between `0%` and `100%` (inclusive). A higher
|
|
weight means the result will be closer to the negative, and a lower weight means
|
|
it will be closer to `$color`. Weight `50%` will always produce `#808080`.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug invert(#b37399); // #4c8c66
|
|
@debug invert(black); // white
|
|
@debug invert(#550e0c, 20%); // #663b3a
|
|
===
|
|
@debug invert(#b37399) // #4c8c66
|
|
@debug invert(black) // white
|
|
@debug invert(#550e0c, 20%) // #663b3a
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'lighten($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` lighter.
|
|
|
|
The `$amount` must be a number between `0%` and `100%` (inclusive). Increases
|
|
the HSL lightness of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `lighten()` function increases lightness by a fixed amount, which is often
|
|
not the desired effect. To make a color a certain percentage lighter than it was
|
|
before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// #e1d7d2 has lightness 85%, so when lighten() adds 30% it just returns white.
|
|
@debug lighten(#e1d7d2, 30%); // white
|
|
|
|
// scale-color() instead makes it 30% lighter than it was originally.
|
|
@debug scale-color(#e1d7d2, $lightness: 30%); // #eae3e0
|
|
===
|
|
// #e1d7d2 has lightness 85%, so when lighten() adds 30% it just returns white.
|
|
@debug lighten(#e1d7d2, 30%) // white
|
|
|
|
// scale-color() instead makes it 30% lighter than it was originally.
|
|
@debug scale-color(#e1d7d2, $lightness: 30%) // #eae3e0
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Lightness 46% becomes 66%.
|
|
@debug lighten(#6b717f, 20%); // #a1a5af
|
|
|
|
// Lightness 20% becomes 80%.
|
|
@debug lighten(#036, 60%); // #99ccff
|
|
|
|
// Lightness 85% becomes 100%.
|
|
@debug lighten(#e1d7d2, 30%); // white
|
|
===
|
|
// Lightness 46% becomes 66%.
|
|
@debug lighten(#6b717f, 20%) // #a1a5af
|
|
|
|
// Lightness 20% becomes 80%.
|
|
@debug lighten(#036, 60%) // #99ccff
|
|
|
|
// Lightness 85% becomes 100%.
|
|
@debug lighten(#e1d7d2, 30%) // white
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'lightness($color)', returns: 'number' do %>
|
|
Returns the HSL lightness of `$color` as a number between `0%` and `100%`.
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug lightness(#e1d7d2); // 85.2941176471%
|
|
@debug lightness(#f2ece4); // 92.1568627451%
|
|
@debug lightness(#dadbdf); // 86.4705882353%
|
|
===
|
|
@debug lightness(#e1d7d2) // 85.2941176471%
|
|
@debug lightness(#f2ece4) // 92.1568627451%
|
|
@debug lightness(#dadbdf) // 86.4705882353%
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'mix($color1, $color2, $weight: 50%)', returns: 'color' do %>
|
|
Returns a number that's a mixture of `$color1` and `$color2`.
|
|
|
|
Both the `$weight` and the relative opacity of each color determines how much of
|
|
each color is in the result. The `$weight` must be a number between `0%` and
|
|
`100%` (inclusive). A larger weight indicates that more of `$color1` should be
|
|
used, and a smaller weight indicates that more of `$color2` should be used.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug mix(#036, #d2e1dd); // #698aa2
|
|
@debug mix(#036, #d2e1dd, 75%); // #355f84
|
|
@debug mix(#036, #d2e1dd, 25%); // #9eb6bf
|
|
@debug mix(rgba(242, 236, 228, 0.5), #6b717f); // rgba(141, 144, 152, 0.75)
|
|
===
|
|
@debug mix(#036, #d2e1dd) // #698aa2
|
|
@debug mix(#036, #d2e1dd, 75%) // #355f84
|
|
@debug mix(#036, #d2e1dd, 25%) // #9eb6bf
|
|
@debug mix(rgba(242, 236, 228, 0.5), #6b717f) // rgba(141, 144, 152, 0.75)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'opacify($color, $amount)', 'fade-in($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` more opaque.
|
|
|
|
The `$amount` must be a number between `0` and `1` (inclusive). Increases the
|
|
alpha channel of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `opacify()` function increases the alpha channel by a fixed amount, which is often
|
|
not the desired effect. To make a color a certain percentage more opaque than it was
|
|
before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// rgba(#036, 0.7) has alpha 0.7, so when opacify() adds 0.3 it returns a fully
|
|
// opaque color.
|
|
@debug opacify(rgba(#036, 0.7), 0.3); // #036
|
|
|
|
// scale-color() instead makes it 30% more opaque than it was originally.
|
|
@debug scale-color(rgba(#036, 0.7), $alpha: 30%); // rgba(0, 51, 102, 0.79)
|
|
===
|
|
// rgba(#036, 0.7) has alpha 0.7, so when opacify() adds 0.3 it returns a fully
|
|
// opaque color.
|
|
@debug opacify(rgba(#036, 0.7), 0.3) // #036
|
|
|
|
// scale-color() instead makes it 30% more opaque than it was originally.
|
|
@debug scale-color(rgba(#036, 0.7), $alpha: 30%) // rgba(0, 51, 102, 0.79)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug opacify(rgba(#6b717f, 0.5), 0.2); // rgba(107, 113, 127, 0.7)
|
|
@debug fade-in(rgba(#e1d7d2, 0.5), 0.4); // rgba(225, 215, 210, 0.9)
|
|
@debug opacify(rgba(#036, 0.7), 0.3); // #036
|
|
===
|
|
@debug opacify(rgba(#6b717f, 0.5), 0.2) // rgba(107, 113, 127, 0.7)
|
|
@debug fade-in(rgba(#e1d7d2, 0.5), 0.4) // rgba(225, 215, 210, 0.9)
|
|
@debug opacify(rgba(#036, 0.7), 0.3) // #036
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'red($color)', returns: 'number' do %>
|
|
Returns the red channel of `$color` as a number between 0 and 255.
|
|
|
|
See also:
|
|
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`saturation()`](#saturation) for getting a color's saturation.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug red(#e1d7d2); // 225
|
|
@debug red(white); // 255
|
|
@debug red(black); // 0
|
|
===
|
|
@debug red(#e1d7d2) // 225
|
|
@debug red(white) // 255
|
|
@debug red(black) // 0
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'rgb($red $green $blue)',
|
|
'rgb($red $green $blue / $alpha)',
|
|
'rgb($red, $green, $blue, $alpha: 1)',
|
|
'rgb($color, $alpha)',
|
|
'rgba($red $green $blue)',
|
|
'rgba($red $green $blue / $alpha)',
|
|
'rgba($red, $green, $blue, $alpha: 1)',
|
|
'rgba($color, $alpha)',
|
|
returns: 'color' do %>
|
|
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
|
|
LibSass and Ruby Sass only support the following signatures:
|
|
|
|
* `rgb($red, $green, $blue)`
|
|
* `rgba($red, $green, $blue, $alpha)`
|
|
* `rgba($color, $alpha)`
|
|
|
|
Note that for these implementations, the `$alpha` argument is *required* if
|
|
the function name `rgba()` is used, and *forbidden* if the function name
|
|
`rgb()` is used.
|
|
<% end %>
|
|
|
|
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified
|
|
as percentages.
|
|
<% end %>
|
|
|
|
If `$red`, `$green`, `$blue`, and optionally `$alpha` are passed, returns a
|
|
color with the given red, green, blue, and alpha channels.
|
|
|
|
Each channel can be specified as either a [unitless][] number between 0 and
|
|
255 (inclusive), or a percentage between `0%` and `100%` (inclusive). The
|
|
alpha channel can be specified as either a unitless number between 0 and 1
|
|
(inclusive), or a percentage between `0%` and `100%` (inclusive).
|
|
|
|
[unitless]: ../values/numbers#units
|
|
|
|
<% fun_fact do %>
|
|
You can pass [special functions][] like `calc()` or `var()` in place of any
|
|
argument to `rgb()`. You can even use `var()` in place of multiple
|
|
arguments, since it might be replaced by multiple values! When a color
|
|
function is called this way, it returns an unquoted string using the same
|
|
signature it was called with.
|
|
|
|
[special functions]: ../syntax/special-functions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug rgb(0 51 102 / var(--opacity)); // rgb(0 51 102 / var(--opacity))
|
|
@debug rgba(var(--peach), 0.2); // rgba(var(--peach), 0.2)
|
|
===
|
|
@debug rgb(0 51 102 / var(--opacity)) // rgb(0 51 102 / var(--opacity))
|
|
@debug rgba(var(--peach), 0.2) // rgba(var(--peach), 0.2)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% heads_up do %>
|
|
Sass's [special parsing rules][] for slash-separated values make it
|
|
difficult to pass variables for `$blue` or `$alpha` when using the
|
|
`rgb($red $green $blue / $alpha)` signature. Consider using
|
|
`hsl($red, $green, $blue, $alpha)` instead.
|
|
|
|
[special parsing rules]: ../operators/numeric#slash-separated-values
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug rgb(0 51 102); // #036
|
|
@debug rgb(95%, 92.5%, 89.5%); // #f2ece4
|
|
@debug rgb(0 51 102 / 50%); // rgba(0, 51, 102, 0.5)
|
|
@debug rgba(95%, 92.5%, 89.5%, 0.2); // rgba(242, 236, 228, 0.2)
|
|
===
|
|
@debug rgb(0 51 102) // #036
|
|
@debug rgb(95%, 92.5%, 89.5%) // #f2ece4
|
|
@debug rgb(0 51 102 / 50%) // rgba(0, 51, 102, 0.5)
|
|
@debug rgba(95%, 92.5%, 89.5%, 0.2) // rgba(242, 236, 228, 0.2)
|
|
<% end %>
|
|
|
|
---
|
|
|
|
If `$color` and `$alpha` are passed, this returns `$color` with the given
|
|
`$alpha` channel instead of its original alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug rgb(#f2ece4, 50%); // rgba(242, 236, 228, 0.5);
|
|
@debug rgba(rgba(0, 51, 102, 0.5), 1); // #003366
|
|
===
|
|
@debug rgb(#f2ece4, 50%) // rgba(242, 236, 228, 0.5)
|
|
@debug rgba(rgba(0, 51, 102, 0.5), 1) // #003366
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'saturate($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` more saturated.
|
|
|
|
The `$amount` must be a number between `0%` and `100%` (inclusive). Increases
|
|
the HSL saturation of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `saturate()` function increases saturation by a fixed amount, which is often
|
|
not the desired effect. To make a color a certain percentage more saturated than
|
|
it was before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// #0e4982 has saturation 80%, so when saturate() adds 30% it just becomes
|
|
// fully saturated.
|
|
@debug saturate(#0e4982, 30%); // #004990
|
|
|
|
// scale-color() instead makes it 30% more saturated than it was originally.
|
|
@debug scale-color(#0e4982, $saturation: 30%); // #0a4986
|
|
===
|
|
// #0e4982 has saturation 80%, so when saturate() adds 30% it just becomes
|
|
// fully saturated.
|
|
@debug saturate(#0e4982, 30%) // #004990
|
|
|
|
// scale-color() instead makes it 30% more saturated than it was originally.
|
|
@debug scale-color(#0e4982, $saturation: 30%) // #0a4986
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// Saturation 50% becomes 70%.
|
|
@debug saturate(#c69, 20%); // #e05299
|
|
|
|
// Saturation 35% becomes 85%.
|
|
@debug desaturate(#f2ece4, 50%); // #ebebeb
|
|
|
|
// Saturation 80% becomes 100%.
|
|
@debug saturate(#0e4982, 30%) // #004990
|
|
===
|
|
// Saturation 50% becomes 70%.
|
|
@debug saturate(#c69, 20%); // #e05299
|
|
|
|
// Saturation 35% becomes 85%.
|
|
@debug desaturate(#f2ece4, 50%); // #ebebeb
|
|
|
|
// Saturation 80% becomes 100%.
|
|
@debug saturate(#0e4982, 30%) // #004990
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'saturation($color)', returns: 'number' do %>
|
|
Returns the HSL saturation of `$color` as a number between `0%` and `100%`.
|
|
|
|
See also:
|
|
|
|
* [`red()`](#red) for getting a color's red channel.
|
|
* [`green()`](#green) for getting a color's green channel.
|
|
* [`blue()`](#blue) for getting a color's blue channel.
|
|
* [`hue()`](#hue) for getting a color's hue.
|
|
* [`lightness()`](#lightness) for getting a color's lightness.
|
|
* [`alpha()`](#alpha) for getting a color's alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug saturation(#e1d7d2); // 20%
|
|
@debug saturation(#f2ece4); // 30%
|
|
@debug saturation(#dadbdf); // 7.2463768116%
|
|
===
|
|
@debug saturation(#e1d7d2) // 20%
|
|
@debug saturation(#f2ece4) // 30%
|
|
@debug saturation(#dadbdf) // 7.2463768116%
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function <<SIGNATURE, returns: 'color' do
|
|
scale-color($color,
|
|
$red: null, $green: null, $blue: null,
|
|
$saturation: null, $lightness: null,
|
|
$alpha: null)
|
|
SIGNATURE
|
|
%>
|
|
Fluidly scales one or more properties of `$color`.
|
|
|
|
Each keyword argument must be a number between `-100%` and `100%` (inclusive).
|
|
This indicates how far the corresponding property should be moved from its
|
|
original position towards the maximum (if the argument is positive) or the
|
|
minimum (if the argument is negative). This means that, for example,
|
|
`$lightness: 50%` will make all colors `50%` closer to maximum lightness
|
|
without making them fully white.
|
|
|
|
It's an error to specify an RGB property (`$red`, `$green`, and/or `$blue`) at
|
|
the same time as an HSL property (`$saturation`, and/or `$lightness`).
|
|
|
|
See also:
|
|
|
|
* [`adjust-color()`](#adjust-color) for changing a color's properties by fixed
|
|
amounts.
|
|
* [`change-color()`](#change-color) for setting a color's properties.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug scale-color(#6b717f, $red: 15%); // #81717f
|
|
@debug scale-color(#d2e1dd, $lightness: -10%, $saturation: 10%); // #b3d4cb
|
|
@debug scale-color(#998099, $alpha: -40%); // rgba(153, 128, 153, 0.6)
|
|
===
|
|
@debug scale-color(#6b717f, $red: 15%) // #81717f
|
|
@debug scale-color(#d2e1dd, $lightness: -10%, $saturation: 10%) // #b3d4cb
|
|
@debug scale-color(#998099, $alpha: -40%) // rgba(153, 128, 153, 0.6)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'transparentize($color, $amount)', 'fade-out($color, $amount)', returns: 'color' do %>
|
|
Makes `$color` more transparent.
|
|
|
|
The `$amount` must be a number between `0` and `1` (inclusive). Decreases the
|
|
alpha channel of `$color` by that amount.
|
|
|
|
<% heads_up do %>
|
|
The `transparentize()` function decreases the alpha channel by a fixed amount,
|
|
which is often not the desired effect. To make a color a certain percentage more
|
|
transparent than it was before, use [`scale-color()`](#scale-color) instead.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
// rgba(#036, 0.3) has alpha 0.3, so when transparentize() subtracts 0.3 it
|
|
// returns a fully transparent color.
|
|
@debug transparentize(rgba(#036, 0.3), 0.3); // rgba(0, 51, 102, 0)
|
|
|
|
// scale-color() instead makes it 30% more transparent than it was originally.
|
|
@debug scale-color(rgba(#036, 0.3), $alpha: -30%); // rgba(0, 51, 102, 0.21)
|
|
===
|
|
// rgba(#036, 0.3) has alpha 0.3, so when transparentize() subtracts 0.3 it
|
|
// returns a fully transparent color.
|
|
@debug transparentize(rgba(#036, 0.3), 0.3) // rgba(0, 51, 102, 0)
|
|
|
|
// scale-color() instead makes it 30% more transparent than it was originally.
|
|
@debug scale-color(rgba(#036, 0.3), $alpha: -30%) // rgba(0, 51, 102, 0.21)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug transparentize(rgba(#6b717f, 0.5), 0.2) // rgba(107, 113, 127, 0.3)
|
|
@debug fade-out(rgba(#e1d7d2, 0.5), 0.4) // rgba(225, 215, 210, 0.1)
|
|
@debug transparentize(rgba(#036, 0.3), 0.3) // rgba(0, 51, 102, 0)
|
|
===
|
|
@debug transparentize(rgba(#6b717f, 0.5), 0.2) // rgba(107, 113, 127, 0.3)
|
|
@debug fade-out(rgba(#e1d7d2, 0.5), 0.4) // rgba(225, 215, 210, 0.1)
|
|
@debug transparentize(rgba(#036, 0.3), 0.3) // rgba(0, 51, 102, 0)
|
|
<% end %>
|
|
<% end %>
|