Java ArrayList contains: Usage, Performance, and Alternatives
Learn how Java ArrayList.contains works, its linear scan behavior, null handling, and when to switch to HashSet for faster lookups.

The contains method on java.util.ArrayList tells you whether a list contains a specified element. It works by scanning the list from the first element to the last and comparing each element with the argument. The behavior is simple and predictable, but the linear scan has performance implications when the list is large or when membership checks happen frequently.
How ArrayList.contains Works
The contains(Object o) method is declared by the Collection interface and implemented in ArrayList by iterating over the internal array and comparing each element with the argument. For a non-null argument, the comparison calls argument.equals(element) for each element. For a null argument, it uses == to look for a null element. The method therefore depends on the equals contract of the elements stored in the list.
List<String> names = new ArrayList<>();
names.add("Alice");
names.add("Bob");
if (names.contains("Alice")) {
System.out.println("Found Alice");
}In this example, contains calls "Alice".equals("Alice") on the first element and returns true immediately. If the element is not found, the scan completes without a match and false is returned.
The Role of equals and hashCode
ArrayList.contains uses equals to determine equality and does not use hashCode. This is different from HashSet or HashMap, which rely on hashCode to locate buckets. For ArrayList, the key requirement is that the elements' equals method is implemented correctly. If you store custom objects, you must override equals (and ideally hashCode) to define meaningful equality.
class Product {
String sku;
Product(String sku) {
this.sku = sku;
}
@Override
public boolean equals(Object obj) {
if (this == obj) return true;
if (!(obj instanceof Product)) return false;
Product other = (Product) obj;
return sku.equals(other.sku);
}
@Override
public int hashCode() {
return sku.hashCode();
}
}Without overriding equals, two Product instances with the same sku are not considered equal because Object.equals compares references. In that case, contains only returns true for the exact same object instance, which is rarely the intended behavior.
Null Handling in contains
ArrayList allows null elements, and contains handles them correctly. When you call contains(null), the implementation checks for a null element using == rather than equals. This is consistent with the Objects.equals semantics.
List<String> list = new ArrayList<>();
list.add(null);
System.out.println(list.contains(null)); // trueIf the list contains null and you call contains with a non-null object, the scan still calls equals on the null element as object.equals(null). A well-behaved equals implementation should return false for a null argument, so the scan continues without treating null as a match. If a custom equals does not handle null, a NullPointerException can occur.
Time Complexity and Performance
ArrayList.contains runs in O(n) time because it may need to examine every element. For small lists, this overhead is negligible. But if you call contains repeatedly on a large list, the cumulative cost becomes significant. For example, checking membership for each of m elements against a list of size n results in O(m * n) time.
List<String> largeList = new ArrayList<>();
// populate largeList...
for (String item : manyItems) {
if (largeList.contains(item)) {
// process match
}
}In such scenarios, a HashSet provides O(1) average lookup time because it uses hashCode to locate the element directly. The tradeoff is that HashSet does not preserve insertion order and requires proper hashCode implementations.
Comparing ArrayList and HashSet for contains
| Collection | contains Time Complexity | Ordering | Null Elements | Requires hashCode |
|---|---|---|---|---|
| ArrayList | O(n) | Insertion order | Yes | No |
| HashSet | O(1) average | No guaranteed order | Yes (one null) | Yes |
Use ArrayList when you need to preserve order and the list is small, or when contains is called rarely. Use HashSet when membership testing is a primary operation and the collection size is large. If you need both order and fast lookups, consider LinkedHashSet, which maintains insertion order while providing O(1) contains.
Using containsAll for Bulk Checks
ArrayList also provides the containsAll(Collection<?> c) method from the Collection interface. This method returns true if all elements of the specified collection are present in the list. It is implemented by iterating over the argument collection and calling contains for each element, so its time complexity is O(n * m) where n is the list size and m is the argument size.
List<String> required = Arrays.asList("A", "B");
List<String> actual = Arrays.asList("A", "B", "C");
boolean hasAll = actual.containsAll(required); // trueIf you frequently need to check whether a list contains all elements of another collection, consider using a HashSet for the larger collection to reduce the overall cost.
When to Avoid ArrayList.contains
Avoid using ArrayList.contains in tight loops or with large datasets where membership checks dominate. A common pattern is deduplication: building a list of unique items by checking contains before adding. This is O(n^2) for n items. Instead, use a HashSet to track seen items and then optionally convert to a list if order matters.
List<String> unique = new ArrayList<>();
Set<String> seen = new HashSet<>();
for (String item : input) {
if (seen.add(item)) {
unique.add(item);
}
}Here, HashSet.add returns false if the item already exists, providing O(1) membership testing. This approach scales much better than using ArrayList.contains in a loop.
Compatibility and Version Notes
The behavior of ArrayList.contains has been stable for many Java versions. The implementation relies on equals and does not depend on hashCode. This means that even if a class has a broken hashCode (for example, always returning 0), ArrayList.contains still works correctly as long as equals is correct. This is a subtle advantage over HashSet, which would degrade to O(n) behavior in such cases.
No special configuration is required to use contains; it is available on any ArrayList instance.
For most applications, the decision between ArrayList and HashSet for membership tests comes down to the tradeoff between order preservation and lookup speed. Measure your actual usage patterns rather than assuming one is always better. If you need to maintain order and the list is small, ArrayList.contains is perfectly acceptable. If you are building a lookup index or performing frequent membership checks on a large dataset, switch to a HashSet or LinkedHashSet.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.