Excalidraw Icon Library

readme.md

Please check out my YouTube video Create a library of your downloaded icons with Excalidraw Automate in Obsidian, it provides a detailed walkthrough of this code.

To save these files into your Vault, either download them, or switch to RAW mode to copy/paste them into your Obsidian Vault. You may need to use CTRL+SHIFT+V to paste.

Icons created by the script are locked in the scene, you can right click them to select and copy them. Locking the eleemnts avoids the need for switching to view mode and ensures the file does not get accidently modified, thus the images in the image library are not actually saved to the image library causing unwanted links in your Vault.

Advanced usage

I use the script with LOCK_ICONS=true; because in this case I won't accidently move items in the image library causing it to save the icons in the file and creating unwanted links in Excalibrain pointing back to the icon library. If you lock icons then you need to right click the selected icon to copy it to the clipboard, however, when you paste the icon to your drawing it will be locked - which is not convenient. For this reason I've also configured an onPaste event handler via the Excalidraw startup script. This automatically unlocks all elements on paste.

ea.onPasteHook = (data) => {
  if(data?.payload?.elements) {
    data.payload.elements.filter(el=>el.locked).forEach(el=>{el.locked = false;});
  }
};

convert script on clipboard to Excalidraw onload script.templater.md

<%* /*

*/
s = await navigator.clipboard.readText();
navigator.clipboard.writeText(s.replaceAll("\n","").replaceAll(/\s{2,}/g," "));
%>

Icon Library Script.md

