Variable: org-roam-node-display-template

org-roam-node-display-template is a customizable variable defined in org-roam-node.el.

Value

"${title}"

Documentation

Configures display formatting for Org-roam node.

If it is a function, it will be called to format a node. Its result is expected to be a string (potentially with embedded properties).

If it is a string and it will be used as described in org-roam
 (see org-roam-node-display-template)

When it is a string, the following processing is done:

Patterns of form "${field-name:length}" are interpolated based on the current node.

Each "field-name" is replaced with the return value of each corresponding accessor function for org-roam-node, e.g.
"${title}" will be interpolated by the result of
org-roam-node-title. You can also define custom accessors using cl-defmethod. For example, you can define:

  (cl-defmethod org-roam-node-my-title ((node org-roam-node))
    (concat "My " (org-roam-node-title node)))

and then reference it here or in the capture templates as
"${my-title}".

"length" is an optional specifier and declares how many
characters can be used to display the value of the corresponding field. If it's not specified, the field will be inserted as is, i.e. it won't be aligned nor trimmed. If it's an integer, the field will be aligned accordingly and all the exceeding characters will be trimmed out. If it's "*", the field will use as many characters as possible and will be aligned accordingly.

A closure can also be assigned to this variable in which case the closure is evaluated and the return value is used as the template. The closure must evaluate to a valid template string.

When org-roam-node-display-template is a function, the function is expected to return a string, potentially propertized. For example, the following function shows the title and base filename of the node:

(defun my--org-roam-format (node)
  "formats the node"
  (format "%-40s %s"
          (if (org-roam-node-title node)
              (propertize (org-roam-node-title node) 'face 'org-todo)
            "")
          (file-name-nondirectory (org-roam-node-file node))))

(setq org-roam-node-display-template 'my--org-roam-format)

Source Code

;; Defined in ~/.emacs.d/elpa/org-roam-20260224.1637/org-roam-node.el
;;; Options
;;;; Completing-read
(defcustom org-roam-node-display-template "${title}"
  "Configures display formatting for Org-roam node.

If it is a function, it will be called to format a node.
Its result is expected to be a string (potentially with
embedded properties).

If it is a string and it will be used as described in org-roam
 (see org-roam-node-display-template)

When it is a string, the following processing is done:

Patterns of form \"${field-name:length}\" are interpolated based
on the current node.

Each \"field-name\" is replaced with the return value of each
corresponding accessor function for `org-roam-node', e.g.
\"${title}\" will be interpolated by the result of
`org-roam-node-title'. You can also define custom accessors using
`cl-defmethod'. For example, you can define:

  (cl-defmethod org-roam-node-my-title ((node org-roam-node))
    (concat \"My \" (org-roam-node-title node)))

and then reference it here or in the capture templates as
\"${my-title}\".

\"length\" is an optional specifier and declares how many
characters can be used to display the value of the corresponding
field. If it\\='s not specified, the field will be inserted as is,
i.e. it won\\='t be aligned nor trimmed. If it\\='s an integer, the
field will be aligned accordingly and all the exceeding
characters will be trimmed out. If it\\='s \"*\", the field will use
as many characters as possible and will be aligned accordingly.

A closure can also be assigned to this variable in which case the
closure is evaluated and the return value is used as the
template. The closure must evaluate to a valid template string.

When org-roam-node-display-template is a function, the function is
expected to return a string, potentially propertized. For example, the
following function shows the title and base filename of the node:

\(defun my--org-roam-format (node)
  \"formats the node\"
  (format \"%-40s %s\"
          (if (org-roam-node-title node)
              (propertize (org-roam-node-title node) \\='face \\='org-todo)
            \"\")
          (file-name-nondirectory (org-roam-node-file node))))

\(setq org-roam-node-display-template \\='my--org-roam-format)"
  :group 'org-roam
  :type  '(choice string function))