sass-site/source/documentation/interpolation.md

154 lines
5.1 KiB
Markdown
Raw Normal View History

2023-05-18 18:03:55 +02:00
---
title: Interpolation
table_of_contents: true
introduction: >
2023-05-25 21:02:28 +02:00
Interpolation can be used almost anywhere in a Sass stylesheet to embed the
result of a [SassScript
expression](/documentation/syntax/structure#expressions) into a chunk of CSS.
Just wrap an expression in `#{}` in any of the following places:
2023-05-18 18:03:55 +02:00
---
2023-05-25 21:02:28 +02:00
2023-06-21 21:20:03 +02:00
* [Selectors in style rules](/documentation/style-rules#interpolation)
* [Property names in declarations](/documentation/style-rules/declarations#interpolation)
* [Custom property values](/documentation/style-rules/declarations#custom-properties)
* [CSS at-rules](/documentation/at-rules/css)
* [`@extend`s](/documentation/at-rules/extend)
* [Plain CSS `@import`s](/documentation/at-rules/import/#plain-css-imports)
* [Quoted or unquoted strings](/documentation/values/strings)
* [Special functions](/documentation/syntax/special-functions)
* [Plain CSS function names](/documentation/at-rules/function/#plain-css-functions)
* [Loud comments](/documentation/syntax/comments)
2023-05-18 18:03:55 +02:00
{% codeExample 'interpolation' %}
2023-05-31 18:31:53 +02:00
@mixin corner-icon($name, $top-or-bottom, $left-or-right) {
.icon-#{$name} {
background-image: url("/icons/#{$name}.svg");
position: absolute;
#{$top-or-bottom}: 0;
#{$left-or-right}: 0;
}
2023-05-18 18:03:55 +02:00
}
2023-05-31 18:31:53 +02:00
@include corner-icon("mail", top, left);
===
@mixin corner-icon($name, $top-or-bottom, $left-or-right)
.icon-#{$name}
background-image: url("/icons/#{$name}.svg")
position: absolute
#{$top-or-bottom}: 0
#{$left-or-right}: 0
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
@include corner-icon("mail", top, left)
2023-05-18 18:03:55 +02:00
{% endcodeExample %}
2023-06-21 21:20:03 +02:00
## In SassScript
2023-05-31 18:31:53 +02:00
2023-06-21 21:20:03 +02:00
{% compatibility 'dart: true', 'libsass: false', 'ruby: "4.0.0 (unreleased)"', 'feature: "Modern Syntax"' %}
LibSass and Ruby Sass currently use an older syntax for parsing
interpolation in SassScript. For most practical purposes it works the same,
but it can behave strangely around [operators][]. See [this document][] for
details.
2023-05-31 18:31:53 +02:00
2023-06-21 21:20:03 +02:00
[operators]: /documentation/operators
[this document]: https://github.com/sass/sass/blob/main/accepted/free-interpolation.md#old-interpolation-rules
{% endcompatibility %}
2023-05-31 18:31:53 +02:00
2023-06-21 21:20:03 +02:00
Interpolation can be used in SassScript to inject SassScript into [unquoted
strings][]. This is particularly useful when dynamically generating names (for
example for animations), or when using [slash-separated values][]. Note that
interpolation in SassScript always returns an unquoted string.
2023-05-31 18:31:53 +02:00
2023-06-21 21:20:03 +02:00
[unquoted strings]: /documentation/values/strings#unquoted
[slash-separated values]: /documentation/operators/numeric#slash-separated-values
2023-05-18 18:03:55 +02:00
{% codeExample 'interpolation-sass-script' %}
2023-05-31 18:31:53 +02:00
@mixin inline-animation($duration) {
$name: inline-#{unique-id()};
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
@keyframes #{$name} {
@content;
}
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
animation-name: $name;
animation-duration: $duration;
animation-iteration-count: infinite;
}
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
.pulse {
@include inline-animation(2s) {
from { background-color: yellow }
to { background-color: red }
}
2023-05-18 18:03:55 +02:00
}
2023-05-31 18:31:53 +02:00
===
@mixin inline-animation($duration)
$name: inline-#{unique-id()}
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
@keyframes #{$name}
@content
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
animation-name: $name
animation-duration: $duration
animation-iteration-count: infinite
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
.pulse
@include inline-animation(2s)
from
background-color: yellow
to
background-color: red
2023-05-18 18:03:55 +02:00
{% endcodeExample %}
{% funFact %}
2023-05-31 18:31:53 +02:00
Interpolation is useful for injecting values into strings, but other than that
it's rarely necessary in SassScript expressions. You definitely *don't* need
it to just use a variable in a property value. Instead of writing `color:
#{$accent}`, you can just write `color: $accent`!
2023-05-18 18:03:55 +02:00
{% endfunFact %}
{% headsUp %}
2023-05-31 18:31:53 +02:00
It's almost always a bad idea to use interpolation with numbers. Interpolation
returns unquoted strings that can't be used for any further math, and it
avoids Sass's built-in safeguards to ensure that units are used correctly.
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
Sass has powerful [unit arithmetic][] that you can use instead. For example,
instead of writing `#{$width}px`, write `$width * 1px`—or better yet, declare
the `$width` variable in terms of `px` to begin with. That way if `$width`
already has units, you'll get a nice error message instead of compiling bogus
CSS.
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
[unit arithmetic]: /documentation/values/numbers#units
2023-05-18 18:03:55 +02:00
{% endheadsUp %}
2023-06-21 21:20:03 +02:00
## Quoted Strings
2023-05-18 18:03:55 +02:00
2023-06-21 21:20:03 +02:00
In most cases, interpolation injects the exact same text that would be used if
the expression were used as a [property value][]. But there is one exception:
the quotation marks around quoted strings are removed (even if those quoted
strings are in lists). This makes it possible to write quoted strings that
contain syntax that's not allowed in SassScript (like selectors) and interpolate
them into style rules.
2023-05-18 18:03:55 +02:00
2023-06-21 21:20:03 +02:00
[property value]: /documentation/style-rules/declarations
2023-05-18 18:03:55 +02:00
{% codeExample 'quoted-strings' %}
2023-05-31 18:31:53 +02:00
.example {
unquoted: #{"string"};
}
===
.example
unquoted: #{"string"}
2023-05-18 18:03:55 +02:00
{% endcodeExample %}
{% headsUp %}
2023-05-31 18:31:53 +02:00
While it's tempting to use this feature to convert quoted strings to unquoted
strings, it's a lot clearer to use the [`string.unquote()` function][].
Instead of `#{$string}`, write `string.unquote($string)`!
2023-05-18 18:03:55 +02:00
2023-05-31 18:31:53 +02:00
[`string.unquote()` function]: /documentation/modules/string#unquote
2023-05-18 18:03:55 +02:00
{% endheadsUp %}