Roam Research Docs · Developer documentation

roam/render

• Getting Started
  • roam/render is a way to write custom inline components like Roam's {{}}
  • roam/render components can be written in clojurescript, JavaScript, or jsx
    • currently clojurescript has the best support
  • To use roam/render, create a clojure (or js or jsx) code block, copy a reference to the block, create a new bock and type {{roam/render: ((<block-reference>))}}.
    • like this

    • (defn hello-world []
        [:div
         {:style {:color "blue"}}
         "hello world"])

    • {{roam/render: ((uD2gB7Qvh))}}
    • {{roam/render:

      (defn hello-world []
        [:div
         {:style {:color "blue"}}
         "hello world"])

      }}
      • If you haven't enabled custom components yet, click the link above to turn it on in settings
  • In clojurescript, you have access to the Roam Clojurescript API as well as the Roam Alpha API (although the clojurescript API is mostly a copy / paste of the roam alpha)
    • You can also use Available Libraries from the window object, some of these are wrapped in a namespace like blueprint for ease of use, but you may use the others by just getting them from the window object
  • In js and jsx, you will only have access to the Roam Alpha API and Available Libraries
  • The best way to get started is to try out a few of our Examples below, and read up on the API pages to see the functions available to you.
  • Don't hesitate to Contact Us with any questions or Feature Requests you have
• Resources
  • Roam Clojurescript API
  • A closer look at roam/render by Zsolt Viczian #Community #Article
  • Creating Reagent Components
• Examples
  • clojurescript
    • Hello World
      • Code::

        • (ns dev-docs.hello-world)
          
          (defn main []
            [:h1 "Hello world from CLJS"])

      • Output::
        • {{roam/render: ((ltUELYamK))}}
        • {{roam/render:

          (ns dev-docs.hello-world)
          
          (defn main []
            [:h1 "Hello world from CLJS"])

          }}
    • Argument Parsing #Important Note
      • Code::

        • (defn main-args-1 [{:keys [block-uid]} & args]
            [:div
             [:h1 (str block-uid ": args: ")]
             [:ul
              (for [arg args]
                [:li (pr-str arg)])]])

      • Output::
        • {{roam/render:

          (defn main-args-1 [{:keys [block-uid]} & args]
            [:div
             [:h1 (str block-uid ": args: ")]
             [:ul
              (for [arg args]
                [:li (pr-str arg)])]])

          "arg-1" 2 test args test block args}}
    • Displaying strings with Roam's markdown parser
      • Code::

        • (ns dev-docs.parse-example
            (:require [roam.util :refer [parse]]))
          
          (defn main []
            [parse "**apple** __banana__ [[test-parse]]"])

      • Output::
        • {{[[roam/render]]: ((uUxqZ4Bwb))}}
        • {{roam/render:

          (ns dev-docs.parse-example
            (:require [roam.util :refer [parse]]))
          
          (defn main []
            [parse "**apple** __banana__ [[test-parse]]"])

          }}
    • Rendering latex equations and splitting code files into multiple blocks #Important Note
      • Description::
        • Code for a roam/render component does not have to live inside a single block. Roam will look for sibling code blocks to the block referenced, concatenate those together and evaluate everything.
          • Only sibling blocks are part of the same file, not children blocks
        • The block that you referenced will be the function that is run in the roam/render component
        • You can even intersperse the components between the code blocks. This is particularly useful for explorable explanation style tutorials

      • (ns katex-example
          (:require
           [reagent.core :as r]
           [roam.katex :as katex]))

      • (defn inline-example []
          (let [*val (r/atom "")]
            (fn []
              [:div
               [:input
                {:value @*val
                 :on-change #(reset! *val (.. % -target -value))}]
               [:div
                "Inline katex: "
                [katex/inline
                @*val]]])))

      • {{roam/render: ((ydU0Dpoq_))}}
      • {{roam/render:

        (defn inline-example []
          (let [*val (r/atom "")]
            (fn []
              [:div
               [:input
                {:value @*val
                 :on-change #(reset! *val (.. % -target -value))}]
               [:div
                "Inline katex: "
                [katex/inline
                @*val]]])))

        }}

      • (defn block-example []
          (let [*val (r/atom "")]
            (fn []
              [:div
               [:input
                {:value @*val
                 :on-change #(reset! *val (.. % -target -value))}]
               [:div
                "Block katex: "
                [katex/block
                @*val]]])))

      • {{roam/render: ((cF6Xzv0bd))}}
      • {{roam/render:

        (defn block-example []
          (let [*val (r/atom "")]
            (fn []
              [:div
               [:input
                {:value @*val
                 :on-change #(reset! *val (.. % -target -value))}]
               [:div
                "Block katex: "
                [katex/block
                @*val]]])))

        }}
    • Get all blocks on a page that reference another page #Important Note
      • Description::
        • roam.datascript.reactive is identical to roam.datascript except that every function returns a reagent reactions, which updates when the result of the query or pull changes.
        • Take note of the use of r/with-let below. Any time you use r/atom or any function from roam.datascript.reactive you should define it inside of a form 2 or form 3 component
          • Not using form 2 or form 3 components can lead to unnecessary rerenders and even infinite loops!
      • Code::

        • (ns dev-docs.get-page-blocks-with-tag
            (:require
             [roam.datascript.reactive :as dr]
             [roam.util :as u]
             [roam.ui.main-window :as main-window]
             [reagent.core :as r]))

        • (defn track-blocks-with-tag-on-page [tag-uid page-uid]
            (dr/q
              '[:find (pull ?page-block [:block/uid :block/string])
                :in $ ?tag-uid ?page-uid
                :where
                [?tag-e :block/uid ?tag-uid]
                [?page-e :block/uid ?page-uid]
                [?page-block :block/page ?page-e]
                [?page-block :block/refs ?tag-e]]
              tag-uid
              page-uid))

        • (defn main [{:keys [block-uid]} [_ tag-uid] [_ page-uid]]
            (r/with-let [*blocks (track-blocks-with-tag-on-page tag-uid page-uid)]
              (into [:ul]
                (keep (fn [[{:keys [block/string block/uid]}]]
                        (when (not= uid block-uid)
                          [:li
                           {:style {:cursor "pointer"}
                            :on-click (fn []
                                        (main-window/open-block
                                          {:block {:uid uid}}))}
                           [u/parse string]])))
                @*blocks)))

      • Output::
        • {{roam/render: ((o5wWBZxdg))}}
        • {{roam/render: Code:: Important Note roam/render}}
    • List public vars of a namespace using ns-publics
      • Description::
        • ns-publics can be useful when trying to figure out what a namespace exports. In this example we pass in a ns-name and display all of the functions / vars in a namespace
      • Code::

        • (ns ns-vars-lister
            (:require [reagent.core]))
          
          (defn main [{:keys [block-uid]} ns-name]
            (let [ns-symbol (symbol ns-name)]
              [:div [:div
                     [:h3 "public vars of ns: " (pr-str ns-symbol)]
                     [:div (map
                            (fn [n] [:div (pr-str n)])
                            (->> (ns-publics ns-symbol)
                                 (seq)
                                 (sort)))]]]))

      • Output::
        • {{roam/render: ((r47yvGHoi)) "reagent.core"}}
        • {{roam/render:

          (ns ns-vars-lister
            (:require [reagent.core]))
          
          (defn main [{:keys [block-uid]} ns-name]
            (let [ns-symbol (symbol ns-name)]
              [:div [:div
                     [:h3 "public vars of ns: " (pr-str ns-symbol)]
                     [:div (map
                            (fn [n] [:div (pr-str n)])
                            (->> (ns-publics ns-symbol)
                                 (seq)
                                 (sort)))]]]))

          "reagent.core"}}
    • instaparse.core readme example
      • Code::

        • (ns developer-documentation.test-instaparse.1
            (:require 
             [reagent.core :as r]
             [roam.block :as block]
             [blueprintjs.core :as bp-core]
             [cljs.pprint :refer [pprint]]
             [instaparse.core :as insta]))
          
          (def as-and-bs
            (insta/parser
              "S = AB*
               AB = A B
               A = 'a'+
               B = 'b'+"))
          
          (defn main [{:keys [block-uid]}]
            [:button 
             {:on-click 
              #(pprint (as-and-bs "aaaaabbbaaaabb"))} "Click me!"])

      • Output::
        • {{[[roam/render]]: ((6DXyUOHhH))}}
        • {{roam/render:

          (ns developer-documentation.test-instaparse.1
            (:require 
             [reagent.core :as r]
             [roam.block :as block]
             [blueprintjs.core :as bp-core]
             [cljs.pprint :refer [pprint]]
             [instaparse.core :as insta]))
          
          (def as-and-bs
            (insta/parser
              "S = AB*
               AB = A B
               A = 'a'+
               B = 'b'+"))
          
          (defn main [{:keys [block-uid]}]
            [:button 
             {:on-click 
              #(pprint (as-and-bs "aaaaabbbaaaabb"))} "Click me!"])

          }} (check console after clicking)
    • Click me template using blueprintjs.core
      • Code::

        • (ns dev-docs.test-blueprint.1
            (:require 
             [reagent.core :as r]
             [roam.block :as block]
             [blueprintjs.core :as bp-core]))
          
          (defonce bp3-button (r/adapt-react-class bp-core/Button))
          
          (defn main [{:keys [block-uid]}]
            [bp3-button 
             {:large true
              :disabled true
              :icon "history"
              :on-click 
              #(block/update 
                {:block {:uid block-uid 
                         :string "Hello world!"}})} 
             "Click me!"])

      • Output::
        • {{[[roam/render]]: ((O1iyYWZsW))}}
        • {{roam/render:

          (ns dev-docs.test-blueprint.1
            (:require 
             [reagent.core :as r]
             [roam.block :as block]
             [blueprintjs.core :as bp-core]))
          
          (defonce bp3-button (r/adapt-react-class bp-core/Button))
          
          (defn main [{:keys [block-uid]}]
            [bp3-button 
             {:large true
              :disabled true
              :icon "history"
              :on-click 
              #(block/update 
                {:block {:uid block-uid 
                         :string "Hello world!"}})} 
             "Click me!"])

          }}
    • Load modules and css from npm #experimental
      • You can load any package from npm simply by requiring it.
        • Unfortunately many packages will not work because they will load their own version of React
        • Some common errors when this happens are
          • 
      • {{[[roam/render]]: ((Hcuh0h3ys))}}
      • {{roam/render:

        (ns render-examples.confetti
          (:require
           [reagent.core :as r]
           ;; require any package from npm
           ["canvas-confetti" :as confetti]
           ;; require a specific version of a package
           ["[email protected]" :refer [AwesomeButton]]
           ;; require css for an npm package
           ["[email protected]/dist/styles.css"]
           ;; alternatively you could use CDN of your choice by providing a full URL
           ;; internally we use esm.sh to load npm packages
           #_["https://cdn.skypack.dev/[email protected]/dist/styles.css"]))
        
        (def awesome-button (r/adapt-react-class AwesomeButton))
        
        (defn main []
          [:div
           [awesome-button
            {:type "primary"
             ;; be careful, some packages export default, which is not auto processed by cljs as it is in js
             ;; when in doubt, print out what your var is
             :onPress #(confetti/default)}
            "Fun!"]])

        }}

        • (ns render-examples.confetti
            (:require
             [reagent.core :as r]
             ;; require any package from npm
             ["canvas-confetti" :as confetti]
             ;; require a specific version of a package
             ["[email protected]" :refer [AwesomeButton]]
             ;; require css for an npm package
             ["[email protected]/dist/styles.css"]
             ;; alternatively you could use CDN of your choice by providing a full URL
             ;; internally we use esm.sh to load npm packages
             #_["https://cdn.skypack.dev/[email protected]/dist/styles.css"]))
          
          (def awesome-button (r/adapt-react-class AwesomeButton))
          
          (defn main []
            [:div
             [awesome-button
              {:type "primary"
               ;; be careful, some packages export default, which is not auto processed by cljs as it is in js
               ;; when in doubt, print out what your var is
               :onPress #(confetti/default)}
              "Fun!"]])

  • jsx
    • Hello World
      • Code::

        • function main2 () {
            return <h1>Hello world from JSX</h1>
          }

      • Output::
        • {{roam/render: ((hlu_MicTh))}}
        • {{roam/render:

          function main2 () {
            return <h1>Hello world from JSX</h1>
          }

          }}
    • Argument Parsing
      • Code::

        • function mainArgs3({args}) {
            let block, actualArgs;
            [block, ...actualArgs] = args;
            const listArgs = actualArgs.map(
              (arg) => <li>{arg.toString()}</li>
            );
            return (
              <div>
                <h1>
                  {block["block-uid"]}: args:
                </h1>
                <ul>{listArgs}</ul>
              </div>
            );
          }

      • Output::
        • {{roam/render:

          function mainArgs3({args}) {
            let block, actualArgs;
            [block, ...actualArgs] = args;
            const listArgs = actualArgs.map(
              (arg) => <li>{arg.toString()}</li>
            );
            return (
              <div>
                <h1>
                  {block["block-uid"]}: args:
                </h1>
                <ul>{listArgs}</ul>
              </div>
            );
          }

          "arg-1" 2 test args test block args}}
  • JavaScript
    • It's a better idea to just use jsx instead of raw javascript unless you run into some bug. Jsx examples will work with javascript if you convert the jsx syntax to create element
    • Hello World
      • Code::

        • function main1() {
            return React.createElement('h1', {}, 'Hello world from JS');
          }

      • Output::
        • {{roam/render: ((qfcNnWG7J))}}
        • {{roam/render:

          function main1() {
            return React.createElement('h1', {}, 'Hello world from JS');
          }

          }}
    • Argument Parsing
      • Code::

        • function mainArgs2({args}) {
            let block, actualArgs;
            [block, ...actualArgs] = args;
            console.log(block, actualArgs)
            return React.createElement('div', {}, "Hello");
          }

      • Output::
        • {{roam/render: ((zJX0nWRLX)) "arg-1" 2 [[test args]] ((7lN0hyokF))}}
        • {{roam/render:

          function mainArgs2({args}) {
            let block, actualArgs;
            [block, ...actualArgs] = args;
            console.log(block, actualArgs)
            return React.createElement('div', {}, "Hello");
          }

          "arg-1" 2 test args test block args}}
          • just did a console log here. Check the JSX example for a better example
• FAQ
  • How to pass arguments into components?
    • When you build anything but the simplest roam/render components, you run into the need to be able to take arguments. Similarly, it is a common use case that you need to know where (which block) your component is situated.
    • The first argument to your component is always a context map
      • Currently this map only contains the block-uid of the block the component is rendered inside of (not the uid of the code block!)
      • {:block-uid "KjccJWpBM"} (clojure) or {"block-uid": "KjccJWpBM"} (js)
    • To pass in additional arguments, add them after the code block uid, like this
      • {{roam/render: ((KjccJWpBM)) "arg-1" 2}}
      • This render component would run the code in the block with block-uid KjccJWpBM and pass the arguments "arg-1" and 2
        • Roam automatically parses these into a string and a number (This is done with the cljs.reader)
      • These all would be automatically passed into the last function in the code block. Specifically, the function would receive the following arguments
        • {:block-uid "KjccJWpBM"} (clojure) or {"block-uid": "KjccJWpBM"} (js)
        • "arg-1"
        • 2
    • Roam will automatically parse and resolve page and block references passed in
      • {{roam/render: ((KjccJWpBM)) [[test args]] ((7lN0hyokF))}}
      • Args
        • {:block-uid "KjccJWpBM"} (clojure) or {"block-uid": "KjccJWpBM"} (js)
        • [:block/uid "MFSo6yX_Q"] (clojure) or ['uid', 'MFSo6yX_Q'] (js)
        • [:block/uid "7lN0hyokF"] or ['uid', '7lN0hyokF'] (js)
    • Examples
      • clojurescript
        • Argument Parsing #Important Note
          • Code::

            • (defn main-args-1 [{:keys [block-uid]} & args]
                [:div
                 [:h1 (str block-uid ": args: ")]
                 [:ul
                  (for [arg args]
                    [:li (pr-str arg)])]])

          • Output::
            • {{roam/render:

              (defn main-args-1 [{:keys [block-uid]} & args]
                [:div
                 [:h1 (str block-uid ": args: ")]
                 [:ul
                  (for [arg args]
                    [:li (pr-str arg)])]])

              "arg-1" 2 test args test block args}}
      • JS
        • Argument Parsing
          • Code::

            • function mainArgs2({args}) {
                let block, actualArgs;
                [block, ...actualArgs] = args;
                console.log(block, actualArgs)
                return React.createElement('div', {}, "Hello");
              }

          • Output::
            • {{roam/render: ((zJX0nWRLX)) "arg-1" 2 [[test args]] ((7lN0hyokF))}}
            • {{roam/render:

              function mainArgs2({args}) {
                let block, actualArgs;
                [block, ...actualArgs] = args;
                console.log(block, actualArgs)
                return React.createElement('div', {}, "Hello");
              }

              "arg-1" 2 test args test block args}}
              • just did a console log here. Check the JSX example for a better example
      • JSX
        • Argument Parsing
          • Code::

            • function mainArgs3({args}) {
                let block, actualArgs;
                [block, ...actualArgs] = args;
                const listArgs = actualArgs.map(
                  (arg) => <li>{arg.toString()}</li>
                );
                return (
                  <div>
                    <h1>
                      {block["block-uid"]}: args:
                    </h1>
                    <ul>{listArgs}</ul>
                  </div>
                );
              }

          • Output::
            • {{roam/render:

              function mainArgs3({args}) {
                let block, actualArgs;
                [block, ...actualArgs] = args;
                const listArgs = actualArgs.map(
                  (arg) => <li>{arg.toString()}</li>
                );
                return (
                  <div>
                    <h1>
                      {block["block-uid"]}: args:
                    </h1>
                    <ul>{listArgs}</ul>
                  </div>
                );
              }

              "arg-1" 2 test args test block args}}
  • How are the code blocks evaluated?
    • In clojurescript we use SCI to parse and evaluate files
    • jsx is converted to js with babel and then evaluated the same as js
    • JavaScript is evaluated with eval

markdown version · view in Roam Research · exported 2026-07-03