syncfusion/blazor-ui-components-skills / skills/syncfusion-blazor-diagram
syncfusion-blazor-diagram
VerifiedBuild and troubleshoot Syncfusion Blazor diagrams using SfDiagramComponent. Trigger for flowcharts, org charts, mind maps, BPMN, UML sequence, swimlanes, symbol palettes, nodes/connectors/ports/annotations, layouts, data binding, serialization (load/save), export/print, and collaborative editing questions. Provide Blazor + Syncfusion setup steps, configuration patterns, and sample snippets.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.6 KB |
| references/advanced-features.md | markdown | 10.0 KB |
| references/annotations.md | markdown | 11.9 KB |
| references/bpmn.md | markdown | 6.6 KB |
| references/collaborative-editing.md | markdown | 7.0 KB |
| references/connectors.md | markdown | 6.4 KB |
| references/data-binding.md | markdown | 12.8 KB |
| references/events.md | markdown | 52.7 KB |
| references/export-print.md | markdown | 5.9 KB |
| references/getting-started.md | markdown | 5.4 KB |
| references/interaction.md | markdown | 36.7 KB |
| references/layout.md | markdown | 12.3 KB |
| references/nodes.md | markdown | 8.6 KB |
| references/overview-component.md | markdown | 5.5 KB |
| references/ports.md | markdown | 5.1 KB |
| references/serialization.md | markdown | 3.5 KB |
| references/shapes.md | markdown | 6.2 KB |
| references/styling.md | markdown | 6.1 KB |
| references/swimlane.md | markdown | 6.1 KB |
| references/symbol-palette.md | markdown | 7.7 KB |
| references/uml-class-diagram.md | markdown | 25.5 KB |
| references/uml-sequence.md | markdown | 6.5 KB |
references/annotations.md
View on GitHub# Annotations in Blazor Diagram
## Table of Contents
- [Overview](#overview)
- [Node Annotations](#node-annotations)
- [Connector Annotations](#connector-annotations)
- [Annotation Position and Alignment](#annotation-position-and-alignment)
- [Annotation Style](#annotation-style)
- [Multiple Annotations](#multiple-annotations)
- [Add / Remove / Update at Runtime](#add--remove--update-at-runtime)
- [Inline Editing](#inline-editing)
- [Common Gotchas](#common-gotchas)
---
## Overview
Annotations are text labels attached to nodes or connectors. They support positioning, alignment, font styling, and runtime editing. Each node/connector can have multiple annotations.
- **Node annotations:** Use `ShapeAnnotation`
- **Connector annotations:** Use `PathAnnotation`
---
## Node Annotations
```razor
@using Syncfusion.Blazor.Diagram
<SfDiagramComponent Height="600px" Nodes="@nodes" />
@code {
DiagramObjectCollection<Node> nodes = new();
protected override void OnInitialized()
{
nodes.Add(new Node
{
ID = "node1",
OffsetX = 200, OffsetY = 200,
Width = 120, Height = 60,
Style = new ShapeStyle { Fill = "#6495ED", StrokeColor = "white" },
Annotations = new DiagramObjectCollection<ShapeAnnotation>
{
new ShapeAnnotation { Content = "Process Step" }
}
});
}
}
```
---
## Connector Annotations
```razor
connectors.Add(new Connector
{
ID = "conn1",
SourceID = "node1", TargetID = "node2",
Type = ConnectorSegmentType.Orthogonal,
Annotations = new DiagramObjectCollection<PathAnnotation>
{
new PathAnnotation
{
Content = "Yes",
Offset = 0.5 // position along the path (0=source, 1=target, 0.5=middle)
}
}
});
```
---
## Annotation Position and Alignment
**Node annotation positioning via `Offset` (fraction of node width/height):**
| Offset | Position |
|--------|----------|
| `(0.5, 0.5)` | Center (default) |
| `(0.5, 0)` | Top center |
| `(0.5, 1)` | Bottom center |
| `(0, 0.5)` | Left center |
| `(1, 0.5)` | Right center |
```razor
new ShapeAnnotation
{
Content = "Label",
Offset = new DiagramPoint { X = 0.5, Y = 0 }, // top center
HorizontalAlignment = HorizontalAlignment.Center,
VerticalAlignment = VerticalAlignment.Bottom,
Margin = new DiagramThickness { Top = 5 }
}
```
**Connector annotation positioning via `Offset` (0 to 1 along the path):**
```razor
new PathAnnotation
{
Content = "Flow Label",
Offset = 0.5, // middle of connector
Alignment = AnnotationAlignment.Center
}
```
---
## Annotation Style
```razor
new ShapeAnnotation
{
Content = "Styled Label",
Style = new TextStyle
{
FontSize = 14,
Bold = true,
Italic = false,
Color = "#333333",
TextDecoration = TextDecoration.Underline,
TextAlign = TextAlign.Center
}
}
```
---
## Interaction Constraints
`AnnotationConstraints` is a flags enum; combine values with `|`.
| Constraint | Description |
|---|---|
| `AnnotationConstraints.None` | No interactions allowed |
| `AnnotationConstraints.Select` | User can select the annotation |
| `AnnotationConstraints.Drag` | User can drag the annotation |
| `AnnotationConstraints.Resize` | User can resize the annotation |
| `AnnotationConstraints.Rotate` | User can rotate the annotation |
| `AnnotationConstraints.Interaction` | Enables all: Select + Drag + Resize + Rotate |
| `AnnotationConstraints.ReadOnly` | Prevents inline text editing |
| `AnnotationConstraints.InheritReadOnly` | Inherits the ReadOnly setting from the parent node/connector |
> **`Default` is NOT in this list** — there is no `AnnotationConstraints.Default`.
```razor
@* ❌ Wrong — AnnotationConstraints.Default does not exist *@
new ShapeAnnotation { Content = "Label", Constraints = AnnotationConstraints.Default }
@* ✅ Correct — use Interaction to enable all, or combine specific flags *@
new ShapeAnnotation { Content = "Draggable label", Constraints = AnnotationConstraints.Select | AnnotationConstraints.Drag }
@* ✅ Correct — use Interaction as the "full access" equivalent *@
new ShapeAnnotation { Content = "All interactions", Constraints = AnnotationConstraints.Interaction }
```
### DragLimit (PathAnnotation only)
Restricts how far (in pixels) a `PathAnnotation` can be dragged from its original position.
**Drag must be enabled** — use `AnnotationConstraints.Interaction` or include `AnnotationConstraints.Select` and `AnnotationConstraints.Drag` in the flags.
> **⚠️ `DragLimit` type is `DiagramThickness` — NOT `Margin`.**
> Using `new Margin { ... }` causes a compile error (`CS0029`). Always use `new DiagramThickness { ... }`:
> ```csharp
> // ❌ Wrong — Margin is the wrong type for DragLimit
> DragLimit = new Margin { Left = 30, Right = 30, Top = 10, Bottom = 10 }
>
> // ✅ Correct — DiagramThickness is the required type
> DragLimit = new DiagramThickness { Left = 30, Right = 30, Top = 10, Bottom = 10 }
> ```
```razor
new PathAnnotation()
{
Content = "Limited drag",
// ✅ Interaction enables drag (required for DragLimit to take effect)
Constraints = AnnotationConstraints.Interaction,
// ✅ DiagramThickness — NOT Margin
DragLimit = new DiagramThickness { Left = 30, Right = 30, Top = 10, Bottom = 10 }
}
```
---
## Rotation
Control annotation rotation independently from the node.
### RotationAngle
Set a fixed rotation angle in degrees (0-360):
```razor
new ShapeAnnotation()
{
Content = "Rotated",
RotationAngle = 45
}
```
### RotationReference
Determines the reference frame for rotation:
| `RotationReferenceDirection` | Description |
|---|---|
| `Page` | Rotation angle is relative to the canvas (absolute) |
| `Parent` | Rotation angle is relative to the parent node's rotation |
```razor
new ShapeAnnotation()
{
Content = "Always upright",
RotationAngle = 0,
RotationReference = RotationReferenceDirection.Page // stays horizontal even when node rotates
}
```
---
## Multiple Annotations
A node can have many annotations at different positions:
```razor
Annotations = new DiagramObjectCollection<ShapeAnnotation>
{
new ShapeAnnotation
{
Content = "Title",
Offset = new DiagramPoint { X = 0.5, Y = 0 },
VerticalAlignment = VerticalAlignment.Bottom
},
new ShapeAnnotation
{
Content = "Subtitle",
Offset = new DiagramPoint { X = 0.5, Y = 1 },
VerticalAlignment = VerticalAlignment.Top,
Style = new TextStyle { FontSize = 10, Color = "#888" }
}
}
```
---
## Add / Remove / Update at Runtime
**Add annotation at runtime:**
```csharp
_diagram.Nodes[0].Annotations.Add(new ShapeAnnotation
{
Content = "New Label",
Offset = new DiagramPoint { X = 0.5, Y = 0.5 }
});
```
**Remove annotation:**
```csharp
_diagram.Nodes[0].Annotations.RemoveAt(0);
```
**Update annotation text:**
```csharp
_diagram.BeginUpdate();
_diagram.Nodes[0].Annotations[0].Content = "Updated Text";
await _diagram.EndUpdateAsync();
```
---
## Inline Editing
Users can double-click an annotation to edit it inline (enabled by default).
**Disable editing for a specific annotation:**
```razor
new ShapeAnnotation
{
Content = "Read Only",
Constraints = AnnotationConstraints.ReadOnly
}
```
> **⚠️ `AllowEditing` does NOT exist** on `ShapeAnnotation` or `PathAnnotation`.
> Inline editing is **on by default** — no property is needed to enable it.
> To **disable** editing, set `Constraints = AnnotationConstraints.ReadOnly`.
**Handle annotation edit events:**
```razor
<SfDiagramComponent TextChanged="OnTextChanged" />
@code {
private void OnTextChanged(TextChangeEventArgs args)
{
// args.OldValue — text before editing
// args.NewValue — text after editing
Console.WriteLine($"Changed from '{args.OldValue}' to '{args.NewValue}'");
}
}
```
---
## Events
All annotation events are raised on `SfDiagramComponent`.
### SelectionChanging / SelectionChanged
Fires when the user selects or deselects an annotation (requires `AnnotationConstraints.Select`):
```razor
<SfDiagramComponent SelectionChanging="OnSelectionChanging" SelectionChanged="OnSelectionChanged" />
@code {
void OnSelectionChanging(SelectionChangingEventArgs args)
{
// args.Cancel = true to prevent selection
}
void OnSelectionChanged(SelectionChangedEventArgs args) { }
}
```
### PositionChanging / PositionChanged
Fires when an annotation is dragged:
```razor
<SfDiagramComponent PositionChanging="OnPositionChanging" PositionChanged="OnPositionChanged" />
@code {
void OnPositionChanging(PositionChangingEventArgs args)
{
// args.Cancel = true to prevent movement
Console.WriteLine($"Moving to: {args.NewValue.OffsetX}, {args.NewValue.OffsetY}");
}
void OnPositionChanged(PositionChangedEventArgs args) { }
}
```
### SizeChanging / SizeChanged
Fires when an annotation is resized:
```razor
<SfDiagramComponent SizeChanging="OnSizeChanging" />
@code {
void OnSizeChanging(SizeChangingEventArgs args)
{
// Enforce minimum width
if (args.NewValue.Width < 50) args.Cancel = true;
}
}
```
### RotationChanging / RotationChanged
Fires when an annotation is rotated:
```razor
<SfDiagramComponent RotationChanging="OnRotationChanging" />
@code {
void OnRotationChanging(RotationChangingEventArgs args) { }
}
```
---
## Hyperlink
| Property | Type | Description |
|---|---|---|
| `Url` | `string` | Target URL |
| `Content` | `string` | Overrides annotation text as link label |
| `OpenMode` | `HyperlinkOpenMode` | `Self` (same tab) or `Blank` (new tab) |
| `Color` | `string` | Supports named colors, hex codes, and RGB values. |
| `TextDecoration` | `TextDecoration` | Defines the text decoration style for the hyperlink, such as None, underline, overline, or strikethrough. |
Use `Hyperlink` to make annotation text a clickable link.
```razor
new ShapeAnnotation()
{
Content = "Visit Documentation",
Hyperlink = new HyperlinkSettings()
{
Url = "https://blazor.syncfusion.com/documentation/diagram/",
Content = "Syncfusion Docs",
Color = "Red",
TextDecoration = TextDecoration.None,
OpenMode = HyperlinkOpenMode.Blank // Self | Blank
}
}
```
> `Content` inside `HyperlinkSettings` overrides the annotation's own `Content` as the visible link text.
### Update Hyperlink at Runtime
```csharp
void UpdateLink()
{
Node node = diagram.GetObject("node1") as Node;
var ann = (node.Annotations as DiagramObjectCollection<ShapeAnnotation>)[0];
ShapeAnnotation ann = (node.Annotations as DiagramObjectCollection<ShapeAnnotation>)[0];
ann.Hyperlink = new HyperlinkSettings()
{
Url = "https://www.example.com",
OpenMode = HyperlinkOpenMode.Self
};
}
```
---
## Common Gotchas
- **Node uses `ShapeAnnotation`, connector uses `PathAnnotation`** — using the wrong type causes no label to show
- **Annotation ID must be unique** and must not start with a number or contain underscores/spaces
- **Default position is center** (`Offset = (0.5, 0.5)` for nodes, `Offset = 0.5` for connectors)
- **`HorizontalAlignment` and `VerticalAlignment`** control which side of the offset point the text is anchored to
- **`PathAnnotation.Offset`** is a `double` (0-1), not a `DiagramPoint` like `ShapeAnnotation.Offset`
- **Inline editing is enabled by default** — use `AnnotationConstraints.ReadOnly` to prevent it
- **`AllowEditing` does NOT exist** on `ShapeAnnotation` or `PathAnnotation` — this property will cause a compile error. Editing is on by default; use `AnnotationConstraints.ReadOnly` to opt out
- **`DragLimit` type is `DiagramThickness`** — NOT `Margin`. Using `new Margin { ... }` causes `CS0029`. Use `new DiagramThickness { Left = 30, Right = 30, Top = 10, Bottom = 10 }`
- **`AnnotationConstraints.Default` does NOT exist** — use `AnnotationConstraints.Interaction` for full access, or combine flags like `AnnotationConstraints.Select | AnnotationConstraints.Drag`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |