sass:meta

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

Mixins permalinkMixins

 meta.load-css($url, $with: null)

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports this mixin.

Loads the module at $url and includes its CSS as though it were written as the contents of this mixin. The $with parameter provides configuration for the modules; if it’s passed, it must be a map from variable names (without $) to the values of those variables to use in the loaded module.

If $url is relative, it’s interpreted as relative to the file in which meta.load-css() is included.

Like the @use rule :

This will only evaluate the given module once, even if it’s loaded multiple times in different ways.
This cannot provide configuration to a module that’s already been loaded, whether or not it was already loaded with configuration.

Unlike the @use rule :

This doesn’t make any members from the loaded module available in the current module.
This can be used anywhere in a stylesheet. It can even be nested within style rules to create nested styles!
The module URL being loaded can come from a variable and include interpolation.

⚠️ Heads up!

The $url parameter should be a string containing a URL like you’d pass to the @use rule. It shouldn’t be a CSS url()!

SCSS Syntax

// dark-theme/_code.scss
$border-contrast: false !default;

code {
 background-color: #6b717f;
 color: #d2e1dd;
 @if $border-contrast {
 border-color: #dadbdf;
 }
}

// style.scss
@use "sass:meta";

body.dark {
 @include meta.load-css("dark-theme/code",
 $with: ("border-contrast": true));
}

Sass Syntax

// dark-theme/_code.sass
$border-contrast: false !default

code
 background-color: #6b717f
 color: #d2e1dd
 @if $border-contrast
 border-color: #dadbdf

// style.sass
@use "sass:meta"

body.dark
 $configuration: ("border-contrast": true)
 @include meta.load-css("dark-theme/code", $with: $configuration)

CSS Output

body.dark code {
 background-color: #6b717f;
 color: #d2e1dd;
 border-color: #dadbdf;
}

Functions permalinkFunctions

 meta.calc-args($calc) //=> list

Dart Sass: since 1.40.0
LibSass: ✗
Ruby Sass: ✗

Returns the arguments for the given calculation.

If an argument is a number or a nested calculation, it’s returned as that type. Otherwise, it’s returned as an unquoted string.

SCSS Syntax

@debug meta.calc-args(calc(100px + 10%)); // unquote("100px + 10%")
@debug meta.calc-args(clamp(50px, var(--width), 1000px)); // 50px, unquote("var(--width)"), 1000px

Sass Syntax

@debug meta.calc-args(calc(100px + 10%)) // unquote("100px + 10%")
@debug meta.calc-args(clamp(50px, var(--width), 1000px)) // 50px, unquote("var(--width)"), 1000px

 meta.calc-name($calc) //=> quoted string

Dart Sass: since 1.40.0
LibSass: ✗
Ruby Sass: ✗

Returns the name of the given calculation.

SCSS Syntax

@debug meta.calc-name(calc(100px + 10%)); // "calc"
@debug meta.calc-name(clamp(50px, var(--width), 1000px)); // "clamp"

Sass Syntax

@debug meta.calc-name(calc(100px + 10%)) // "calc"
@debug meta.calc-name(clamp(50px, var(--width), 1000px)) // "clamp"

 meta.call($function, $args...)
call($function, $args...)

Dart Sass: ✓
LibSass: since 3.5.0
Ruby Sass: since 3.5.0

In older versions of LibSass and Ruby Sass, the call() function took a string representing a function’s name. This was changed to take a function value instead in preparation for a new module system where functions are no longer global and so a given name may not always refer to the same function.

Passing a string to call() still works in all implementations, but it’s deprecated and will be disallowed in future versions.

Invokes $function with $args and returns the result.

The $function should be a function returned by meta.get-function().

SCSS Syntax

@use "sass:list";
@use "sass:meta";
@use "sass:string";

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition) {
 $new-list: ();
 $separator: list.separator($list);
 @each $element in $list {
 @if not meta.call($condition, $element) {
 $new-list: list.append($new-list, $element, $separator: $separator);
 }
 }
 @return $new-list;
}

$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;

content {
 @function contains-helvetica($string) {
 @return string.index($string, "Helvetica");
 }
 font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

Sass Syntax

@use "sass:list"
@use "sass:meta"
@use "sass:string"

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition)
 $new-list: ()
 $separator: list.separator($list)
 @each $element in $list
 @if not meta.call($condition, $element)
 $new-list: list.append($new-list, $element, $separator: $separator)


 @return $new-list


$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif

.content
 @function contains-helvetica($string)
 @return string.index($string, "Helvetica")

 font-family: remove-where($fonts, meta.get-function("contains-helvetica"))

CSS Output

.content {
 font-family: Tahoma, Geneva, Arial, sans-serif;
}

 meta.content-exists()
content-exists() //=> boolean

Returns whether the current mixin was passed a @content block.

Throws an error if called outside of a mixin.

SCSS Syntax

@mixin debug-content-exists {
 @debug meta.content-exists();
 @content;
}

@include debug-content-exists; // false
@include debug-content-exists { // true
 // Content!
}

Sass Syntax

@mixin debug-content-exists
 @debug meta.content-exists()
 @content


