flutter
/

Dart Spread Operator – ... and ...? with Examples

Last Sync: Today

On this page

10
0%
5 min read
Remaining
5 minleft

Click any section to jump — progress syncs automatically

flutter

Dart Spread Operator – ... and ...? with Examples

What is the Spread Operator?

The spread operator (...) was introduced in Dart 2.3 and provides a concise way to insert multiple elements into a collection. It 'spreads' the elements of an existing collection into a new collection literal. This is especially useful when you want to combine collections, add all elements from one collection to another, or conditionally include elements.

Basic Syntax

DARTRead-only
1
void main() {
  var list1 = [1, 2, 3];
  var list2 = [0, ...list1, 4]; // [0, 1, 2, 3, 4]
  print(list2);
}

The ...list1 expands to 1, 2, 3 inside the new list literal.

Spread with Lists

You can use the spread operator anywhere inside a list literal to insert all elements of another list.

DARTRead-only
1
void main() {
  var numbers = [1, 2, 3];
  var moreNumbers = [4, 5, 6];
  var combined = [...numbers, ...moreNumbers];
  print(combined); // [1, 2, 3, 4, 5, 6]
}

Spread with Sets

The spread operator works similarly with sets. Note that sets maintain uniqueness, so duplicates are automatically removed.

DARTRead-only
1
void main() {
  var set1 = {1, 2, 3};
  var set2 = {3, 4, 5};
  var combined = {...set1, ...set2};
  print(combined); // {1, 2, 3, 4, 5}
}

Spread with Maps

For maps, the spread operator inserts all key‑value pairs from another map. If there are duplicate keys, later spreads override earlier ones.

DARTRead-only
1
void main() {
  var map1 = {'a': 1, 'b': 2};
  var map2 = {'b': 3, 'c': 4};
  var combined = {...map1, ...map2};
  print(combined); // {a: 1, b: 3, c: 4} (b is overwritten)
}

Null‑Aware Spread Operator (...?)

When the collection you want to spread might be null, use the null‑aware spread operator ...?. If the expression is null, it simply contributes nothing instead of throwing an error.

DARTRead-only
1
void main() {
  List<int>? maybeList;
  var list = [1, 2, ...?maybeList, 3];
  print(list); // [1, 2, 3] – no error
  
  maybeList = [4, 5];
  list = [1, 2, ...?maybeList, 3];
  print(list); // [1, 2, 4, 5, 3]
}

Combining Spread with Collection if and for

You can mix spread operators with collection if and for to build collections dynamically.

DARTRead-only
1
void main() {
  bool includeExtra = true;
  var extraNumbers = [4, 5];
  
  var numbers = [
    1,
    2,
    if (includeExtra) ...extraNumbers,
    3,
  ];
  print(numbers); // [1, 2, 4, 5, 3]
}

Notice that inside the if block we used ...extraNumbers to spread the list. This is a very powerful pattern for conditional inclusion of multiple elements.

Using Spread with Function Arguments

Although the spread operator is primarily for collection literals, you can also use it to pass a list as multiple positional arguments to a function using the ... syntax inside a function call (this is a different feature called 'spread in argument lists' introduced in Dart 3.0).

DARTRead-only
1
void printNumbers(int a, int b, int c) {
  print('$a, $b, $c');
}

void main() {
  var numbers = [1, 2, 3];
  printNumbers(...numbers); // 1, 2, 3
}

This is useful when you have a list and want to pass its elements as individual arguments.

Complete Example

DARTRead-only
1
void main() {
  // Combine multiple lists
  var fruits = ['apple', 'banana'];
  var berries = ['strawberry', 'blueberry'];
  var allFruits = [...fruits, ...berries];
  print('Fruits: $allFruits');
  
  // Merge maps (later keys override)
  var defaults = {'theme': 'light', 'fontSize': 14};
  var userPrefs = {'theme': 'dark'};
  var settings = {...defaults, ...userPrefs};
  print('Settings: $settings'); // {theme: dark, fontSize: 14}
  
  // Null‑aware spread
  List<String>? extraColors;
  var colors = ['red', 'green', ...?extraColors, 'blue'];
  print('Colors: $colors');
  
  // Conditional spread with if
  bool showAdmin = true;
  var adminFeatures = ['manage users', 'view logs'];
  var menu = [
    'home',
    'profile',
    if (showAdmin) ...adminFeatures,
    'settings',
  ];
  print('Menu: $menu');
}

