brycehewett / BlazorPanzoom

Blazor .NET 5 wrapper for timmywil's panzoom library that helps make zooming and panning of Blazor components and elements easier

BlazorPanzoom

BlazorPanzoom is a library for Blazor that wraps around timmywil's JavaScript library, panzoom. It provides an easy way to enable panning and zooming of web components/elements through CSS transformations.

Currently targeting: panzoom v4.4.1

Demo Showcase

View Demo App

The demo app aims to implement all of the same examples from timmywil's panzoom' s demo page.

The list below shows which examples have been implemented.

Demo List

• Panning and zooming
• Panning and focal-point zooming (shift + mousewheel)
• SVG support: move all the things!
• Containment within the parent: contain = inside
• Containment within the parent: contain = outside
• Exclude elements within the Panzoom element from event handling
• Disabling one axis
• Adding on matrix functions to the transform
• Adding a transform to a child
• A Panzoom instance within another Panzoom instance

Prerequisites

• .NET 5.0

Installation

Install the NuGet package:

dotnet add package BlazorPanzoom

Add the following to _Imports.razor

@using BlazorPanzoom

Add the following to index.html (client-side) or _Host.cshtml (server-side) in body

<script src="_content/BlazorPanzoom/panzoom.min.js"></script>
<script src="_content/BlazorPanzoom/blazorpanzoom.js"></script>

Client-Side Config (WebAssembly)

In Program.cs...

Import the following

using BlazorPanzoom;

And then add the following to where you register your services

builder.Services.AddBlazorPanzoomServices();

Server-Side Config

Import the following

using BlazorPanzoom;

In Startup.cs...

Import the following

using BlazorPanzoom;

And then add the following to where you register your services

builder.Services.AddBlazorPanzoomServices();

Usage

Simple Example

Wrap the element that you want to enable panning and zooming for with <Panzoom>:

<!-- Using solid border-style to highlight the image's panning & zooming boundary -->
<div class="my-main" style="border-style: solid;">
    <Panzoom>
        <!-- Must set the element's reference (@ref)! -->
        <img @ref="@context.ElementReference" src="https://homepages.cae.wisc.edu/~ece533/images/pool.png" alt="image"/>
    </Panzoom>
</div>

Note: you must use @ref="@context.ElementReference" on the element that you want to enable panning and zooming for!

This example enables panning for the <img> component via mouse input. Zooming is not enabled by default on Desktop.

Zoom via Mouse Wheel

To enable zooming of an element through the mouse wheel, pass WheelMode="@WheelMode.ZoomWithWheel" to the <Panzoom> component.

<div class="my-main" style="border-style: solid;">
    <Panzoom WheelMode="WheelMode.ZoomWithWheel">
        <img @ref="@context.ElementReference" src="https://homepages.cae.wisc.edu/~ece533/images/pool.png" alt="image"/>
    </Panzoom>
</div>

---

Full Example

FocalDemo.razor (Live Demo)

Demonstrates:

• Registering an element to use Panzoom
  • Setting options via PanzoomOptions

See issue #3 for a list of supported options. For documentation on what each option does, see panzoom #doc.

• Calling Panzoom functions from code (ResetAsync & ZoomWithWheelAsync)
• Custom zoom wheel handling (zoom only while holding the Shift key)

    <div class="buttons">
        <button @onclick="OnResetClick">Reset</button>
    </div>

    <div class="panzoom-parent" style="border-width: 10px;">
        <!-- We wrap the <img> element with the Panzoom control -->
        <Panzoom @ref="_panzoom" PanzoomOptions="@(new PanzoomOptions {Canvas = true})" WheelMode="@WheelMode.Custom" OnWheel="@OnWheel">
            <!-- MUST set @ref="@context.ElementReference" to the <Panzoom>'s context -->
            <div @ref="@context.ElementReference" class="panzoom" style="width: 400px; height: 400px; margin: 0 auto;">
                <img style="width: 100%; height: 100%;" src="target.png" alt="image"/>
            </div>
        </Panzoom>
    </div>
    
 @code {

    private Panzoom _panzoom;

    private async Task OnResetClick(MouseEventArgs args) => await _panzoom.ResetAsync();

    private async Task OnWheel(CustomWheelEventArgs args)
    {
        if (!args.ShiftKey)
        {
            return;
        }
        await _panzoom.ZoomWithWheelAsync(args);
    }

}

For more examples, see the Demos folder.

Documentation

Please see the wiki for documentation and help.

For documentation on the panzoom JavaScript API, click here.

License

MIT