Sass meta.keywords() Function

What You’ll Learn

meta.keywords() belongs to the built-in sass:meta module. It reads the named arguments from an argument list created with $args... and returns them as a map. This page covers argument lists, keyword maps, the official syntax-colors pattern, and five compiled examples.

What Is meta.keywords()?

When a mixin or function accepts $args..., callers can pass a mix of positional values and named keywords like $string: #080. Official docs: meta.keywords($args) returns only those keywords as a map from unquoted name strings (without $) to their values.

📝 Syntax

@use "sass:meta";

// Recommended
meta.keywords($args)

// Legacy global name
keywords($args)

Parameters

Return value

📦 Argument Lists and $args...

You almost always use keywords inside a mixin or function that ends with a rest parameter:

@use "sass:meta";

@mixin demo($args...) {
  // $args is an argument list (not a plain list)
  $named: meta.keywords($args);
  // loop $named with @each ...
}

@include demo($color: teal, $gap: 1rem);

• Positional values remain available on the argument list itself.
• Keyword entries are collected into the map from meta.keywords.
• Map keys never include the $ prefix.

📦 Loading sass:meta

// Recommended — namespaced
@use "sass:meta";
@mixin m($args...) {
  $k: meta.keywords($args);
}

// Optional — bring members into scope
@use "sass:meta" as *;
@mixin m($args...) {
  $k: keywords($args);
}

// Legacy global
@mixin m($args...) {
  $k: keywords($args);
}

🛠 Compatibility

This is about Sass compilers, not browsers. Keyword extraction runs at compile time.

Prefer current Dart Sass with @use "sass:meta".

Examples Gallery

Each example uses meta.keywords on an argument list. Open View Compiled CSS for verified Dart Sass output.

@use "sass:meta";

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

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

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

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

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

@use "sass:meta";

@mixin peek($args...) {
  .peek {
    --keys: #{meta.inspect(meta.keywords($args))};
  }
}

@include peek($a: 1, $b: 2);

.peek {
  --keys: (a: 1, b: 2);
}

@use "sass:meta";

@mixin peek($args...) {
  .peek {
    --keys: #{meta.inspect(meta.keywords($args))};
  }
}

@include peek(1, 2, 3);

.peek {
  --keys: ();
}

@use "sass:meta";

@mixin box($pad, $args...) {
  .box {
    padding: $pad;
    @each $name, $val in meta.keywords($args) {
      #{$name}: $val;
    }
  }
}

@include box(1rem, $color: teal, $border-radius: 8px);

.box {
  padding: 1rem;
  color: teal;
  border-radius: 8px;
}

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

@function has-kw($args...) {
  @return map.has-key(meta.keywords($args), "debug");
}

.flag {
  --debug: #{has-kw($debug: true, $x: 1)};
}

.flag {
  --debug: true;
}

🚀 Real-World Use Cases

• Flexible theme APIs — accept any named tokens without listing every parameter.
• Code generators — official syntax-highlighter color maps.
• Property bags — spread leftover keywords into CSS declarations.
• Optional flags — detect $debug / $verbose with map.has-key.
• Library helpers — separate required positionals from open-ended options.

⚠️ Common Pitfalls

• Passing a plain list/map — $args must be an argument list from $args....
• Looking for $ in keys — keys are bare names like string, not $string.
• Expecting positionals in the map — they stay on the argument list only.
• Interpolating unsafe names — keyword keys used as CSS must be valid identifiers/properties.
• Confusing with CSS keywords — this is about Sass named arguments, not CSS reserved words.

💡 Best Practices