Blazor.JSInterop.Helpers 1.1.1

Table of Contents

1. Overview
2. Installation
3. Usage
4. Documentation
5. Examples
6. License

Overview

When building robust and complex razor components using Blazor, interactions with the Document Object Model (DOM) become inevitable.

This package extends the JavaScript (JS) interoperability in Blazor through helpers for interacting with the DOM's Window and Element APIs.

Installation

Package Manager

Install-Package Blazor.JSInterop.Handlers -Version 1.1.1

.NET CLI

dotnet add package Blazor.JSInterop.Handlers

PackageReference

<PackageReference Include="Blazor.JSInterop.Handlers" Version="1.1.1">

Usage

To use the package, you first need to configure your dependency injection (DI) container. Add the following line of code to your Program.cs:

builder.Services.AddBlazorInteropHandlers();

Then add references to the namespaces in your _Imports.razor or as directives at the top of your razor component's page:

@using Blazor.JSInterop.Helpers.Services
@using Blazor.JSInterop.Helpers.Models

Finally, inject instances of the service as needed in your razor component in your directive section or code section:

// In directive section
@inject IElementHandler elementHandler
@inject IWindowHandler windowHandler

// In code section
@code
{
    [Inject] IElementHandler elementHandler;
    [Inject] IWindowHandler windowHandler;
}

Documentation

WindowHandler
-- Models
-- Events
-- Methods
ElementHandler
-- Methods
Examples
-- Alert on window resize event
-- Focus an element

WindowHandler

Namespace: Blazor.JSInterop.Helpers.Services
Inheritance: IWindowHandler → WindowHandler

Contains event handlers and methods to interact with the DOM's Window API

Models

Namespace: Blazor.JSInterop.Helpers.Models

Events

Methods

ElementHandler

Namespace: Blazor.JSInterop.Helpers.Services
Inheritance: IElementHandler → ElementHandler

Contains methods to interact with the DOM's Element API.

Methods

Examples

When performing JS interop calls and when dealing with component references, it is recommended that you use the OnAfterRender{Async} stage as component references will have finished populating at this point.

Some helpers may mutate DOM objects directly. It is recommended that you only mutate the DOM object when the object doesn't interact with Blazor. Otherwise it may invalidate Blazor's internal representation of the DOM, resulting in undefined behavior.

Alert when window resizes

Before adding subscribers to events, you must first register the event handlers.

Example.razor

@page "/"

@using Blazor.JSInterop.Helpers.Services
@using Blazor.JSInterop.Helpers.Models

@implements IDisposable

@inject IWindowHandler windowHandler

<PageTitle>Index</PageTitle>

<h1>Hello, world!</h1>

@code
{
    // Register event handlers and add subscriber
    protected override async Task OnInitializedAsync()
    {
        await windowHandler.RegisterEventHandlers();
        windowHandler.OnResize += OnResizeHandler;
    }

    // When the window resizes, alert the user
    private async void OnResizeHandler(object sender, WindowEventArgs windowEventArgs)
    {
        await windowHandler.AlertAsync("The window was resized!");
    }

    // Unsubscribe when the component is disposed.
    public void Dispose()
    {
        windowHandler.OnResize -= OnResizeHandler;
    }
}

Note: In the preceding example, the component implements IDisposable. It is recommended that you implement either IDisposable or IAsyncDisposable when subscribing to events. If both are implemented, the framework only executes the asynchronous overload.

Focus an element

Focus an element when a button is clicked. The component reference is bound and passed to the FocusAsync(ElementReference) method.

Example.razor

@page "/"

@using Blazor.JSInterop.Helpers.Services
@using Blazor.JSInterop.Helpers.Models

@inject IElementHandler elementHandler

<PageTitle>Index</PageTitle>

// @ref binds the component reference
<h1 @ref=@_headingRef>Hello, world!</h1>

<button @onclick=@FocusHeadingOne>Click Me!</button>

@code
{
    // Store component reference
    ElementReference _headingRef;

    private async void FocusHeadingOne()
    {
        await elementHandler.FocusAsync(_headingRef);
    }
}

Note: In the preceding example, the reference to the FocusHeadingOne method was bound to the button tag directly so overriding OnAfterRender{Async} was not necessary.

License

This project is licensed under MIT. Feel free to re-use any libraries or code for non-commercial use but do your due diligence with attributing credit.