/*

const FILENAME_FILTER = /^icon -/i;
const KEYWORD_GRABBER = /(?:icon -)?([^-]*)-?/i;
const COLS = 30;
const LOCK_ICONS = true;
const HEIGHT = 180;
const WIDTH = 180;
const TEXTHEIGHT = 40;
const PADDING = 50;

const api = ea.getExcalidrawAPI();
const f = ea.targetView.file;

const {
  zenModeEnabled,
  linkOpacity,
  trayModeEnabled,
  penMode,
  penDetected,
  allowPinchZoom,
  allowWheelZoom,
  pinnedScripts,
  customPens,
  zoom
} = api.getAppState();

api.resetScene();
api.updateScene({
  appState: {
    zenModeEnabled,
    linkOpacity,
    trayModeEnabled,
    penMode,
    penDetected,
    allowPinchZoom,
    allowWheelZoom,
    pinnedScripts,
    customPens,
    zoom
  }
});

const promisePool = async (tasks, concurrency, taskHandler) => {
  const results = [];
  const executing = [];

  for (const task of tasks) {
    const p = Promise.resolve().then(() => taskHandler(task));
    results.push(p);

    if (concurrency <= tasks.length) {
      const e = p.then(() => executing.splice(executing.indexOf(e), 1));
      executing.push(e);
      if (executing.length >= concurrency) {
        await Promise.race(executing);
      }
    }
  }
  return Promise.all(results);
};

const processIcon = async (task) => {
  const row = task.row;
  const rowOfIcons = task.icons;
  const eaTemp = ea.getAPI(ea.targetView);
  for (let col=0;col<rowOfIcons.length;col++) {
    const icon = rowOfIcons[col];
    const id = await eaTemp.addImage(col * (WIDTH + PADDING), row * (HEIGHT + PADDING + TEXTHEIGHT), icon);
    if (f !== eaTemp.targetView.file && eaTemp.targetView?.getViewType?.() !== 'excalidraw') continue;
    if (!id) continue;
  
    const keywords = icon.basename.match(KEYWORD_GRABBER)[1].trim();
    eaTemp.style.verticalAlign = 'top';
    eaTemp.style.textAlign = 'center';
    eaTemp.style.fontSize = 12;
  
    const el = eaTemp.getElement(id);
    let ratio = el.width / WIDTH;
    if (el.height / ratio > HEIGHT) ratio = el.height / HEIGHT;
    el.width = el.width / ratio;
    el.height = el.height / ratio;
    el.locked = LOCK_ICONS;
  
    eaTemp.style.strokeColor = 'black';
    const labelID = eaTemp.addText(col * (WIDTH + PADDING) - PADDING / 2 + 10, row * (HEIGHT + PADDING + TEXTHEIGHT) + HEIGHT + PADDING / 2 - 10, keywords, {
      width: WIDTH + PADDING - 20,
      height: TEXTHEIGHT - 20,
      textAlign: 'center',
      textVerticalAlign: 'top',
      autoResize: false,
    });
    eaTemp.getElement(labelID).locked = LOCK_ICONS;
  }

  await eaTemp.addElementsToView(false, false, false);
  eaTemp.targetView.clearDirty();
  eaTemp.destroy();
};

const icons = app.vault.getFiles()
  .filter(f => (f.extension !== 'md' || ea.isExcalidrawFile(f)) && f.basename.toLowerCase().match(FILENAME_FILTER))
  .sort((a, b) => a.basename.toLowerCase() < b.basename.toLowerCase() ? -1 : 1);
const numRows = Math.ceil(icons.length / COLS);
const iconsInRows = [];
for (let i = 0; i < numRows; i++) {
  iconsInRows.push({icons: icons.slice(i * COLS, (i + 1) * COLS), row:i});
};

const concurrency = 3;
await promisePool(iconsInRows, concurrency, processIcon);

ea.targetView.clearDirty();
api.zoomToFit();
api.updateContainerSize(ea.getViewElements().filter(el => el.type === 'rectangle'));

Icon Library.excalidraw.md

excalidraw-plugin

parsed

excalidraw-onload-script

const FILENAME_FILTER = /^icon -/i;const KEYWORD_GRABBER = /(?:icon -)?([^-]*)-?/i;const COLS = 30;const LOCK_ICONS = false;const HEIGHT = 180;const WIDTH = 180;const TEXTHEIGHT = 40;const PADDING = 50;const api = ea.getExcalidrawAPI();const f = ea.targetView.file;const { zenModeEnabled, linkOpacity, trayModeEnabled, penMode, penDetected, allowPinchZoom, allowWheelZoom, pinnedScripts, customPens, zoom} = api.getAppState();api.resetScene();api.updateScene({ appState: { zenModeEnabled, linkOpacity, trayModeEnabled, penMode, penDetected, allowPinchZoom, allowWheelZoom, pinnedScripts, customPens, zoom }});const promisePool = async (tasks, concurrency, taskHandler) => { const results = []; const executing = []; for (const task of tasks) { const p = Promise.resolve().then(() => taskHandler(task)); results.push(p); if (concurrency <= tasks.length) { const e = p.then(() => executing.splice(executing.indexOf(e), 1)); executing.push(e); if (executing.length >= concurrency) { await Promise.race(executing); } } } return Promise.all(results);};const processIcon = async (task) => { const row = task.row; const rowOfIcons = task.icons; const eaTemp = ea.getAPI(ea.targetView); for (let col=0;col<rowOfIcons.length;col++) { const icon = rowOfIcons[col]; const id = await eaTemp.addImage(col * (WIDTH + PADDING), row * (HEIGHT + PADDING + TEXTHEIGHT), icon); if (f !== eaTemp.targetView.file && eaTemp.targetView?.getViewType?.() !== 'excalidraw') continue; if (!id) continue; const keywords = icon.basename.match(KEYWORD_GRABBER)[1].trim(); eaTemp.style.verticalAlign = 'top'; eaTemp.style.textAlign = 'center'; eaTemp.style.fontSize = 12; const el = eaTemp.getElement(id); let ratio = el.width / WIDTH; if (el.height / ratio > HEIGHT) ratio = el.height / HEIGHT; el.width = el.width / ratio; el.height = el.height / ratio; el.locked = LOCK_ICONS; eaTemp.style.strokeColor = 'black'; const labelID = eaTemp.addText(col * (WIDTH + PADDING) - PADDING / 2 + 10, row * (HEIGHT + PADDING + TEXTHEIGHT) + HEIGHT + PADDING / 2 - 10, keywords, { width: WIDTH + PADDING - 20, height: TEXTHEIGHT - 20, textAlign: 'center', textVerticalAlign: 'top', autoResize: false, }); eaTemp.getElement(labelID).locked = LOCK_ICONS; } await eaTemp.addElementsToView(false, false, false); eaTemp.targetView.clearDirty(); eaTemp.destroy();};const icons = app.vault.getFiles() .filter(f => (f.extension !== 'md' || ea.isExcalidrawFile(f)) && f.basename.toLowerCase().match(FILENAME_FILTER)) .sort((a, b) => a.basename.toLowerCase() < b.basename.toLowerCase() ? -1 : 1);const numRows = Math.ceil(icons.length / COLS);const iconsInRows = [];for (let i = 0; i < numRows; i++) { iconsInRows.push({icons: icons.slice(i * COLS, (i + 1) * COLS), row:i});};const concurrency = 3;await promisePool(iconsInRows, concurrency, processIcon);ea.targetView.clearDirty();api.zoomToFit();api.updateContainerSize(ea.getViewElements().filter(el => el.type === 'rectangle'));

#exclude

Excalidraw Data

Text Elements

%%

Drawing

N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebQBWbR4aOiCEfQQOKGZuAG0AXX4IXDg4AGUoqHFUUDBIdXTqiCJlaRS6hkIECgAhXGwAa2VSYQ5iAGE2fDZSbggAYgAzZZX2

yGwRQKyASSr9CpGBhEnp2Yl5gEYEK6u1iA3SLahd9L7B4dGJqZm5qHIOZhwXBPO4PJ4vfQAMUI+HwFRgwTmgg8oM2mWeewObCOAHUSOpuHxwOs0TtMX9sQh4YiJMiSKjHuiIQAlYStDjhHJoC78EmMsnpADyQOwahg3AuAAZJbz7qSMelIZwoJDcPoYeK0PFZWCmXslVkyoQjNUeDLiXL+Qr9AAVLBQACCLS4EmCiygDPB5OBjsebAokhCxG4HCE

sJ18ohAFExg6/QGg3NgSMqBGrRC4ymbfAmiMhGM7sxsCNYQANbjmjpFkv4ACaFdlRjYBm4tQ69AIQmqF2JAF80170qz88QOcwueg8wXZcMSEaTYTK5BZ8QKgg4NxtRaVwBZNjEBAx3CaYLBtCLAhhGekEgnH5oNuQHpTM/oebYD+ftaQZkIZRh4E5nmBB4hAkCID7Ad0SxI5hSgdgARDMN8FlRZyAyX8xiYQgOGUVtiUgTJj1Pbg/i7Xl1iIDc0D

IhAKIgDg1WqWj6OEKAiA5UjSC7SCLTsAArBBsGyMpGLgPcDyPE8EFfC98CvC1+ngxgbWbfB8LqeocyRNJhIQ785WYKADGzRAkPDAjmjYQYZO4OSFM05pQkdPSVLU8z8D7cB+zoRYYXCVtexAXsgA

%%

so in both cases you see an Excalidraw drawing, but one has 18 images and the other 90?

did you modify the filter at the beginning of the code?

regarding learning Obsidian.js, I think small projects like this one are the best way.

one easy way to debug is to insert console.log(variable_name); at key points to see the value of variables.

another approach is to insert debugger; command in the code. doing this the script execution will stop when the program gets to that point (but only if developer console is open).

Ok, now that's kind of weird. I inserted ' console.log(icons);' after the first command, now it works fine and I can see the (correct) number of icons in the console AND in the drawing.
Removed the console.log command and it still works perfectly.
I have no idea, what went wrong in my first attempts. And I promise, I didn't change anything (at least not knowingly). 🙈

So, thank you for your effort to help out and again 1.000++ thanks for your great plugins and videos!!! 🙏

Thank you for your great video and script. As always, I am on my Samsung tablet with Android. I put the script in the Script folder and I copied the file into my vault. Then I added the word 'Icon' just to a few images and the imported file loaded a library of the images. Then I renamed altogether around 30 files. After that I always get a message and button "Scroll back to content", but the canvas remains white. I cannot debug, because I just have the tablet and cannot start the developer console. And I am also not a programmer, just know very roughly how to debug. Any suggestions? Is the functionality limited on Android devices?

Because the script wasn't working, I moved most images to another folder, but the script still didn't work. I reinstalled the script and I recreated the file from the original source, but still didn't change for the better.

But knowledge discovery via Icons is something I were totally missing before and is quite interesting. And the icons add an additional input to remember and connect the information anyway.

Update: I activated the script 'Zoom to fit selected elements' and there was my Icon library again. When the script wasn't showing anything, zoom factor display some strange symbols as well. Probably, the adding of the many icons lead to a kind of confusion.

I counted 24 files with 'icon' in file name (using Obsidian search) and most of them are displayed in the Icon Library, but not all.

By the way, in your video you opened the Icon Library in a kind of side pane. My Icon Library is more like a normal excalidraw file with icons in it. Am I doing s.th. wrong here? Or, again, is the functionality limited on Android devices?

Is there a filter option to point the script to a specific directory? I migrated from Joplin to Obsidian and I noticed it catches file with icon in the name. Even after changing it to "icon-"

Thank you very much for the icon library and the script.
The icon library works fine but I have some questions about the display of the icon library on your video:

1. the name "Icon Library" does not display the ".excalibrain" as on mine (number 1)
2. the excalidraw or image icons is on the left of the panel (number 2 and 3)
3. on your panel, in the video, we also see, on the right of the "Icon Library", a number (number 4 and 5) and two opposite arrows (number 6 and 7).
   

I assume this is only a setting in Obsidian or in the Excalidraw setting but I can't find it.

Thanks for your work !!!!

I did not notice these comments here:

• The filter is now set for files beginning with "Icon -" or "icon -". You can change the filter by changing the FILENAME_FILTER=/^icon -/i; regular expression at the beginning of the script
• @OXiOSDev: "Icon Library" vs. "Icon Library.excalidraw" is just a difference in filenames. Simply delete the ".excalidraw" part of the filename. It is not needed. You can set the default file naming in Excalidraw settings.
• @JuergenKaettnis My library is also just an excalidraw file. You can drag any file (markdown, excalidraw, anything) to the side pane and pin it there.
• @OXiOSDev regarding #3: I think those come from the PaneRelief plugin.

@zsviczian Thank you very much for your answers

whein i install this script its not working.
so i debug my console, the line below

if(f!==ea.targetView.file && ea.targetView?.getViewType?.()!=="excalidraw") return;

at this line code error said return is not defined.

do you know what meaning is?

@LEEJOOPIL
Did you download the .md file following this link? Icon Library.excalidraw.md

I think the error message says return is not defined.

I used lcon library.excalidraw.md but still not working...
still return is not defined..

Hi! Any way to automatically set "invert colors"?

I had the same issue as LEEJOOPIL.
Added the script to a new installation with only the bare minimum of community plugins.
The error is "Uncaught SyntaxError: Illegal return statement" and points to this code: if(f!==ea.targetView.file && ea.targetView?.getViewType?.()!=="excalidraw") return;
Removing that line doesn't help either.

This sounds like a plugin is automatically modifying files, e.g. adding some metadata, etc, that creates a syntax error.
Disable other plugins. Delete and re-add the script. Is the error still happening?

Please share the output of command palette "Debug info" so I can see your definition of bare minimum.

Debug Info:
SYSTEM INFO:
Obsidian version: v1.5.12
Installer version: v1.5.3
Operating system: Windows 10 Home 10.0.22631
Login status: not logged in
Insider build toggle: off
Live preview: on
Base theme: dark
Community theme: AnuPpuccin v1.4.5
Snippets enabled: 3
Restricted mode: off
Plugins installed: 1
Plugins enabled: 1
1: Excalidraw v2.2.4

RECOMMENDATIONS:
Custom theme and snippets: for cosmetic issues, please first try updating your theme and disabling your snippets. If still not fixed, please try to make the issue happen in the Sandbox Vault or disable community theme and snippets.
Community plugins: for bugs, please first try updating all your plugins to latest. If still not fixed, please try to make the issue happen in the Sandbox Vault or disable community plugins.

I deleted all plugins except Excalidraw.
Deleted the Icon Library script and Icon Library.md from the vault.
Copied the raw Icon Library script.
Created a new empty drawing
opened the Console
added ea=excalidraw.automate
ea.setview('first')
pasted in the icon library script
and still the same error.

PixPin_2026-01-27_09-47-15.mp4

Hey， My Teacher，
I can already display all the base icons in the sidebar, and I can also retrieve them, but when I use them, it is troublesome. I drag them directly to excalidraw to display embedded links. I suspect that it is "convert script on clipboard to Excalidraw onload script.templateer.md". The reason why this is not set correctly, how should I set it?