Adding new Libraries/Shapes

[alex98RB]

I'm trying to add some custom shapes/libraries to my self-hosted Draw.io instance. I already have them as XML files.

I saw that it's possible to load custom libraries by hosting the XML file externally and referencing it via a URL. However, I’d like to know if there’s another way to do this — for example, by adding the XML files directly to a specific Draw.io folder or by modifying the Draw.io configuration.

Is that possible? If so, how can it be done?

[davidjgraph]

1. Loading Custom Libraries by URL

You already know this one: you can host the XML file somewhere and load it via URL (File > Open Library from > URL…).
This is the only “official” method in vanilla deployments, as there is no GUI for uploading shape libraries to the app server itself.
2. Adding XML Libraries to the Draw.io Source (Advanced / Custom Builds Only)

If you self-host and can build from source (or modify your deployment), you can add custom libraries so they’re always available to your users.
Here’s how:
A. For the Standalone App (Static Files)

Find or Create a Library Folder:
In your web root, there’s usually a folder like /libs or /static/libraries (depends on how you deployed).
If it doesn’t exist, you can create one (e.g., /custom-libraries).

Place Your XML Files There:

    Copy your .xml library files into this folder.

Reference the Library in the App

    Users can use File > Open Library from > URL… and enter /custom-libraries/my-shapes.xml (relative URL if on same domain).

    Optional:
    If you want your custom libraries to show up in the “+ More Shapes…” dialog by default, you need to modify the app source:

        Edit js/diagramly/Sidebar.js (or the relevant file in your fork):

            Add your custom library URLs to the section where libraries are loaded (search for "Sidebar.prototype.addShapePalette" and "Sidebar.prototype.addMyShapesPalette").

            Example:

            // Add your library here
            this.addShapes('myCustom', 'My Custom Shapes',
              [this.libraryUrl + '/custom-libraries/my-shapes.xml']);

        Rebuild and redeploy your instance.

B. For Docker Deployments

Mount a volume (e.g. /data/custom-libraries) and place your XML files there.

Serve this directory via your web server or directly in the Docker container, so it’s accessible by URL as above.

3. Modifying Default Configuration (Not Officially Supported)

There is no built-in config file where you can list custom libraries. All “default” libraries are hardcoded in the source (see above) or loaded via URL.
However, in Enterprise/White-label builds, there are more config options. If you’re using the open source or regular self-hosted version, editing source is the main way.
4. Packaging as a Plugin (Advanced, For Power Users)

Draw.io supports plugins. You can create a plugin that loads your libraries programmatically and adds them to the sidebar on app load.
Here’s an example plugin snippet:

Draw.loadPlugin(function(ui) {
ui.sidebar.addShapePalette('customLib', 'My Library', true, function(content) {
// Load your XML and add shapes here
// Or simply auto-load a library by URL:
ui.loadLibrary('https://your-server/custom-libraries/my-shapes.xml');
});
});

Place your plugin JS in a location served by your web server and configure draw.io to load it via the ?plugins= URL parameter.
Summary Table
Method User-Friendly Centralized Requires Build/Code Edit Notes
Host XML & load by URL No No No Quick and simple, but per-user action
Add XML to static folder + source edit Yes Yes Yes Requires build step
Plugin auto-load Yes Yes Some JS knowledge Flexible, but more complex
Conclusion

No, you can’t just “drop XML into a folder and have it always show up” without either editing source code or using plugins.

Best option for persistent, organization-wide libraries:

    Either modify the source code to include your libraries,

    Or use a custom plugin to load them automatically.

For quick ad-hoc use:

    Hosting via URL is easiest.