How does HashMap work internally?

A HashMap stores key-value pairs in an internal array of buckets.

When you call put(key, value), Java uses the key's hash code to decide which bucket the entry should go into. When you call get(key), Java uses the same idea to quickly jump to the likely bucket instead of scanning every entry.

1. HashMap receives the key and value.
2. It calculates a hash from the key.
3. It converts that hash into a bucket index.
4. If the bucket is empty, it stores the entry there.
5. If the bucket already has entries, it checks whether the key already exists using equals().
6. If the key exists, the old value is replaced. If not, a new entry is added to that bucket.

Map<String, Integer> scores = new HashMap<>();

scores.put("alice", 90);
scores.put("bob", 85);
scores.put("alice", 95); // replaces Alice's old value

HashMap uses hashCode() to find the bucket, but it uses equals() to confirm whether two keys are actually the same logical key.

class UserId {
    private final String value;

    UserId(String value) {
        this.value = value;
    }

    // If two UserId objects are logically equal,
    // equals() and hashCode() must agree.
}

A collision happens when two different keys land in the same bucket. This is normal. HashMap is designed to handle it.

If collisions are rare, HashMap remains very fast. If many keys collide into the same bucket, lookup becomes slower because Java has to search within that bucket.

In older mental models, people often say: “A HashMap bucket contains a linked list.” That is partly true, but modern Java has an extra optimization.

If too many entries collide into the same bucket, Java can convert that bucket from a linked structure into a tree structure. This improves worst-case lookup behavior when collisions are heavy.

HashMap has a capacity, which is the number of buckets. It also has a load factor, which controls how full the map is allowed to get before it grows.

The common default load factor is 0.75. So if the capacity is 16, resizing happens after the number of entries exceeds 12.

capacity = 16
loadFactor = 0.75

threshold = capacity * loadFactor
threshold = 16 * 0.75 = 12

When the threshold is exceeded, HashMap creates a larger internal table and redistributes entries into new buckets.