Dart - Inserting Elements into List Examples

This tutorial shows you examples of how to insert elements into a List in Dart, which also applies on any Dart framework such as Flutter and AngularDart.

For adding elements to a List, we can use add, addAll, insert, or insertAll. Those methods return void and they mutate the List object.

Using .add(E value)

.add is used to add an element at the end of the List. It accepts one parameter:

• E value: The element to be added

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];

  strings.add("six");
  print(strings);

Output:

  [one, two, three, four, five, six]

If you apply this method on an empty List, it will become the first and also the last element.

  List<String> strings = [];

  strings.add("one");
  print(strings);

Output:

  [one]

However, if it's applied on a null List, you will get NoSuchMethodError exception.

  List<String> strings = null;

  strings.add("one");
  print(strings);

Output:

  Unhandled exception:
  NoSuchMethodError: The method 'add' was called on null.

Using .addAll(Iterable<E> iterable)

.addAll is used to add multiple elements at the end of a List. It accepts on parameter as well. But instead of an element, you need to pass an Iterable.

• Iterable<E> iterable: An Iterable containing elements to be added

The Iterable must have the same element type as the List. Otherwise, you will get compile error.

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];
  List<String> newStrings = ['new-one', 'new-two'];

  strings.addAll(newStrings);
  print(strings);

Output:

  [one, two, three, four, five, new-one, new-two]

You can also use Set.

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];
  Set<String> newStrings = new Set();
  newStrings.add('new-one');
  newStrings.add('new-two');

  strings.addAll(newStrings);
  print(strings);

Output:

  [one, two, three, four, five, new-one, new-two]

Applying .addAll on an empty List makes the modified List contains the exactly same elements as the passed Iterable. If this method is applied on a null List, it will throw the following error:

  Unhandled exception:
  NoSuchMethodError: The method 'addAll' was called on null.

Using .insert(int index, E element)

.insert is used to insert an element at certain position and shifts all elements afterwards. It accepts two parameters:

• int index: The index where the element will be inserted
• E element: The element to be inserted

Here is the example:

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];
  strings.insert(3, "new");
  print(strings);

As the index starts at 0, the code above will place 'new' as the fourth element, shifting 'four' and 'five' to the right by one position.

Output:

  [one, two, three, new, four, five]

The valid index value must be in the range 0..N, where N is the number of elements. Passing 0 as index means the value will be placed as the first element, while passing N means the value will be placed at the end of the List. If you try to use invalid index.

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];

  strings.insert(6, 'new');
  print(strings);

You will get this error:

  Unhandled exception:
  RangeError: Invalid value: Not in range 0..5, inclusive: 6

If the List is empty, the only valid index value is 0. If the List is null, you will get this exception:

  Unhandled exception:
  NoSuchMethodError: The method 'insertAll' was called on null.

Using .insertAll(int index, Iterable<E> iterable)

.insertAll is used to insert elements at the given index, shifting the elements aferwards by the number of the elements to be inserted.

• int index: The index where the element will be inserted
• Iterable<E> element: The elements to be inserted

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];
  List<String> newStrings = ['new-one', 'new-two'];

  strings.insertAll(3, newStrings);
  print(strings);

Output:

  [one, two, three, new-one, new-two, four, five]

Like insert, the valid index range is 0..N, where N is the number of the List where .insertAll is applied on. Passing invalid index will throw RangeError exception as well.

The only valid index value for an empty List is 0. Applying .insertAll on a null List will trigger NoSuchMethodError as well.

Inserting an Element only if it doesn't exist

If you need to insert a value only if it is not presence in the List yet, you can check the presence of the value using contains(E element) first, then call add or insert only if contains returns false.

  List<String> strings = ['one', 'two', 'three', 'four', 'five'];

  !strings.contains('one') ?? strings.add('one');
  print(strings);

As the 'one' value is already exist, it will not execute the add method. Output:

  [one, two, three, four, five]

Alternatively, you can use Dart's Set which always keeps the elements unique.