BlazorIntersectionObserver 0.1.0-dev

This is a prerelease version of BlazorIntersectionObserver.
There is a newer version of this package available.
See the version list below for details.
dotnet add package BlazorIntersectionObserver --version 0.1.0-dev
NuGet\Install-Package BlazorIntersectionObserver -Version 0.1.0-dev
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BlazorIntersectionObserver" Version="0.1.0-dev" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BlazorIntersectionObserver --version 0.1.0-dev
#r "nuget: BlazorIntersectionObserver, 0.1.0-dev"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BlazorIntersectionObserver as a Cake Addin
#addin nuget:?package=BlazorIntersectionObserver&version=0.1.0-dev&prerelease

// Install BlazorIntersectionObserver as a Cake Tool
#tool nuget:?package=BlazorIntersectionObserver&version=0.1.0-dev&prerelease

A comprehensive wrapper around the Intersection Observer API, giving you all the goodness of observing intersections in a performant way.

This is a wrapper around the Intersection Observer API so that you can use it in Blazor. It has the same API structure with convenience methods and components for a better dev experience.

Get Started

1. Installation

Install Blazor.IntersectionObserver through NuGet.

> dotnet add package BlazorIntersectionObserver

2. Register the service

Now you'll need to add the service to the service configuration.

using Blazor.IntersectionObserver;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddIntersectionObserver();
    }
}

3. Use it!

For the quickest setup, use the IntersectionObserve component. This provides an implicit context object which contains the observer entry! Easy!

Component setup
@using Blazor.IntersectionObserver.Components

<IntersectionObserve>
    <div>
        Hey... looks I'm @(context?.IsIntersecting ? "intersecting!": "not intersecting!")
    </div>
</IntersectionObserve>
Service setup

To directly use the service, you just need to inject it and observe the element(s).

@using Blazor.IntersectionObserver
@inject IntersectionObserverService ObserverService

<img ref="ImageElement" src="@(IsIntersecting ? "https://www.placecage.com/g/500/500" : "")"/>

@functions {
    public ElementRef ImageElement { get; set; }
    public bool IsIntersecting { get; set; }
    public bool HasObserver { get; set; }
    
    protected override void OnAfterRender() 
    {
        if (!HasObserver) 
        {
            SetupObserver();
        }
    }

    public async void SetupObserver()
    {
        HasObserver = true;

        await ObserverService.Observe(ImageElement, (entries) =>
        {
            var entry = entries.FirstOrDefault();
            IsIntersecting = entry.IsIntersecting;
            StateHasChanged();
        });
    }
}

Documentation and Usage

Options

You can pass through options to the ObserverService methods, these are the same as the Intersection Observer API options.

Example
var options = new IntersectionObserverOptions {
    Root = BodyRef, 
    Threshold = new List<double> { 0.25, 0.5, 1 },
    RootMargin = "10px 10px 10px 10px"
};

Service Methods

Observe

This a shorthand way of observing an element by providing:

  • The element you want to observe.
  • The callback to trigger on an intersection update.
  • The intersection observer options.

This returns an IntersectionObserver instance, allowing you to disconnect the observer or unobserve an element. Or if you wish, observe additional elements.

var observer = ObserverService.Observe(ElementRef, (entries) => {
    IsIntersecting = entries.FirstOrDefault().IsIntersecting;
    StateHasChanged();
}, options);
Create

The Create method follows the same approach as the Intersection Observer API, you create the observer and then pass elements you wish to observe by calling the Observe method on the observer instance. To create the observer, provide the following:

  • The callback to trigger on an intersection update.
  • The intersection observer options.

This returns an IntersectionObserver instance, allowing you to Observe elements. This also provides the ability to disconnect or unobserve the element.

var observer = ObserverService.Create((entries) => {
    IsIntersecting = entries.FirstOrDefault().IsIntersecting;
    StateHasChanged();
}, options);

observer.Observe(FirstImage);
observer.Unobserve(FirstImage);

IntersectionObserver Methods

Observe

To observe an element, provide the element reference to the IntersectionObserver instance by calling Observe.

observer.Observe(ElementRef);
Unobserve

To unobserve an element, provide the element reference to the IntersectionObserver instance by calling Unobserve.

observer.Unobserve(ElementRef);
Disconnect

To disconnect the observer, call Disconnect on the IntersectionObserver instance.

observer.Disconnect();

This is a useful method to clean up observers when components are disposed of, i.e.

@using Blazor.IntersectionObserver
@implements IDisposable
@inject IntersectionObserverService ObserverService

<div ref="NicolasCageRef"></div>

@functions {
    private IntersectionObserver Observer;
    @* Code... *@
    public void Dispose()
    {
        Observer.Disconnect();
    }
}

Component

<IntersectionObserve>

Rather than directly interfacing with the service, you can use this convenience component for quick and easy observing. You can access the observer entry through the implicit @context!

@* Injecting service... *@

<IntersectionObserve>
    <div>
        Hey... looks I'm @(context?.IsIntersecting ? "intersecting!": "not intersecting!")
    </div>
</IntersectionObserve>

@* Component code... *@

Implementation Detail

To avoid creating an unnecessary number of observers for every element being observed, if a Blazor Observer shares exactly the same options as another, they will both use the same IntersectionObserver instance in JS. As each Blazor Observer has a unique id and callback, the elements that are being observed will still be passed to their respective Blazor Observer.

Feature Requests

There's so much that IntersectionObserver can do, so if you have any requests or you want better documentation and examples, feel free to make a pull request or create an issue!

Credit

  • Blazor Extensions - They have a great way of setting up a blazor library, check their repos out!
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.1.0 76,696 10/15/2021
3.0.1 1,912 9/27/2021
3.0.0 499 9/4/2021
2.0.3 58,062 5/20/2021
2.0.2 297 5/20/2021
2.0.0 349 5/19/2021
1.1.0 13,336 12/6/2020
1.0.0 522 12/6/2020
0.2.0 651 6/4/2019
0.1.1 573 5/25/2019
0.1.0-dev 455 5/25/2019