Work with custom links

Custom links can be used where hyperlinks and links to pages are allowed, namely on shapes and (parts of) text labels.

Note: This feature is not available in draw.io for Confluence Server.

  1. Right-click on a shape, then select Edit Link, or select the shape (cell) and use the keyboard shortcut Alt+Shift+L.
  2. Enter the custom link in the first text field.
    Edit the custom link

The format for custom links is: data:action/json,{"actions":[actions]} where actions is a comma-separated list of JavaScript objects (JSON) with the following possible keys:

  • "open": string - opens a standard or custom link (including page links)
  • "toggle"/"show"/"hide"/"highlight": cellset - toggles, shows, hides or highlights the given cells
  • "select": cellset - selects the given cells if the diagram is editable
  • "scroll": cellset - scrolls to the first cell in the given celllset
  • "viewbox": {"x": int, "y": int, "width": int, "height": int}

If no scroll action is specified, then the first cell of the select or highlight action is scrolled to be visible (select has precedence).

For highlight, a color (string), duration (number in milliseconds) and opacity (1-100) may be specified.

A cellset is an array of cell IDs or tags or both, e.g. {"cells": ["id1", "id2"], "tags": ["tag1", "tag2"]}.

  • If multiple tags are used, then the cells that have all tags are selected (AND).
  • To toggle cells with either tag1 or tag2, use multiple toggle actions instead.
  • To specify all cells, use "cells": ["*"].
  • To specify all cells with a tag, use "tags": [] (empty array).

Note that when tags are used to toggle cells, it will change the current visible state of the cell.

Example 1

data:action/json,{"actions":[{"toggle": {"cells": ["5", "7"]}}]}

This shows or hides the cells with ID 5 and ID 7, depending on their current visible state. See this example in diagrams.net.

Example 2

data:action/json,{"actions":[{"open": "data:page/id,1"},{"highlight":{"cells":["2"],"opacity":100, "color": "red"}}]}

This opens the page with ID 1 and then highlights the cell with ID 2 in red with an opacity of 100%. [See this example in diagrams.net](

Example 3

data:action/json,{"actions":[{"show": {"tags": []}},{"hide": {"tags": ["pipe", "water"]}}]}

This shows all cells with a tag and then hides all cells with the tags pipe and water.

Find the ID of a shape (cell), page, or layer

  • Shapes: Right-click on a shape, select Edit Data, or select a shape then use the keyboard shortcut Ctrl+M on Windows or Cmd+M on macOS.
    Edit Data on a shape or a page will show you its ID
  • Pages: Make sure nothing is selected to get the ID of a page, then press Ctrl+M on Windows or Cmd+M on macOS.
  • Layers: Select View > Layers from the menu to see the Layers dialog. Click on the three vertical dots (Edit Data) to see the ID of the selected layer.
    Click Edit Data in the Layers dialog to see the ID of a selected layer

When the diagram is viewed in the editor, the custom links are shown in a tooltip when you select the shape with the label Action. When you click on the link, the visible state of the cells is updated and the diagram is saved.

If realtime collaboration is used, the visible state of the cells is updated in all connected diagrams.

When viewed in the lightbox or in read-only mode, when you click on the shape or text, the visible state of the cells will change, but the change will not be saved.

While we’re working on a user interface to create and edit custom links, please use this tool to more easily create custom links.