list.is-bracketed($list) returns true when $list uses square brackets ([…]), otherwise false. Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: is-bracketed().
Round parentheses do not count. Pair with list.join(..., $bracketed: …) when you create or force bracketed lists.
list.is-bracketed(1px 2px 3px) → false. list.is-bracketed([1px, 2px, 3px]) → true.
CSS values like grid tracks often need square brackets. This helper lets mixins branch on that shape before emitting CSS.
@use "sass:list";
list.is-bracketed(1px 2px 3px); // false
list.is-bracketed([1px, 2px, 3px]); // true
list.is-bracketed((1px, 2px, 3px)); // false — parentheses ≠ brackets
list.is-bracketed([]); // true
// Global alias still works
is-bracketed([1fr 2fr]);Pattern: inspect with is-bracketed → emit or rewrite with join(..., $bracketed: true) when brackets are required.
What counts as bracketed:
| List shape | is-bracketed |
|---|---|
[1px, 2px, 3px] | true |
1px 2px 3px / (1px, 2px, 3px) | false |
[] | true (empty but bracketed) |
Single value 10px | false |
list.join(..., $bracketed: true) | true |
Comma lists written with (…) are unbracketed. Only square […] returns true.
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
A normal spacing list has no square brackets.
@use "sass:list";
@debug list.is-bracketed(1px 2px 3px); // false
.plain {
--bracketed: #{list.is-bracketed(1px 2px 3px)};
}false.true (Official Docs)Comma list written with […] is bracketed.
@use "sass:list";
@debug list.is-bracketed([1px, 2px, 3px]); // true
.square {
--bracketed: #{list.is-bracketed([1px, 2px, 3px])};
}true.Edge shapes you will meet in real tokens.
@use "sass:list";
.report {
--space: #{list.is-bracketed(10px 20px 30px)};
--comma-brackets: #{list.is-bracketed([blue, red, green])};
--parens: #{list.is-bracketed((1px, 2px, 3px))};
--single: #{list.is-bracketed(10px)};
--empty: #{list.is-bracketed([])};
}false.true.[] is empty but still bracketed → true.Only emit a value when the list is already bracketed.
@use "sass:list";
$plain: 8px 16px 24px;
$grid: [1fr 2fr 1fr];
.guard {
@if list.is-bracketed($grid) {
--grid-display: #{$grid};
} @else {
--grid-display: none;
}
@if list.is-bracketed($plain) {
--plain-display: #{$plain};
} @else {
--plain-kind: unbracketed;
}
}$grid is bracketed → emit the tracks.$plain is not → take the else path.@if keeps the check compile-time safe.list.joinCreate a bracketed list, then confirm with is-bracketed.
@use "sass:list";
@use "sass:meta";
$forced: list.join(10px, 20px, $bracketed: true);
.forced {
--joined: #{meta.inspect($forced)};
--is-bracketed: #{list.is-bracketed($forced)};
}$bracketed: true on join adds square brackets.meta.inspect shows [10px 20px].is-bracketed confirms true.Most is-bracketed bugs are confusing parentheses with square brackets or mixing up brackets with separators.
(1px, 2px, 3px) returns false. Only […] is bracketed.
A list can be space- or comma-separated and bracketed. Use list.separator for the separator name.
[] is still bracketedlist.is-bracketed([]) is true even though length is 0.
10px counts as a one-item list without brackets.
Prefer the module form with Dart Sass 1.23+. Global is-bracketed() remains for older call sites.
| API | Status |
|---|---|
list.is-bracketed() | Dart Sass 1.23+ via @use "sass:list" |
Global is-bracketed() | Available (prefer module form in new code) |
| Return type | Boolean true / false |
| LibSass / Ruby Sass | No sass:list module — use global is-bracketed() if needed |
Compile with the Dart Sass CLI.
[…].false.$bracketed when you need to create brackets.@use "sass:list".One line: when you need to know if a list uses […], call list.is-bracketed($list).
Practical checklist:
1. @use "sass:list"
2. Remember only square brackets count as bracketed
3. Do not confuse parentheses with brackets
4. Use list.join(..., $bracketed: true) to force brackets
5. Branch with @if list.is-bracketed($list) before emitting CSSCombine two lists, with optional separator and brackets.
8 people found this page helpful