# Blazor Diagram Overview

The [Blazor Diagram component](https://www.telerik.com/blazor-ui/diagram) 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, geometric form, and content of its elements.

## Diagram Elements

The Diagram component UI consists of the following elements:

* [*Shapes*](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes) are the Diagram nodes ([vertices](https://en.wikipedia.org/wiki/Vertex_\(graph_theory\))). Shapes can display text and images.
* [*Connectors*](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes#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*](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections) are the links ([edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge)) between Diagram shapes. Normally, a connection links two Diagram shapes, but a connection can also exist without related shapes.
* [*Caps*](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#cap-types) are the connection ends. The connections are directional, so each connection has a start cap and end cap.
* [*Selection handles*](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#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*](https://www.telerik.com/blazor-ui/documentation/components/diagram/layouts#layout-grid-settings) are groups ([subgraphs](https://en.wikipedia.org/wiki/Component_\(graph_theory\))) 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 three ways to define and display a Diagram:

* [Define the shapes and connections in the Diagram component declaration](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#define-shapes-and-connections-declaratively).
* [Bind the Diagram to collections of shapes and connections](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#bind-the-diagram-to-data).
* [Define the shapes and connections in a JSON](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#define-shapes-and-connections-in-json).

### Define Shapes and Connections Declaratively

To create the Telerik Diagram for Blazor declaratively:

1. Add the `TelerikDiagram` tag.
2. [Define the Diagram layout](https://www.telerik.com/blazor-ui/documentation/components/diagram/layouts) through the `Type` parameter of the child `<DiagramLayout>` tag.
3. [Define shapes](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes) with `<DiagramShape>` tags inside `<DiagramShapes>`.
4. [Define the connections](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections) between the shapes with `<DiagramConnection>` tags inside `<DiagramConnections>`.
5. (optional) Define the Diagram `Height`, `Width`, and [initial `Zoom`](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#zoom) for optimal display. The default height is `"600px"`.
6. (optional) Define the default type of all Diagram [shapes](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes#shape-types) and [connections](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections#connection-types).

> caption Basic Blazor Diagram

<demo metaUrl="client/diagram/basic-2/" height="570"></demo>

### Bind the Diagram to Data

See the [Diagram Data Binding](https://www.telerik.com/blazor-ui/documentation/components/diagram/data-bind) article, which explains how you can bind the Diagram component to a data source.

### 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](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#diagram-reference).
2. Execute the Diagram [`LoadFromJsonAsync(string json)` method](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdiagram#methods).

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 and apply them to the component in a future user session](https://www.telerik.com/blazor-ui/documentation/knowledge-base/diagram-change-shape-color-onshapeclick).
* Review the JSON structure and see how to define all possible shape and connection settings in JSON format.

> caption Loading and saving the Diagram shape and connection state

<demo metaUrl="client/diagram/state-1/" height="720"></demo>

## Layouts

The [Diagram provides multiple built-in horizontal and vertical layouts](https://www.telerik.com/blazor-ui/documentation/components/diagram/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](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes).

## 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](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections).

## 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.

> caption Zoom-related Diagram parameters

```RAZOR.skip-repl
<TelerikDiagram Zoom="1"
                ZoomRate="0.1"
                MaxZoom="2"
                MinZoom="0" />
```

## Pan

The Diagram content may overflow the component boundaries if there are a lot of shapes or if the user zooms in. By default, the Diagram allows users to pan the content by holding the `Ctrl` key and dragging. The following code snippet shows the relevant parameters together with their default values.

When both panning and [selection](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#select) are enabled, make sure the two features use a different `Key`.

> caption Pan-related Diagram parameters

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramPannable Enabled="true" Key="@DiagramPannableKey.Ctrl" />
</TelerikDiagram>
```

### Scrollbars

The Diagram allows you to control the visibility and behavior of scrollbars when panning is enabled. This provides better control over the user experience, especially when working with large diagrams.

The available scrollbar-related parameters are:

* `ShowScrollbars` (bool?)—controls whether scrollbars are shown for a pannable Diagram viewport. When set to `true`, scrollbars appear when the Diagram content overflows the viewport boundaries.
* `AutoHideScrollbars` (bool?)—controls whether the scrollbars hide automatically when idle. This parameter only applies when `ShowScrollbars` is enabled.

> caption Configure scrollbar visibility and auto-hide behavior

```RAZOR.skip-repl
<TelerikDiagram Height="400px">
    <DiagramPannable Enabled="true"
                     Key="@DiagramPannableKey.Ctrl"
                     ShowScrollbars="true"
                     AutoHideScrollbars="false" />
</TelerikDiagram>
```

## Select

Users can select a single shape or connection with a click. The Diagram also supports multiple selection through dragging a rectangular marquee. The following code snippet shows the relevant parameters together with their default values.

Once the user selects some shapes and connections, they can drag them to another position or remove them with the `Del` key.

When both [panning](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#pan) and selection are enabled, make sure the two features use a different `Key`.

> caption Selection-related Diagram parameters

```RAZOR.skip-repl
<TelerikDiagram>
    <DiagramSelectable Enabled="true" Multiple="true" Key="@DiagramSelectableKey.None">
        <DiagramSelectableStroke Color="black" DashType="@DashType.Dash" Width="1" />
    </DiagramSelectable>
</TelerikDiagram>
```

## 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](https://www.telerik.com/blazor-ui/documentation/components/diagram/events).

## Diagram API

Get familiar with all Diagram parameters, methods, events, and nested tags in the [Diagram API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdiagram).

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

* Tag names in plural wrap tag names in singular:
  ```RAZOR.skip-repl
  <DiagramShapes>
    <DiagramShape />
  </DiagramShapes>
  ```
* Tags are nested, so that child tag names use their parent tag name with an appended word:
  ```RAZOR.skip-repl
  <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](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdiagram#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](https://www.telerik.com/blazor-ui/documentation/components/diagram/overview#define-shapes-and-connections-in-json) above.

> caption Using the Diagram reference

```RAZOR.skip-repl
<TelerikDiagram @ref="@DiagramRef" />

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

## Next Steps

* [Bind the Diagram to data](https://www.telerik.com/blazor-ui/documentation/components/diagram/data-bind)
* [Define Diagram layouts](https://www.telerik.com/blazor-ui/documentation/components/diagram/layouts)
* [Configure Diagram shapes](https://www.telerik.com/blazor-ui/documentation/components/diagram/shapes)
* [Customize Diagram connections](https://www.telerik.com/blazor-ui/documentation/components/diagram/connections)
* [Handle Diagram events](https://www.telerik.com/blazor-ui/documentation/components/diagram/events)
* [Export the Diagram](https://www.telerik.com/blazor-ui/documentation/components/diagram/export)

## See Also

* [Live Demos: Diagram](https://demos.telerik.com/blazor-ui/diagram/overview)
* [Diagram API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdiagram)
