Introduction

Flattening a List of List values into one List is a very common Java collection task. In Java 8, the idiomatic solution is to stream the outer list, use flatMap to open the inner lists, and then collect the results into a new list.

Why flatMap Is the Important Method

If you call map(List::stream) on a List<List<Integer>>, you do not get a stream of integers. You get a stream of inner streams. flatMap is what turns those many streams into one continuous stream of elements.

That is the core idea behind flattening nested collections in Java 8.

1import java.util.Arrays;
2import java.util.List;
3import java.util.stream.Collectors;
4
5public class FlattenExample {
6    public static void main(String[] args) {
7        List<List<Integer>> listOfLists = Arrays.asList(
8            Arrays.asList(1, 2, 3),
9            Arrays.asList(4, 5),
10            Arrays.asList(6, 7, 8)
11        );
12
13        List<Integer> flat = listOfLists.stream()
14            .flatMap(List::stream)
15            .collect(Collectors.toList());
16
17        System.out.println(flat);
18    }
19}

The result is one ordered list containing all integers from each inner list.

How the Stream Pipeline Works

The flattening pipeline does three separate jobs:

1. stream() creates a stream over the outer list.
2. flatMap(List::stream) turns each inner list into a stream and merges those streams.
3. collect(Collectors.toList()) materializes the final flattened result.

This style is concise, but it is also precise. The code says exactly what is happening: take nested lists, turn them into one stream, then collect the values.

Preserving Order

With a normal sequential stream, order is preserved automatically. Java processes the outer list from left to right and each inner list in its own encounter order.

That means this input:

1List<List<String>> nested = Arrays.asList(
2    Arrays.asList("a", "b"),
3    Arrays.asList("c"),
4    Arrays.asList("d", "e")
5);

becomes this output:

[a, b, c, d, e]

If order matters, the default stream behavior is usually what you want.

Handling Null or Empty Inner Lists

Empty inner lists are harmless. They simply contribute no elements to the output. Null inner lists are different: calling stream() on null throws a NullPointerException.

If the input is not guaranteed clean, filter nulls first.

1import java.util.Arrays;
2import java.util.List;
3import java.util.Objects;
4import java.util.stream.Collectors;
5
6public class NullSafeFlatten {
7    public static void main(String[] args) {
8        List<List<String>> nested = Arrays.asList(
9            Arrays.asList("x", "y"),
10            null,
11            Arrays.asList("z")
12        );
13
14        List<String> flat = nested.stream()
15            .filter(Objects::nonNull)
16            .flatMap(List::stream)
17            .collect(Collectors.toList());
18
19        System.out.println(flat);
20    }
21}

That extra filter is often enough for defensive code.

Beyond Flattening: Filtering and Transformation

Once the list is flattened into a stream, you can keep processing it. That is one reason streams are popular for this problem.

For example, flatten and keep only even numbers:

1List<Integer> evens = listOfLists.stream()
2    .flatMap(List::stream)
3    .filter(n -> n % 2 == 0)
4    .collect(Collectors.toList());

Or flatten and remove duplicates:

1List<Integer> unique = listOfLists.stream()
2    .flatMap(List::stream)
3    .distinct()
4    .collect(Collectors.toList());

That makes flattening a natural part of a larger transformation pipeline rather than a separate pre-processing step.

Streams Versus Loops

A loop-based solution is also valid and sometimes clearer for teams that do not use streams often. But in Java 8, flatMap is the standard expression of this specific idea.

Loops emphasize mutation and step-by-step accumulation. Streams emphasize transformation. Neither is universally superior, but flatMap is the most idiomatic answer to the question.

Common Pitfalls

A common mistake is using map(List::stream) and wondering why the result is a stream of streams instead of a flat stream of values.

Another issue is ignoring null inner lists. Empty lists work fine, but null values need to be filtered or handled explicitly.

Developers also sometimes assume flattening changes the original nested structure. It does not. The stream pipeline creates a new list and leaves the source lists unchanged.

Summary

• In Java 8, flatMap is the standard way to flatten a List of List values.
• 'flatMap(List::stream) merges the inner lists into one stream of elements.'
• Sequential streams preserve the natural order of the nested lists.
• Empty inner lists are fine, but null inner lists need defensive handling.
• Flattening can be combined with filtering, mapping, or deduplication in the same stream pipeline.