Blazor Diagram Overview

The Blazor Diagram component displays relationships between objects or concepts, for example, hierachy. The Diagram provides a variety of built-in shapes and horizontal and vertical layouts. The connections between the graph nodes can be one-directional, bi-directional, or non-directional. The component allows customizing the size, position, and geometric form of its elements.

Diagram Elements

The Diagram component UI consists of the following elements:

• Shapes are the Diagram nodes (vertices). Shapes can display text and images.
• Connectors are the 5 dots that appear on the Shape boundaries and center on hover. Users can grab a connector and drag it to another shape to create a new connection.
• Connections are the links (edges) between Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
• Caps are the connection ends. The connections are directional, so each connection has a start cap and end cap.
• Selection handles are the additional visual elements that appear at both ends of a connection when it is selected. The handles appear on top of the caps and connectors.
• Components are groups (subgraphs) of connected shapes within the same Diagram that are not linked to each other. The Diagram provides [dedicated settings for such scenarios].

Note that difference between caps, connectors, and selection handles. Although they can overlap visually, connectors belong to a shape, while caps and selection handles belong to a connection.

Creating Blazor Diagram

There are two ways to define and display a Diagram:

• Define the shapes and connections in the Diagram component declaration.
• Define the shapes and connections in a JSON.

Define Shapes and Connections Declaratively

To create the Telerik Diagram for Blazor declaratively:

1. Add the TelerikDiagram tag.
2. Define the Diagram layout through the Type parameter of the child <DiagramLayout> tag.
3. Define shapes with <DiagramShape> tags inside <DiagramShapes>.
4. Define the connections between the shapes with <DiagramConnection> tags inside <DiagramConnections>.
5. (optional) Define the Diagram Height, Width, and initial Zoom for optimal display. The default height is "600px".
6. (optional) Define the default type of all Diagram shapes and connections.

Basic Blazor Diagram

<TelerikDiagram Height="420px" Zoom="0.8">
    <DiagramConnectionDefaults Type="@DiagramConnectionType.Cascading" />
    <DiagramLayout Type="@DiagramLayoutType.Tree" />
    <DiagramShapeDefaults Type="@DiagramShapeType.Rectangle" />

    <DiagramShapes>
        <DiagramShape Id="shape1">
            <DiagramShapeContent Text="Shape 1" />
        </DiagramShape>
        <DiagramShape Id="shape2">
            <DiagramShapeContent Text="Shape 2" />
        </DiagramShape>
        <DiagramShape Id="shape3">
            <DiagramShapeContent Text="Shape 3" />
        </DiagramShape>
        <DiagramShape Id="shape4">
            <DiagramShapeContent Text="Shape 4" />
        </DiagramShape>
        <DiagramShape Id="shape5">
            <DiagramShapeContent Text="Shape 5" />
        </DiagramShape>
        <DiagramShape Id="shape6">
            <DiagramShapeContent Text="Shape 6" />
        </DiagramShape>
    </DiagramShapes>

    <DiagramConnections>
        <DiagramConnection FromId="shape1" ToId="shape2" />
        <DiagramConnection FromId="shape1" ToId="shape3" />
        <DiagramConnection FromId="shape2" ToId="shape4" />
        <DiagramConnection FromId="shape2" ToId="shape5" />
        <DiagramConnection FromId="shape3" ToId="shape6" />
    </DiagramConnections>
</TelerikDiagram>

Define Shapes and Connections in JSON

To load the shape and connection data from JSON:

1. Capture the Diagram component reference through the @ref attribute.
2. Execute the Diagram LoadFromJsonAsync(string json) method.

The minimum required JSON information includes:

• Shape id's as strings.
• Shape x and y coordinates as pixel numbers.
• Connection from.shapeId and to.shapeId if the connection links shapes. Otherwise, set the start and end coordinates with from.x, from.y, to.x, and to.y.

Optionally, you can also define:

• Shape width and height as numbers.
• Connection from.connector and to.connector that determine which shape side the connection touches ("Top", "Right", "Bottom", "Left").

The Diagram provides a SaveAsJsonAsync() method that returns the current shape and connection state as a JSON string. This allows you to persist user changes or see how to define more advanced shape and connection settings in JSON format.

Loading and saving the Diagram shape and connection state

Make changes and
<TelerikButton OnClick="@OnSaveButtonClick">Save Diagram to JSON</TelerikButton>

Make more changes and restore with
<TelerikButton OnClick="@OnLoadButtonClick">Load Diagram from JSON</TelerikButton>

<TelerikDiagram @ref="@DiagramRef" Height="320px" Zoom="0.9">
    <DiagramConnectionDefaults Type="@DiagramConnectionType.Cascading" />
    <DiagramLayout Type="@DiagramLayoutType.Tree" />
    <DiagramShapeDefaults Type="@DiagramShapeType.Rectangle" />
