How to Iterate Over a HashMap in Kotlin

By the end of this page, you will understand how to iterate over a HashMap in Kotlin using idiomatic approaches such as looping through entries, keys, and values. You will also see when to use destructuring, forEach, and other common patterns used in real Kotlin codebases.

In Kotlin, a HashMap is a key-value collection. Each item in the map has:

• a key used to identify the item
• a value stored under that key

When people say they want to “iterate over a HashMap,” they usually mean one of these:

• loop through every key-value pair
• loop through only the keys
• loop through only the values

Although HashMap comes from Java, Kotlin provides cleaner and more readable ways to work with it.

A map matters in real programming because it is often used for:

• configuration settings
• user data by ID
• counting occurrences
• caching values
• request parameters
• lookup tables

In Kotlin, the most common way to iterate a map is to loop through its entries or use destructuring directly in a for loop. This is preferred because it is readable and gives direct access to both the key and the value.

Think of a HashMap like a locker room:

• each key is a locker number
• each value is what is stored inside that locker

Iterating over the map means walking past all the lockers and checking:

• the locker numbers only (keys)
• the contents only (values)
• or both the number and the contents (entries)

Kotlin makes this easy by letting you open each locker and directly name the two parts:

for ((key, value) in map) {
    println("$key -> $value")
}

That syntax is called destructuring: Kotlin splits each map entry into two variables for you.

Basic syntax

Iterate over key-value pairs

val scores = hashMapOf(
    "Alice" to 95,
    "Bob" to 87,
    "Charlie" to 91
)

for ((name, score) in scores) {
    println("$name scored $score")
}

This is the most idiomatic Kotlin approach. Each map entry is unpacked into name and score.

Iterate using entries

for (entry in scores.entries) {
    println("${entry.key} scored ${entry.value}")
}

Use this when you want the full entry object.

Iterate over keys only

for (name in scores.keys) {
    println(name)
}

Iterate over values only

 (score  scores.values) {
    println(score)
}

Consider this example:

val items = hashMapOf(
    "pen" to 2,
    "notebook" to 5
)

for ((name, quantity) in items) {
    println("$name: $quantity")
}

Here is what happens step by step:

1. A HashMap named items is created.

   • key "pen" has value 2
   • key "notebook" has value 5

2. The for loop starts:

for ((name, quantity) in items)

1. Kotlin takes the first entry from the map.

   • name becomes the key
   • quantity becomes the value

Iterating over maps is common in many real applications.

Configuration settings

val config = mapOf(
    "host" to "localhost",
    "port" to "8080",
    "mode" to "debug"
)

for ((key, value) in config) {
    println("$key = $value")
}

Used for printing or validating settings.

Counting values

val wordCounts = hashMapOf(
    "kotlin" to 3,
    "java" to 2,
    "api" to 5
)

for ((word, count) in wordCounts) {
    println("$word appears $count times")
}

Used in text processing and analytics.

API query parameters

val params = mapOf(
    "page" to "1",
    "sort" to "name"
)

for ((key, value)  params) {
    println()
}

In real Kotlin projects, developers usually choose the iteration style based on what they need.

Common patterns

1. Destructuring for readability

for ((key, value) in settings) {
    println("$key -> $value")
}

Best when both parts are needed.

2. Guard clauses while iterating

for ((key, value) in settings) {
    if (value.isBlank()) continue
    println("Valid setting: $key = $value")
}

Useful for skipping invalid entries early.

3. Validation

for ((field, value) in formData) {
    if (value.isBlank()) {
        println("$field is required")
    }
}

Common in forms, API inputs, and configuration loading.

4. Transformation with collection functions

val uppercased = scores.map { (name, score) ->
    ": "
}

1. Iterating over keys when you need both key and value

Broken or inefficient approach:

for (key in scores.keys) {
    println("$key -> ${scores[key]}")
}

This works, but it performs a lookup for each key. A clearer approach is:

for ((key, value) in scores) {
    println("$key -> $value")
}

2. Assuming HashMap keeps insertion order

Broken assumption:

val map = hashMapOf("a" to 1, "b" to 2, "c" to 3)
for ((k, v) in map) {
    println(k)
}

Do not rely on the output order. If order matters, use an ordered map.

3. Forgetting that keys may not exist

val age = scores["Unknown"]
println(age)

This may print null. Kotlin maps often return nullable values when a key is missing.

val map = hashMapOf(
    "a" to 1,
    "b" to 2
)

Iterate over key-value pairs

for ((key, value) in map) {
    println("$key -> $value")
}

Iterate with entries

for (entry in map.entries) {
    println(entry.key)
    println(entry.value)
}

Iterate over keys

for (key in map.keys) {
    println(key)
}

Iterate over values

for (value in map.values) {
    println(value)
}

Use forEach

map.forEach { (key, value) ->
    println("$key -> $value")
}

Key rules

How do I loop through a HashMap in Kotlin?

Use a for loop with destructuring:

for ((key, value) in map) {
    println("$key -> $value")
}

What is the most idiomatic way to iterate over a map in Kotlin?

The most idiomatic approach is usually:

for ((key, value) in map)

It is concise and readable.

Can I iterate over only the keys or only the values?

Yes.

for (key in map.keys) { }
for (value in map.values) { }

Does HashMap preserve insertion order in Kotlin?

No. If you need predictable iteration order, use LinkedHashMap or linkedMapOf().

What does (key, value) mean in a Kotlin for loop?

• Map — the general key-value interface that HashMap implements.
• MutableMap — used when you need to add, remove, or update entries.
• LinkedHashMap — useful when iteration order matters.
• Destructuring declarations — lets you write (key, value) in loops and lambdas.
• forEach — a common alternative to for loops in Kotlin collections.
• Null safety — important because map lookups may return null.
• Collection transformations — functions like map and filter are often used with maps in real code.