Sass list.is-bracketed() Function

What You’ll Learn

list.is-bracketed() belongs to the built-in sass:list module. It answers one question: does this list use square brackets? This page covers boolean results, brackets vs parentheses, empty lists, pairing with list.join’s $bracketed flag, Dart Sass support, and five compiled examples.

What Is list.is-bracketed()?

In Sass, lists can be written with or without square brackets. Brackets are part of the list’s structure—useful when you want CSS that looks like grid-template-columns: [sidebar] 1fr; or when you intentionally keep a list bracketed inside mixins.

• list.is-bracketed(1px 2px 3px) → false
• list.is-bracketed([1px, 2px, 3px]) → true
• list.is-bracketed((1px, 2px, 3px)) → false (parentheses ≠ brackets)

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.is-bracketed($list)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$flag: list.is-bracketed([1px, 2px]);

// Optional — bring members into scope
@use "sass:list" as *;
$flag: is-bracketed([1px, 2px]);

// Optional — custom namespace
@use "sass:list" as l;
$flag: l.is-bracketed([1px, 2px]);

🔍 Brackets vs Parentheses

Beginners often mix up […] and (…). Only square brackets make list.is-bracketed return true.

@use "sass:list";

// Square brackets → true
$a: list.is-bracketed([10px, 20px]);

// Parentheses / plain lists → false
$b: list.is-bracketed((10px, 20px));
$c: list.is-bracketed(10px 20px);

📋 list.is-bracketed vs list.separator

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished values you choose to emit—never a live is-bracketed call.

Examples Gallery

Each example uses @use "sass:list". Open View Compiled CSS for verified Dart Sass output (official samples where noted).

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

@debug list.is-bracketed(1px 2px 3px);       // false
@debug list.is-bracketed([1px, 2px, 3px]);   // true

.check {
  --plain: #{meta.inspect(list.is-bracketed(1px 2px 3px))};
  --brack: #{meta.inspect(list.is-bracketed([1px, 2px, 3px]))};
}

.check {
  --plain: false;
  --brack: true;
}

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

$space: 1rem 2rem 3rem;
$grid: [auto 1fr minmax(0, 240px)];
$single: 12px;
$empty-brack: [];

.shapes {
  --space: #{meta.inspect(list.is-bracketed($space))};
  --grid: #{meta.inspect(list.is-bracketed($grid))};
  --single: #{meta.inspect(list.is-bracketed($single))};
  --empty: #{meta.inspect(list.is-bracketed($empty-brack))};
}

.shapes {
  --space: false;
  --grid: true;
  --single: false;
  --empty: true;
}

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

$tokens: [primary, secondary, muted];
$joined: list.join(10px, 20px, $bracketed: true);
$unbrack: list.join([10px], 20px, $bracketed: false);

.flags {
  --has-brackets: #{meta.inspect(list.is-bracketed($tokens))};
  --joined: #{meta.inspect(list.is-bracketed($joined))};
  --forced-off: #{meta.inspect(list.is-bracketed($unbrack))};
}

.flags {
  --has-brackets: true;
  --joined: true;
  --forced-off: false;
}

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

@mixin emit-list($name, $list) {
  .#{$name} {
    --bracketed: #{meta.inspect(list.is-bracketed($list))};
    @if list.is-bracketed($list) {
      content: "#{meta.inspect($list)}";
    } @else {
      content: "plain-list";
    }
  }
}

@include emit-list("plain", 1px 2px);
@include emit-list("square", [1px, 2px]);

.plain {
  --bracketed: false;
  content: "plain-list";
}

.square {
  --bracketed: true;
  content: "[1px, 2px]";
}

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

$map: (a: 1, b: 2);

.meta {
  --map-as-list: #{meta.inspect(list.is-bracketed($map))};
  --parens: #{meta.inspect(list.is-bracketed((1px, 2px, 3px)))};
}

.meta {
  --map-as-list: false;
  --parens: false;
}

🚀 Real-World Use Cases

• Grid / track lists — detect whether a track list should keep brackets.
• Design-token helpers — branch mixin output for bracketed vs plain tokens.
• API validation — assert that a caller passed a bracketed list.
• Join pipelines — verify $bracketed after list.join.
• Debugging structure — pair with list.separator in @debug logs.

⚠️ Common Pitfalls

• Parentheses ≠ brackets — (a, b) returns false.
• Confusing with separator — brackets and separators are independent.
• Expecting CSS to care — browsers never call is-bracketed.
• Forgetting @use — list.is-bracketed needs sass:list.
• Assuming maps are bracketed — maps are list-like but not square-bracketed.

💡 Best Practices