Sass Reference - - By Hugo Giraudel

Strings

Strings are an essential part of both Sass and the CSS language. Unlike many programming languages, CSS and Sass do not require strings to be quoted in most circumstances. That means a string can be either quoted or unquoted, and will behave the same way in both cases.

// Any of the two following declarations is okay since
// Sass accepts both unquoted and quoted strings and
// CSS does not require font family names to be quoted.
$font: Helvetica;
$font: 'Helvetica';

.foo {
  font-family: $font;
}

On the other hand, when having a Sass string meant to be used as a CSS identifier, it should not be quoted since CSS requires CSS identifiers to remain unquoted.

// Yep
$fallback-font: sans-serif;

// Yep for Sass, nope for CSS
$fallback-font: 'sans-serif';

.foo {
  font-family: 'Helvetica', $fallback-font;
}

If a string contains special characters, then it should be quoted in order so it does not throw a syntax error.

// Okay
$foo: 'I am a string.';

// Nope because of the full-stop
$bar: I am a string.;

Note that when dealing with an unquoted valid string, it is likely to be treated as a list by Sass since spaces are one of the two allowed item delimiters for lists (the other one being commas).

// This is a string of 13 characters
$foo: 'I am a string';

// This is a list of 4 items and is
// strictly equivalent to `(I, am, a, string)`
$bar: I am a string;

To help you deal with quotes, Sass provides two handy functions: quote and unquote. Both expect a string and return a string, so no type coercion is ever done with one or the other.

$foo: 'I am a string';
$bar: quote($foo); // 'I am a string'
$baz: unquote($foo); // I am a string

$foo: I am a string;
$bar: quote($foo); // Error as `$foo` is a list
$baz: unquote($foo); // I am a string

Interestingly enough, unquoting a list (because an unquoted string is actually a list as mentioned earlier) should throw an error but does not. It simply does nothing. This behavior is likely to be updated in a future version of Sass.

String Concatenation

The plus sign (+) can be used to concatenate several strings into a single one. The result will be a new string made of the associated given parts.

$foo: 'bar' + 'baz'; // 'barbaz'

Members of a string concatenation can be variables as well.

$bar: 'bar';
$foo: $bar + 'baz'; // 'barbaz'

Ultimately, members can also be from different data types, not necessarily strings. When concatenating a string with a value from another type, Sass will attempt to cast the latter into a string.

$foo: 'bar' + 42; // 'bar42'
$foo: 'bar' + true; // 'bartrue'
$foo: 'bar' + (0, 1, 2); // 'bar0, 1, 2'
$foo: 'bar' + red; // 'barred'
$foo: 'bar' + #f00; // 'bar#f00'
$foo: 'bar' + (a: 1, b: 2); // 'bar(a: 1, b: 2)'
$foo: 'bar' + ('a': 1, 'b': 2); // 'bar(\'a\': 1, \'b\': 2)'

Note that the null value cannot be appended to a string. When doing so, Sass will throw an error mentioning how null cannot be part of an operation (in this case, concatenation).

// Invalid
// > `invalid null operation: ""bar" plus null".`
$foo: 'bar' + null;

String Interpolation

Strings can also contain variables. However, extra effort are to be made when wanting to print the content of a variable in a string because as a default Sass will simply display the variable name without trying to fetch its associated content.

$foo: 'world';
$bar: 'Hello $foo!'; // 'Hello $foo!'

The process of asking the interpreter to print the variable content as part of the string is called variable interpolation. In Sass, you have to wrap the variable in #{}, for instance:

$foo: 'world';
$bar: 'Hello #{$foo}!'; // 'Hello world!'

This action can also be useful when wanting to print the content of a variable at some specific places such as within a selector, a @media block context or a property name. Basically, the only place where variables do not have to be interpolated is property values as they are naturally evaluated in there.

String Functions

Since version 3.3, Sass now provides a handful of functions to manipulate strings, the same way we have been able to manipulate lists for years now.

  • str-length: returns the length of a string
  • str-index: returns the position of a substring in a string
  • str-insert: inserts a substring in a string at given index
  • str-slice: returns the portion of a string between two indexes

Unfortunately, there is no native way to replace all occurrences of a string within a string with another string (a.k.a str-replace). Fortunately, this is something perfectly doable as a custom function:

/// Replace `$search` with `$replace` in `$string`
/// @param {String} $string - Initial string
/// @param {String} $search - Substring to replace
/// @param {String} $replace [''] - New value
/// @return {String} - Updated string
@function str-replace($string, $search, $replace: '') {
  $index: str-index($string, $search);

  @if $index {
    @return str-slice($string, 1, $index - 1) + $replace + str-replace(str-slice($string, $index + str-length($search)), $search, $replace);
  }

  @return $string;
}

Note that Sass also provides two functions to help dealing with case:

  • to-upper-case: returns the upper-cased version of input
  • to-lower-case: returns the lower-cased version of input

Engine compatibility

Strings are fully compatible across all Sass engines although LibSass is known to have some bug with nested string concatenations.