@include debug-content-exists // false
@include debug-content-exists // true
 // Content!

 meta.feature-exists($feature)
feature-exists($feature) //=> boolean

Returns whether the current Sass implementation supports $feature.

The $feature must be a string. The currently recognized features are:

global-variable-shadowing, which means that a local variable will shadow a global variable unless it has the !global flag.
extend-selector-pseudoclass, which means that the @extend rule will affect selectors nested in pseudo-classes like :not().
units-level3, which means that unit arithmetic supports units defined in CSS Values and Units Level 3.
at-error, which means that the @error rule is supported.
custom-property, which means that custom property declaration values don’t support any expressions other than interpolation.

Returns false for any unrecognized $feature.

SCSS Syntax

@debug meta.feature-exists("at-error"); // true
@debug meta.feature-exists("unrecognized"); // false

Sass Syntax

@debug meta.feature-exists("at-error") // true
@debug meta.feature-exists("unrecognized") // false

 meta.function-exists($name, $module: null)
function-exists($name) //=> boolean

Returns whether a function named $name is defined, either as a built-in function or a user-defined function.

If $module is passed, this also checks the module named $module for the function definition. $module must be a string matching the namespace of a [@use rule][] in the current file.

SCSS Syntax

@use "sass:math";

@debug meta.function-exists("div", "math"); // true
@debug meta.function-exists("scale-color"); // true
@debug meta.function-exists("add"); // false

@function add($num1, $num2) {
 @return $num1 + $num2;
}
@debug meta.function-exists("add"); // true

Sass Syntax

@use "sass:math"

@debug meta.function-exists("div", "math") // true
@debug meta.function-exists("scale-color") // true
@debug meta.function-exists("add") // false

@function add($num1, $num2)
 @return $num1 + $num2

@debug meta.function-exists("add") // true

 meta.get-function($name, $css: false, $module: null)
get-function($name, $css: false, $module: null) //=> function

Returns the function named $name.

If $module is null, this returns the function named $name without a namespace (including global built-in functions). Otherwise, $module must be a string matching the namespace of a @use rule in the current file, in which case this returns the function in that module named $name.

By default, this throws an error if $name doesn’t refer to Sass function. However, if $css is true, it instead returns a plain CSS function.

The returned function can be called using meta.call().

SCSS Syntax

@use "sass:list";
@use "sass:meta";
@use "sass:string";

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition) {
 $new-list: ();
 $separator: list.separator($list);
 @each $element in $list {
 @if not meta.call($condition, $element) {
 $new-list: list.append($new-list, $element, $separator: $separator);
 }
 }
 @return $new-list;
}

$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;

content {
 @function contains-helvetica($string) {
 @return string.index($string, "Helvetica");
 }
 font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

Sass Syntax

@use "sass:list"
@use "sass:meta"
@use "sass:string"

/// Return a copy of $list with all elements for which $condition returns `true`
/// removed.
@function remove-where($list, $condition)
 $new-list: ()
 $separator: list.separator($list)
 @each $element in $list
 @if not meta.call($condition, $element)
 $new-list: list.append($new-list, $element, $separator: $separator)


 @return $new-list


$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif

.content
 @function contains-helvetica($string)
 @return string.index($string, "Helvetica")

 font-family: remove-where($fonts, meta.get-function("contains-helvetica"))

CSS Output

.content {
 font-family: Tahoma, Geneva, Arial, sans-serif;
}

 meta.global-variable-exists($name, $module: null)
global-variable-exists($name, $module: null) //=> boolean

Returns whether a global variable named $name (without the $) exists.

If $module is null, this returns whether a variable named $name without a namespace exists. Otherwise, $module must be a string matching the namespace of a @use rule in the current file, in which case this returns whether that module has a variable named $name.

SCSS Syntax

@debug meta.global-variable-exists("var1"); // false

$var1: value;
@debug meta.global-variable-exists("var1"); // true

h1 {
 // $var2 is local.
 $var2: value;
 @debug meta.global-variable-exists("var2"); // false
}

Sass Syntax

@debug meta.global-variable-exists("var1") // false

$var1: value
@debug meta.global-variable-exists("var1") // true

h1
 // $var2 is local.
 $var2: value
 @debug meta.global-variable-exists("var2") // false

 meta.inspect($value)
inspect($value) //=> unquoted string

Returns a string representation of $value.

Returns a representation of any Sass value, not just those that can be represented in CSS. As such, its return value is not guaranteed to be valid CSS.

⚠️ Heads up!

This function is intended for debugging; its output format is not guaranteed to be consistent across Sass versions or implementations.

SCSS Syntax

@debug meta.inspect(10px 20px 30px); // unquote("10px 20px 30px")
@debug meta.inspect(("width": 200px)); // unquote('("width": 200px)')
@debug meta.inspect(null); // unquote("null")
@debug meta.inspect("Helvetica"); // unquote('"Helvetica"')

Sass Syntax

@debug meta.inspect(10px 20px 30px) // unquote("10px 20px 30px")
@debug meta.inspect(("width": 200px)) // unquote('("width": 200px)')
@debug meta.inspect(null) // unquote("null")
@debug meta.inspect("Helvetica") // unquote('"Helvetica"')

 meta.keywords($args)
keywords($args) //=> map

Returns the keywords passed to a mixin or function that takes arbitrary arguments. The $args argument must be an argument list.

The keywords are returned as a map from argument names as unquoted strings (not including $) to the values of those arguments.

SCSS Syntax

@use "sass:meta";

@mixin syntax-colors($args...) {
 @debug meta.keywords($args);
 // (string: #080, comment: #800, variable: #60b)

 @each $name, $color in meta.keywords($args) {
 pre span.stx-#{$name} {
 color: $color;
 }
 }
}

