Working with Keyword Lists and Maps in Elixir

Apr 11, 2016

Table of contents:

  1. What are Keyword Lists?
  2. What are Keyword Lists used for?
  3. What are Maps?
  4. The Map module
  5. Conclusion

So far in this introduction to Elixir we’ve looked at Strings, Tuples, and Lists.

Another common type that you will find in many different programming languages is the associative data structure.

Associative data structures go by a couple of different names depending on the language. You might also know them as associative arrays, hashes or dictionaries.

In today’s tutorial we are going to be taking a look at the two data associative structures in Elixir, Keyword Lists and Maps.

What are Keyword Lists?

A Keyword List is a List of Tuples where the first item of each Tuple is an Atom:

first = [{:first_name, "Philip"}, {:last_name, "Brown"}]

You can also create a Keyword List with this alternative syntax:

second = [first_name: "Philip", last_name: "Brown"]

If you compare the two lists, you will see that they are equal:

first == second
# true

So when you use the second (nicer) syntax, Elixir will just convert it under the hood to a List of Tuples where the key of each Tuple is an Atom.

A Keyword List is just a List and so you have access to all of the same functionality that we looked at in Understanding Lists in Elixir:

# "Philip"

# 2

What are Keyword Lists used for?

Keyword Lists have a couple of special characteristics that make them different from other types:

  • Keys must be atoms
  • Keys are ordered, as specified by the developer
  • Keys can be given more than once

Keyword Lists are usually used for passing the arguments to a function or for passing options.

What are Maps?

Maps are used to store key / value associations in Elixir. The main differences between a Map and a Keyword List is that Maps are not ordered and you can use any type for the key.

To create a new Map you would use the %{} syntax:

map = %{:first_name => "Philip", :last_name => "Brown"}

You don’t have to use Atoms for the keys when defining a Map:

map = %{"first_name" => "Philip", "last_name" => "Brown"}

But if the keys are Atoms, you can use the Keyword List syntax from earlier:

map = %{first_name: "Philip", last_name: "Brown"}

You can access the values of a Map using dot syntax:

# "Philip"

Maps are used extensively in Elixir for Pattern Matching. We haven’t covered Pattern Matching so far in this series so I will leave that topic for a future tutorial.

The Map module

As we’ve seen a couple of times so far in this introduction to Elixir, there is also a Standard Library Module that provides a number of useful functions for working with Maps.

Here are some of the highlights.

The equal? function checks to see if the two given maps are equal:

The merge function will merge two maps together:

Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4})
# %{a: 3, b: 2, d: 4}

The pop function finds and removes all values associated with the given key:

Map.pop(%{a: 1}, :a)
# {1, %{}}

For a full list of the available functions and their documentation, take a look at the documentation.


If you are familiar with another programming language you will probably feel very comfortable with understanding associative data structures and how you might use them.

However even if you are very familiar with a particular data type such as associative data structures, I think it’s always a good idea to acclimatise to a new programming language by researching and understanding the various types of the language.

This will definitely help you get productive quicker when you start to get your hands really dirty!

Philip Brown


© Yellow Flag Ltd 2024.