Spread Operators: ... and ...?
They evaluate a collection expression, unpack all its individual elements, and insert them directly into another collection literal (List, Set, or Map).
... and ...? are not traditional mathematical operators and do not form standalone operator expressions — they are also categorized as syntactic sugar.
There are two variants:
...collection: Basic spread syntax. The collection must never be null; passing a null value will throw an error immediately.
...?collection: Null-safe spread syntax. If the collection evaluates to null, the spread operation is skipped entirely with no exception thrown.
The official examples below make their behavior straightforward to understand:
void main() {
final list1 = [1, 2, 3];
final list2 = [0, ...list1, 4, 5];
print(list2); // [0, 1, 2, 3, 4, 5]
// Null-safe spread demonstration
List<int>? maybeList;
final safeList = [10, ...?maybeList, 20];
print(safeList); // [10, 20]; no error even though maybeList is null
}</int>Code language: Dart (dart)In the first snippet, we have a source list containing three elements: 1, 2, 3. The second list unpacks and inserts all items from list1 after the value 0, then appends 4 and 5 at the end, resulting in the combined sequence [0, 1, 2, 3, 4, 5].
The second example also performs a spread insertion, but uses the null-safe variant. Since maybeList holds null, the spread step is omitted with no runtime crash and no impact on the final collection.
Spread Example with Set
void main() {
final set1 = {1, 2};
final set2 = {3, ...set1, 4};
print(set2); // {3, 1, 2, 4}
}Code language: PHP (php)
Spread Example with Map
void main() {
final map1 = {'a': 1, 'b': 2};
final map2 = {'c': 3, ...map1, 'd': 4};
print(map2); // {c: 3, a: 1, b: 2, d: 4}
}Code language: PHP (php)Important Restrictions
The spread syntax ... cannot be used standalone outside of [] or {} collection literals.
void main() {
final list1 = [1, 2, 3];
var arr = ...list; // Syntax error: spread can only live inside collection literals
}Code language: PHP (php)D:\dartdemo\firstdart>dart run
Building package executable...
Failed to build firstdart:firstdart:
bin/firstdart.dart:3:12: Error: Expected an identifier, but got '...'.
Try inserting an identifier before '...'.
var arr = ...list; // Syntax error: spread can only live inside collection literals
^^^
bin/firstdart.dart:3:12: Error: Expected ';' after this.
var arr = ...list; // Syntax error: spread can only live inside collection literals
^^^
bin/firstdart.dart:3:15: Error: Undefined name 'list'.
var arr = ...list; // Syntax error: spread can only live inside collection literalsCode language: PHP (php)Using plain ... to spread a nullable collection that may hold null will throw a compile error. Always use ...? if the collection could potentially be null.
void main() {
List<int>? list = null;
var res = [...list]; // Compile error
var resSafe = [...?list]; // Valid null-safe spread
}</int>Code language: PHP (php)D:\dartdemo\firstdart>dart run
Building package executable...
Failed to build firstdart:firstdart:
bin/firstdart.dart:3:16: Error: An expression whose value can be 'null' must be null-checked before it can be dereferenced.
var res = [...list]; // Compile errorCode language: PHP (php)