How to Render Background Image for Diagram in the JavaScript Diagram?

This article explains how to render a background image at a specified offset in the JavaScript Diagram component. By default, the diagram’s background image is set using the pageSettings property, which fills the entire page area based on the defined width and height. However, this approach does not support setting a custom offset position for the background image.

To overcome this limitation, we can simulate a background image with an offset by rendering an image node instead. This image node is configured to appear in the background by setting its zIndex to zero, and we disable all interactive constraints so it behaves like a static background element. The image is positioned using offsetX and offsetY to control its exact placement within the diagram space.

Refer to the following sample code where we define a node with an image shape. This node is placed at offsetX: 350 and offsetY: 350, with a width and height of 700. The image is sourced from a URL and will appear as the background of the diagram.

var node = {
   id: 'node1',
   offsetX: 350,
   offsetY: 350,
   width: 700,
   height: 700,
   shape: {
       type: 'Image',
       source: 'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQEg7hGf67QktC2fSWbPJWv1XZ8QgKAIqmIsw&s'
   }
}; 

In the getNodeDefaults function, we check for the background image node by its ID and disable its constraints using ~ej.diagrams.NodeConstraints.Default, which ensures it cannot be selected, dragged, or resized. We also set its zIndex to zero so it renders beneath all other elements in the diagram. For other nodes, you can define custom dimensions as needed.

getNodeDefaults: function(node) {
    if (node.id === 'node1') {
        node.constraints = ~ej.diagrams.NodeConstraints.Default;
        node.zIndex = 0;
    } else {
        node.height = 100;
        node.width = 100;
    }
    return node;
} 

This method effectively creates a background image with custom offset positioning, offering more flexibility than the built-in pageSettings.background approach. It is especially useful when building custom layouts or needing visual alignment that differs from the default page area.

Refer to the working sample for additional details and implementation: Sample

Conclusion

We hope you enjoyed learning how to render a background image for a diagram at a specified offset in JavaScript Diagram.

You can refer to our JavaScript Diagram feature tour page to know about its other groundbreaking feature representations and documentation, and how to quickly get started for configuration specifications. You can also explore our JavaScript Diagram example to understand how to create and manipulate data.

For current customers, you can check out our components from the License and Downloads page. If you are new to Syncfusion®, you can try our 30-day free trial to check out our other controls.

If you have any queries or require clarifications, please let us know in the comments section below. You can also contact us through our support forums, BoldDesk Support, or feedback portal. We are always happy to assist you!