Customizing Node Completions

Node selection is achieved via the completing-read interface, typically through org-roam-node-read. The presentation of these nodes are governed by org-roam-node-display-template.

Variable: org-roam-node-display-template

Configures display formatting for Org-roam node.

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.

If you’re using a vertical completion framework, such as Ivy and Selectrum, Org-roam supports the generation of an aligned, tabular completion interface. For example, to include a column for tags up to 10 character widths wide, one can set org-roam-node-display-template as such:

(setq org-roam-node-display-template
      (concat "${title:*} "
              (propertize "${tags:10}" 'face 'org-tag)))