Key Takeaways

    • The spread operator ... inserts all elements of a collection into another collection literal.
    • Works with Lists, Sets, and Maps.
    • For maps, later spreads override keys from earlier spreads.
    • Use ...? to safely spread a nullable collection – if it's null, nothing is inserted.
    • Combine with collection if and for for dynamic collection building.
    • Spread can also be used to pass list elements as individual function arguments (Dart 3+).

Try it yourself

void main() {
  var listA = [1, 2, 3];
  var listB = [4, 5, 6];
  var combined = [...listA, ...listB];
  print('Combined: $combined');
  
  var mapA = {'x': 10, 'y': 20};
  var mapB = {'y': 99, 'z': 30};
  var merged = {...mapA, ...mapB};
  print('Merged map: $merged');
}

Test Your Knowledge

Q1
of 4

What is the output of this code? void main() { var a = [1, 2]; var b = [3, 4]; var c = [0, ...a, ...b, 5]; print(c); }

A
[0, 1, 2, 3, 4, 5]
B
[0, [1, 2], [3, 4], 5]
C
[0, 1, 2, 5]
D
Error
Q2
of 4

What does the null‑aware spread operator `...?` do when the spread expression is null?

A
Throws an exception
B
Inserts a null element
C
Inserts nothing
D
Skips the entire collection literal
Q3
of 4

Given `var map1 = {'a': 1}; var map2 = {'a': 2, 'b': 3};`, what is `{...map1, ...map2}`?

A
{a: 1, a: 2, b: 3}
B
{a: 1, b: 3}
C
{a: 2, b: 3}
D
{a: 1, b: 3, a: 2}
Q4
of 4

Which operator would you use to safely spread a nullable list inside another list?

A
...
B
...?
C
??
D
?.

Frequently Asked Questions

What is the spread operator and why would I use it?

The spread operator ... expands an iterable (like a list, set, or map) into individual elements inside a collection literal. It's useful for combining collections, inserting all elements of one collection into another, and conditionally including multiple elements in a concise way.

What is the difference between `...` and `...?`?

... spreads a collection, but throws an error if the collection is null. ...? is the null‑aware spread operator – if the collection is null, it simply adds nothing (no error). Always use ...? when the spread expression might be null.

Can I use the spread operator with Sets?

Yes, you can use ... inside a set literal to include all elements of another set or list. Duplicates are automatically removed because sets enforce uniqueness. For example: {1, 2, ...anotherSet, 3}.

How does spread work with Maps?

When spreading a map, all key‑value pairs are inserted. If the same key appears in multiple maps, later spreads override earlier ones. For example: {...map1, ...map2} – if both have the same key, the value from map2 will be used.

Can I combine spread with collection `if` and `for`?

Yes, you can use ... inside a collection if or for to conditionally insert multiple elements. For example: [if (show) ...extraItems] adds all elements of extraItems only if show is true.

What happens if I spread an empty collection?

Spreading an empty collection adds nothing. For example, [1, 2, ...[], 3] results in [1, 2, 3]. This is safe and useful when the collection might be empty.

Can I use spread inside a function call?

In Dart 3.0 and later, you can use ... to pass a list as multiple positional arguments to a function. For example: printNumbers(...[1, 2, 3]) calls printNumbers(1, 2, 3). The list length must match the number of parameters.

Are there any performance concerns with using spread?

Spreading creates a new collection and copies elements, so for very large collections it may have a performance cost. However, for typical use cases it's efficient and the readability benefits outweigh any minor overhead.

Previous

dart collection methods

Next

dart collection if for

Related Content

Need help?

Explore our comprehensive docs or start a chat with our tech experts.