Sass meta.keywords()

Intermediate
8 min read
Updated: Nov 2026
5 examples
Dart Sass
Sass meta.keywords extracting named arguments from an argument list
Definition

Definition and Usage

meta.keywords($args) returns a map of the keyword (named) arguments passed to a mixin or function that takes arbitrary arguments. $args must be an argument list. Load it with @use "sass:meta".

Official sample idea.

A syntax-colors($args...) mixin loops meta.keywords($args) to emit pre span.stx-#{$name} rules from named colors like $string: #080.

Map keys omit $.

Official docs: keys are unquoted strings of argument names without $. So $comment: #800 becomes key comment.

Argument list only.

Pass the rest parameter from $args.... A normal list or map is not the same type and will error.

Syntax

Syntax

SCSS
@use "sass:meta";

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

@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
);

// Global alias (legacy): keywords($args)
// Prefer meta.keywords after @use "sass:meta"

Pattern: capture $args... → meta.keywords($args) → @each over the map (or inspect / map.has-key).

Reference

Keywords vs Positionals

What ends up in the map:

Passed asIn meta.keywords?Example
Named keywordYes — map entry$string: #080 → string: #080
Positional onlyNopeek(1, 2, 3) → empty map ()
Fixed param + keywordsOnly the leftover namesbox(1rem, $color: teal)
Ordinary list / mapErrorMust be an argument list
Debug the map shape.

Pair with meta.inspect while learning, or @debug meta.keywords($args) in real projects.

Code

SCSS Examples

Examples use @use "sass:meta". Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).

Example 1 — Official Docs syntax-colors

Turn named color keywords into generated selectors.

SCSS
@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
);

How It Works

  1. $args... captures the named colors.
  2. keywords builds (string: #080, …).
  3. @each walks each name/value pair.
  4. Matches the official Sass docs CSS output.

Example 2 — Peek at the Keywords Map

Use meta.inspect to see the map shape while learning.

SCSS
@use "sass:meta";

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

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

How It Works

  1. Named args become map entries.
  2. Keys omit the $ (a, b).
  3. inspect shows the map as text.
  4. Prefer @debug in real projects.

Example 3 — No Keywords → Empty Map

Positional-only calls still work; the keyword map is empty.

SCSS
@use "sass:meta";

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

@include peek(1, 2, 3);

How It Works

  1. 1, 2, 3 are positional only.
  2. keywords returns an empty map ().
  3. Positionals stay on the argument list itself.
  4. Named-only APIs can still accept leftovers safely.

Example 4 — Fixed Arg + Keyword Bag

Keep a required positional parameter, then spread extra named styles.

SCSS
@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);

How It Works

  1. $pad is handled as a normal parameter.
  2. Leftover names land in $args....
  3. keywords + @each emit CSS declarations.
  4. Flexible property-bag style APIs.

Example 5 — Detect an Optional Keyword Flag

Combine meta.keywords with map.has-key.

SCSS
@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)};
}

How It Works

  1. $debug becomes key debug.
  2. map.has-key checks for that optional flag.
  3. Other keywords ($x) do not matter here.
  4. Useful for optional feature switches in flexible APIs.

Edge Cases & Pitfalls

Most keywords bugs are wrong input types or expecting positionals in the map.

type

Must be an argument list

Pass $args from $args..., not a handwritten list or map.

keys

Keys omit the dollar sign

Look up "debug", not "$debug", with map.has-key.

pos

Positionals are excluded

Only named keyword arguments appear in the returned map.

compile

Compile-time only

Browsers never see meta.keywords—only the CSS you emit from the map.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
meta.keywords()Dart Sass via @use "sass:meta"
InputArgument list ($args...)
Return typeMap (bare name → value)
Legacy globalkeywords($args)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Returns a map of named args from an argument list.
  • Keys omit $; values are whatever was passed.
  • Positionals stay out of the keywords map.
  • Great for flexible APIs that accept any named options.

One line: to read named arguments from $args..., use meta.keywords($args).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:meta"
2. Capture with $args...
3. $map: meta.keywords($args)
4. @each $name, $value in $map { … }
5. Look up bare names (no $) with map.has-key

Frequently Asked Questions

meta.keywords($args) returns a map of the keyword (named) arguments passed into a function or mixin that accepts arbitrary arguments via $args....
An argument list—usually the rest parameter from @mixin name($args...) or @function name($args...). Passing a normal list or map is not the same thing.
Official docs: keys are unquoted strings of argument names without the $. So $string: #080 becomes the map key string (the name without $).
No. keywords() only returns named keyword arguments. Positional values stay in the argument list itself.
Yes. keywords($args) is the legacy global name. Prefer meta.keywords after @use "sass:meta".
Flexible APIs that accept any set of named options—theme tokens, syntax highlighters, or property bags—then loop the map with @each.

Next: Sass meta.load-css()

Load another module’s CSS into the current stylesheet.

meta.load-css() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass meta.inspect Function Sass meta.load-css Function