Blazor Integration

This guide is focused on Blazor WebAssembly integration.

Critical Setup Checklist

Before troubleshooting anything else, confirm all of these are in place:

1. builder.Services.AddAnnotations(); is registered in Program.cs.
2. The annotations bundle CSS is linked in App.razor.
3. Toolbar.Position is set to "floating" when the toolbar should overlay inside the viewer container.
4. ListPanel.Enabled is explicitly set to true because it defaults to false.
5. Your app-level stylesheet pipeline is active so the RCL CSS can load.

Example stylesheet include:

<HeadContent>
  <link rel="stylesheet" href="css/annotations-overrides.css" />
</HeadContent>

Known Pitfalls

Toolbar not visible

• The toolbar must be mounted to the DOM.
• The position must be "floating".

List panel not visible

The list panel is disabled by default. Opt in explicitly:

ListPanel = new ListPanelOptions(Enabled: true, Side: "right", Width: 280, Visible: true)

Initializing too early

Call AnnotationsInterop.InitializeAsync or let AnnotationViewer.OnAfterRenderAsync do the setup after the first render.

Recommended Path

Use the HyperPath.Viewer.Annotations.Blazor package and its built-in interop.

Register Services

using HyperPath.Viewer.Annotations.Blazor;

builder.Services.AddAnnotations();

Add the Component

@using HyperPath.Viewer.Annotations.Blazor.Components
@using HyperPath.Viewer.Annotations.Blazor.Models

<AnnotationViewer
  @ref="_viewer"
  Style="width:100%; height:80vh;"
  Options="@_options"
  OnAnnotationChanged="HandleAnnotationChanged"
  OnModeChanged="HandleModeChanged" />

Advanced Path

Use a custom JS interop wrapper only when you need full control over placement, mounting, or lifecycle behavior.