@include syntax-colors(
 $string: #080,
 $comment: #800,
 $variable: #60b,
)

Sass Syntax

@use "sass:meta"

@mixin syntax-colors($args...)
 @debug meta.keywords($args)
 // (string: #080, comment: #800, variable: #60b)

 @each $name, $color in meta.keywords($args)
 pre span.stx-#{$name}
 color: $color




@include syntax-colors($string: #080, $comment: #800, $variable: #60b)

CSS Output

pre span.stx-string {
 color: #080;
}

pre span.stx-comment {
 color: #800;
}

pre span.stx-variable {
 color: #60b;
}

 meta.mixin-exists($name, $module: null)
mixin-exists($name, $module: null) //=> boolean

Returns whether a mixin named $name exists.

If $module is null, this returns whether a mixin named $name without a namespace exists. Otherwise, $module must be a string matching the namespace of a @use rule in the current file, in which case this returns whether that module has a mixin named $name.

SCSS Syntax

@debug meta.mixin-exists("shadow-none"); // false

@mixin shadow-none {
 box-shadow: none;
}

@debug meta.mixin-exists("shadow-none"); // true

Sass Syntax

@debug meta.mixin-exists("shadow-none") // false

@mixin shadow-none
 box-shadow: none


@debug meta.mixin-exists("shadow-none") // true

 meta.module-functions($module) //=> map

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports this function.

Returns all the functions defined in a module, as a map from function names to function values.

The $module parameter must be a string matching the namespace of a @use rule in the current file.

SCSS Syntax

// _functions.scss
@function pow($base, $exponent) {
 $result: 1;
 @for $_ from 1 through $exponent {
 $result: $result * $base;
 }
 @return $result;
}

@use "sass:map";
@use "sass:meta";

@use "functions";

@debug meta.module-functions("functions"); // ("pow": get-function("pow"))

@debug meta.call(map.get(meta.module-variables("functions"), "pow"), 3, 4); // 16

Sass Syntax

// _functions.sass
@function pow($base, $exponent)
 $result: 1
 @for $_ from 1 through $exponent
 $result: $result * $base

 @return $result

@use "sass:map"
@use "sass:meta"

@use "functions"

@debug meta.module-functions("functions") // ("pow": get-function("pow"))

@debug meta.call(map.get(meta.module-variables("functions"), "pow"), 3, 4) // 16

 meta.module-variables($module) //=> map

Dart Sass: since 1.23.0
LibSass: ✗
Ruby Sass: ✗

Only Dart Sass currently supports this function.

Returns all the variables defined in a module, as a map from variable names (without $) to the values of those variables.

The $module parameter must be a string matching the namespace of a @use rule in the current file.

SCSS Syntax

// _variables.scss
$hopbush: #c69;
$midnight-blue: #036;
$wafer: #e1d7d2;

@use "sass:meta";

@use "variables";

@debug meta.module-variables("variables");
// (
// "hopbush": #c69,
// "midnight-blue": #036,
// "wafer": #e1d7d2
// )

Sass Syntax

// _variables.sass
$hopbush: #c69
$midnight-blue: #036
$wafer: #e1d7d2

@use "sass:meta"

@use "variables"

@debug meta.module-variables("variables")
// (
// "hopbush": #c69,
// "midnight-blue": #036,
// "wafer": #e1d7d2
// )

 meta.type-of($value)
type-of($value) //=> unquoted string

Returns the type of $value.

This can return the following values:

New possible values may be added in the future. It may return either list or map for (), depending on whether or not it was returned by a map function.

SCSS Syntax

@debug meta.type-of(10px); // number
@debug meta.type-of(10px 20px 30px); // list
@debug meta.type-of(()); // list

Sass Syntax

@debug meta.type-of(10px) // number
@debug meta.type-of(10px 20px 30px) // list
@debug meta.type-of(()) // list

 meta.variable-exists($name)
variable-exists($name) //=> boolean

Returns whether a variable named $name (without the $) exists in the current scope.

SCSS Syntax

@debug meta.variable-exists("var1"); // false

$var1: value;
@debug meta.variable-exists("var1"); // true

h1 {
 // $var2 is local.
 $var2: value;
 @debug meta.variable-exists("var2"); // true
}

Sass Syntax

@debug meta.variable-exists("var1") // false

$var1: value
@debug meta.variable-exists("var1") // true

h1
 // $var2 is local.
 $var2: value
 @debug meta.variable-exists("var2") // true