sass-site/source/documentation/syntax/special-functions.liquid

153 lines
5.1 KiB
Plaintext
Raw Normal View History

2023-05-07 18:58:40 +02:00
---
title: Special Functions
2023-05-25 17:55:08 +02:00
table_of_contents: true
2023-05-07 18:58:40 +02:00
introduction: >
CSS defines many functions, and most of them work just fine with Sasss normal
function syntax. Theyre parsed as function calls, resolved to [plain CSS
2023-06-16 01:45:25 +02:00
functions](/documentation/at-rules/function/#plain-css-functions), and compiled
2023-05-25 17:55:08 +02:00
as-is to CSS. There are a few exceptions, though, which have special syntax
that cant just be parsed as a [SassScript
expression](/documentation/syntax/structure#expressions). All special function
calls return [unquoted strings](/documentation/values/strings#unquoted).
2023-05-07 18:58:40 +02:00
---
2023-05-23 18:24:23 +02:00
2023-05-07 18:58:40 +02:00
{% markdown %}
2023-05-31 18:22:35 +02:00
## `url()`
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
The [`url()` function][] is commonly used in CSS, but its syntax is different
than other functions: it can take either a quoted *or* unquoted URL. Because
an unquoted URL isn't a valid SassScript expression, Sass needs special logic
to parse it.
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[`url()` function]: https://developer.mozilla.org/en-US/docs/Web/CSS/url
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
If the `url()`'s argument is a valid unquoted URL, Sass parses it as-is,
although [interpolation][] may also be used to inject SassScript values. If
it's not a valid unquoted URL—for example, if it contains [variables][] or
[function calls][]—it's parsed as a normal [plain CSS function call][].
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[interpolation]: /documentation/interpolation
[variables]: /documentation/variables
[function calls]: /documentation/at-rules/function
2023-06-16 01:45:25 +02:00
[plain CSS function call]: /documentation/at-rules/function/#plain-css-functions
2023-05-07 18:58:40 +02:00
{% endmarkdown %}
{% codeExample 'url' %}
2023-05-31 18:22:35 +02:00
$roboto-font-path: "../fonts/roboto";
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face {
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2");
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto";
font-weight: 100;
}
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face {
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2");
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto";
font-weight: 300;
}
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face {
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2");
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto";
font-weight: 400;
}
===
$roboto-font-path: "../fonts/roboto"
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face
// This is parsed as a normal function call that takes a quoted string.
src: url("#{$roboto-font-path}/Roboto-Thin.woff2") format("woff2")
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto"
font-weight: 100
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face
// This is parsed as a normal function call that takes an arithmetic
// expression.
src: url($roboto-font-path + "/Roboto-Light.woff2") format("woff2")
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto"
font-weight: 300
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
@font-face
// This is parsed as an interpolated special function.
src: url(#{$roboto-font-path}/Roboto-Regular.woff2) format("woff2")
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
font-family: "Roboto"
font-weight: 400
2023-05-07 18:58:40 +02:00
{% endcodeExample %}
2023-05-31 18:22:35 +02:00
{% markdown %}
## `element()`, `progid:...()`, and `expression()`
2023-05-07 18:58:40 +02:00
2023-06-01 22:56:54 +02:00
{% compatibility 'dart: "<1.40.0"', 'libsass: false', 'ruby: false', 'feature: "calc()"' %}
2023-05-31 18:22:35 +02:00
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.40.0 parse `calc()`
as special syntactic function like `element()`.
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
Dart Sass versions 1.40.0 and later parse `calc()` as a [calculation].
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[calculation]: /documentation/values/calculations
{% endcompatibility %}
2023-05-07 18:58:40 +02:00
2023-06-01 22:56:54 +02:00
{% compatibility 'dart: ">=1.31.0 <1.40.0"', 'libsass: false', 'ruby: false', 'feature: "clamp()"' %}
2023-05-31 18:22:35 +02:00
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.31.0 parse
`clamp()` as a [plain CSS function] rather than supporting special syntax
within it.
2023-05-07 18:58:40 +02:00
2023-06-16 01:45:25 +02:00
[plain CSS function]: /documentation/at-rules/function/#plain-css-functions
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
Dart Sass versions between 1.31.0 and 1.40.0 parse `clamp()` as special
syntactic function like `element()`.
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
Dart Sass versions 1.40.0 and later parse `clamp()` as a [calculation].
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[calculation]: /documentation/values/calculations
{% endcompatibility %}
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
The [`element()`] function is defined in the CSS spec, and because its IDs
could be parsed as colors, they need special parsing.
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[`element()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/element
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[`expression()`][] and functions beginning with [`progid:`][] are legacy
Internet Explorer features that use non-standard syntax. Although they're no
longer supported by recent browsers, Sass continues to parse them for
backwards compatibility.
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
[`expression()`]: https://blogs.msdn.microsoft.com/ie/2008/10/16/ending-expressions/
[`progid:`]: https://blogs.msdn.microsoft.com/ie/2009/02/19/the-css-corner-using-filters-in-ie8/
2023-05-07 18:58:40 +02:00
2023-05-31 18:22:35 +02:00
Sass allows *any text* in these function calls, including nested parentheses.
Nothing is interpreted as a SassScript expression, with the exception that
[interpolation][] can be used to inject dynamic values.
2023-05-23 14:25:18 +02:00
2023-05-31 18:22:35 +02:00
[interpolation]: /documentation/interpolation
2023-05-07 18:58:40 +02:00
{% endmarkdown %}
{% codeExample 'element' %}
2023-05-31 18:22:35 +02:00
$logo-element: logo-bg;
.logo {
background: element(##{$logo-element});
}
===
$logo-element: logo-bg
.logo
background: element(##{$logo-element})
===
.logo {
background: element(#logo-bg);
}
2023-05-07 18:58:40 +02:00
{% endcodeExample %}