</TelerikDiagram>

<div style="overflow:auto;max-height:90px;max-width:90vw;">
    @DiagramJson
</div>

@code {
    private TelerikDiagram? DiagramRef { get; set; }

    private async Task OnSaveButtonClick()
    {
        DiagramJson = await DiagramRef!.SaveAsJsonAsync();
    }

    private async Task OnLoadButtonClick()
    {
        await DiagramRef!.LoadFromJsonAsync(DiagramJson);
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && DiagramRef is not null)
        {
            await Task.Delay(1); // wait for HTML and client-side Diagram instance
            await DiagramRef.LoadFromJsonAsync(DiagramJson);
            StateHasChanged();
        }

        await base.OnAfterRenderAsync(firstRender);
    }

    private string DiagramJson { get; set; } = @"
    {
      ""shapes"": [
        {
          ""id"": ""shape1"",
          ""content"": {
            ""text"": ""Shape 1""
          },
          ""x"": 200,
          ""y"": 50
        },
        {
          ""id"": ""shape2"",
          ""content"": {
            ""text"": ""Shape 2""
          },
          ""height"": 100,
          ""width"": 160,
          ""x"": 50,
          ""y"": 200
        },
        {
          ""id"": ""shape3"",
          ""content"": {
            ""text"": ""Shape 3""
          },
          ""x"": 300,
          ""y"": 200
        }
      ],
      ""connections"": [
        {
          ""from"": {
            ""shapeId"": ""shape1""
          },
          ""to"": {
            ""shapeId"": ""shape2""
          }
        },
        {
          ""from"": {
            ""shapeId"": ""shape1"",
            ""connector"":""Right""
          },
          ""to"": {
            ""shapeId"": ""shape3"",
            ""connector"":""Top""
          }
        }
      ]
    }";
}

Layouts

The Diagram provides multiple built-in horizontal and vertical layouts, which arrange all shapes and connections automatically, according to specific rules and priorities. Some of the layouts have variations called sub types.

Shapes

The shapes are the graph nodes and the main building blocks of the Diagram component. Learn about the shape types and available configuration options.

Connections

Connections link shapes or points in the Diagram. Users can create, modify or remove connections at runtime. See the Diagram connection features and settings.

Zoom

The Diagram allows users to zoom the graph in and out for better perception. The following code snippet shows the relevant parameters together with their default values. The default Zoom value is effectively 100% and the default maximum zoom is 200%. A Zoom value below 0.5 may not be readable, unless the shapes use a large font size or users zoom their browser.

Zoom-related Diagram parameters

RAZOR

<TelerikDiagram Zoom="1"
                ZoomRate="0.1"
                MaxZoom="2"
                MinZoom="0" />

Events

The Telerik Diagram fires events that enable the app to detect and react to user interactions with the component. Find out more about the Diagram events and event arguments.

Diagram API

Get familiar with all Diagram parameters, methods, events, and nested tags in the Diagram API Reference.

As a rule of thumb, the Diagram markup follows these naming conventions:

• Tag names in plural wrap tag names in singular:
  RAZOR

  <DiagramShapes>
    <DiagramShape />
  </DiagramShapes>

• Tags are nested, so that child tag names use their parent tag name with an appended word:
  RAZOR

  <DiagramConnection>
      <DiagramConnectionSelection>
          <DiagramConnectionSelectionHandles>
              <DiagramConnectionSelectionHandlesFill />
          </DiagramConnectionSelectionHandles>
      </DiagramConnectionSelection>
  </DiagramConnection>

• The previous rule has the following exceptions:
  • <DiagramConnectionDefaults> is a child of <TelerikDiagram>.
  • <DiagramShapeDefaults> is a child of <TelerikDiagram>.
  • <DiagramShapeDefaultsConnectorDefaults> is a child of <DiagramShapeDefaults>.
  • <DiagramShapeConnectorDefaults> is a child of <DiagramShape>.

Diagram Reference

The Blazor Diagram component exposes methods for programmatic operation. To use them, define a reference to the component instance with the @ref directive attribute. Blazor populates component references in OnAfterRenderAsync, so they are not available earier.

See a full example in section Create Diagram from JSON above.

Using the Diagram reference

RAZOR

<TelerikDiagram @ref="@DiagramRef" />

@code {
    private TelerikDiagram? DiagramRef { get; set; }
}

Next Steps

• Define Diagram layouts
• Configure Diagram shapes
• Customize Diagram connections
• Handle Diagram events

See Also

• Live Demos: Diagram
• Diagram API Reference