My Profile Photo

Sheogorath's Blog


Depending on the time of the day a friend, a colleague, a wise guy. The beauty of the world is its sense of humor to show humans their way by letting them search their own.


Cover image for this blog post

Using the Matrix room directory

Everyone who follows me around will have notice that I’m an advocate for the matrix protocol. Main argument is of course the federation, but also the growing ecosystem and strong standardization of the protocol. Since I’m an advocate for protocol, I of course provide various channels on this wonderful, federated platform.

To find those you have two possibilities:

  1. You visit my overview page for matrix rooms and read through it
  2. You use the room directory in Riot or your matrix client to find the rooms on my homeserver

How does the room directory work?

The room directory is a rather simply tool in Riot and probably also in other matrix clients. As the name indicates it a list of rooms that are published on a homeserver. That doesn’t mean that these rooms exist only on this homeserver, but rather than someone decided to publish them to the “local room directory”.

The homeserver stores a reference to the room as well as some room metadata, like the description, picture, number of members, etc. and provides them in a compact JSON format, that clients can request. Depending on your homeserver configuration, it might even be available from outside your homeserver. This is of course a risk when you want to use it to provide “your people” a room list containing internal rooms, but for me as a single-user or family instance, it’s great to provide a curated list to you and other people.

How to use the room directory?

To open the room directory, select the “Explore”-Button in the upper left corner of Riot1. It’ll open the room directory and give you a first impression what people on your homeserver are interested in.

Image of the "Explore"-button

The “Explore”-Button is at the top of your room list, that provides all rooms you already joined, and besides the “filter”-field to quickly search your room list. You might also notice the number of icons above, these are the last visited rooms, and the icons on the side, these are communities. Basically filters for the room list, paired with memberships and a description.

The home directory will open and provide you with the default list of your homeserver. I’ll try to explain all sections and their functions a bit more detailed:

Matrix room directory with number 1 for the search bar, 2 for the room directory selected, 3 for the drop-down menu and 4 for the regular room directory list

The room directory contains 4 major components:

  1. The search bar — It allows you to search the name, handle and description of rooms that are published to the room directory. E.g. “Random talks” or “CodiMD”
  2. The drop-down for homeservers — This drop-down provides a default selection of homeservers for the room directory. By default this is your homeserver and matrix.org. You can alter this with your Riot configuration.
  3. The drop-down for adding additional homeservers — Is the list of additional homeservers you can add yourself using the “Add a new server”-button. This will allow you to add and select other homeservers to browse their room directory. E.g.: gnome.org or shivering-isles.com
  4. The room list — This is the list that results out of the settings above. It’s endless scrolling and will contain the filtered or unfiltered selects rooms for your query.

Additional information

With all this said, I guess you are now ready to explore the Matrix space, find new rooms to hang out. To make it easier, let me provide you some server that have public room lists available:

  • matrix.org
  • mozilla.org
  • gnome.org
  • (and of course) shivering-isles.com

Another very popular way to explore new rooms are communities. But since they are not perfectly implemented and would break the scope of this article, I’ll leave it to you, to figure out how they work.

All in all, I hope you can use this tutorial to get started with your room exploration. See you on Matrix!

Update: Updated the screenshot and description to version 1.5.15 of Riot.

Photo by Jamie Street on Unsplash

  1. Riot version 1.5.15, if you run a much earlier or later version of Riot this might no longer matches. And of course it can be completely different, when you use a different client like fractal.