The Tag Cycle Extension allows users to define custom cycles tied to a keyboard shortcut!


You could use the Copy Extension button below to individually install this extension. To install, just paste anywhere in your Roam graph and click "Yes, I Know What I'm Doing".

Manual Installation

If the extension doesn't work after using the copy extension button above, try installing manually using the instructions below.

First create a block with the text {{[[roam/js]]}} on any page in your Roam DB. Then, create a single child of this block and type three backticks. A code block should appear. Copy this code and paste it into the child code block in your graph:

var existing = document.getElementById("roamjs-tag-cycle");
if (!existing) {
  var extension = document.createElement("script");
  extension.src = "https://roamjs.com/tag-cycle.js";
  extension.id = "roamjs-tag-cycle";
  extension.async = true;
  extension.type = "text/javascript";

Finally, click "Yes, I Know What I'm Doing".


This script is configured in the [[roam/js/tag-cycle]] page.

For every cycle you want, make a block denoting the keyboard shortcut that will trigger that cycle. Then as children of that block, create one block for each text in the cycle.

Now when you're in a given block, the keyboard shortcut will replace text in your block based on the cycle you defined!

The format of a keyboard shortcut is deliminated by +. The following modifiers are supported:

  • CTRL
  • CMD
  • WIN
  • ALT Additionally, could use "SHIFT", but it should added after the modifier. The Key pressed is the last component.

This is what it would look like for Roam's native TODO/DONE cycle:

  • CTRL+Enter
    • TODO
    • DONE

Here is what I use for my project tracking:

Note that this means entering an empty block will clear the previous element, and append the next element when no other element is found. Blank bullets only append a text to the block when it is a part of only one keystroke.

By default, empty blocks will cycle to a [[]] tag. To use a #[[]] tag instead, add 'HASH' to the end of the keyboard shortcut like this:

  • CTRL+Enter HASH
    • TODO
    • DONE

If instead of tags, you would like to cycle through raw text, add RAW to the end of the shortcut. Like this:

  • CTRL+Enter RAW
    • TODO
    • DONE

By default, empty blocks will cycle the next entry to the end of the block. To prepend to the block instead, add FRONT to the end of the shortcut. Like this:

  • CTRL+Enter FRONT
    • TODO
    • DONE

Front could combine with some of the other modifiers above. So to fully reproduce Roam's native tag cycle, it would look like this:

    • {{[[TODO]]}}
    • {{[[DONE]]}}

If you change the blocks on the configuration page, the changes will take effect as soon as you navigate away from the blocks.



This extension is brought to you by RoamJS! If you are facing any issues reach out to support@roamjs.com or click on the chat button on the bottom right.

If you get value from using this extension, consider sponsoring RoamJS by clicking on the button below!

A special thanks to those who's contributions also helped make this extension possible:

Other Extensions