Business apps built on ASP.NET Core don't need to look like spreadsheets. A short animated check mark after a form submits, a friendly illustration on an empty dashboard or a branded loader while a report generates can make an internal tool or customer portal feel finished. Lottie is a practical way to add that motion: designers export vector animations as small files, and the browser plays them with a JavaScript player. The question for .NET teams is how to wire this into Razor Pages, MVC and especially Blazor without fighting the framework.
This guide covers the two main web players, how to call them from Blazor through JavaScript interop, how to serve .json and .lottie files correctly, and how to keep animations accessible and fast.
Choosing a Player: lottie-web or the dotLottie Web Player
There are two well-maintained options for the browser.
- lottie-web is the original player from Airbnb. It is published on npm as
lottie-weband renders JSON animations exported from After Effects with the Bodymovin plugin. You create an animation withlottie.loadAnimation(), passing a container element, a renderer (svg,canvasorhtml), loop and autoplay flags, and a path to the JSON file. The returned instance exposes methods such asplay(),pause(),stop(),setSpeed()anddestroy(). - dotLottie web player from LottieFiles is published as
@lottiefiles/dotlottie-web. It plays both classic JSON files and the newer.lottieformat, a compressed ZIP archive that can bundle several animations, images, themes and state machines. It renders to a<canvas>element through aDotLottieclass. There is also a web component package,@lottiefiles/dotlottie-wc, which gives you a<dotlottie-wc>tag.
If your designers already deliver JSON files and you want SVG output that stays crisp when zoomed, lottie-web is a simple choice. If you want compressed files or plan to ship many animations together, the dotLottie player is worth a look.
Adding the Library to an ASP.NET Core Project
You have two common routes, and both work with Razor Pages, MVC and Blazor.
Script tag from a local copy or CDN
The quickest route is a script tag. Download the minified player from the npm package (or reference it from a public CDN such as cdnjs, where lottie-web is listed under its old name, bodymovin) and place it under wwwroot/lib. Then reference it in your layout, App.razor or _Host.cshtml, depending on your project template. A local copy avoids a third-party dependency at runtime and works on intranets without internet access.
npm with a bundler
If your team already runs a front-end build step (Vite, esbuild or webpack) that outputs into wwwroot, install the package with npm install lottie-web or npm install @lottiefiles/dotlottie-web and import it in your own module. This gives you version pinning through package.json and lets you tree-shake the rest of your scripts.
For most line-of-business apps, the script tag is enough. Keep the file versioned in source control so deployments stay predictable. Our ASP.NET development team usually starts this way and moves to npm only when a project already has a front-end pipeline.
Controlling Animations From Blazor With JS Interop
Blazor components can't touch the DOM directly in C#, so the player lives in JavaScript and Blazor calls it through IJSRuntime. Microsoft's guide to calling JavaScript functions from .NET methods in Blazor recommends JavaScript modules, loaded with import, over global functions. It also explains that an ElementReference only points to a real element after the component renders, so DOM work belongs in OnAfterRenderAsync, and that JS calls aren't possible during prerendering.
The pattern below uses a small JS module that creates a lottie-web animation and returns the instance to .NET as an IJSObjectReference. Blazor can then call play, pause and stop on that object directly.
// wwwroot/js/lottieInterop.js
export function load(el, path, loop) {
const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
return lottie.loadAnimation({
container: el, renderer: "svg", path,
loop: reduce ? false : loop, autoplay: !reduce
});
}
// LottiePlayer.razor (@code block)
private ElementReference host;
private IJSObjectReference? module, anim;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (!firstRender) return;
module = await JS.InvokeAsync<IJSObjectReference>("import", "./js/lottieInterop.js");
anim = await module.InvokeAsync<IJSObjectReference>("load", host, Path, Loop);
}
public async Task Play() => await anim!.InvokeVoidAsync("play");
public async Task Pause() => await anim!.InvokeVoidAsync("pause");
public async Task Stop() => await anim!.InvokeVoidAsync("stop");
public async ValueTask DisposeAsync()
{
try
{
if (anim is not null) { await anim.InvokeVoidAsync("destroy"); await anim.DisposeAsync(); }
if (module is not null) await module.DisposeAsync();
}
catch (JSDisconnectedException) { }
}
A few notes on this component:
- The markup is just
<div @ref="host"></div>plus@inject IJSRuntime JSand@implements IAsyncDisposable. Size the container with a CSS class, since the player fills it. PathandLoopare ordinary component parameters, so the same component serves a loader, an empty state and a success tick.- In a Blazor Web App, the component needs an interactive render mode (for example
@rendermode InteractiveServer) for the buttons and lifecycle methods to run in the browser session. - Calling
destroy()on dispose releases the animation when users navigate away, which matters on dashboards that swap panels often. - Don't let Blazor render child content inside the container. The player owns that DOM, and Blazor's diffing should not try to update it.
Teams that are new to the format often ask designers for a short brief first. If some of your designers or stakeholders read Spanish, this Spanish-language article on what an animación Lottie is and when it makes sense explains the format from a design point of view, which helps both sides agree on what to deliver.
Serving .json and .lottie Files With the Right MIME Types
Static file handling is where many Lottie integrations quietly break. JSON files are fine: .json is already a known extension and is served as application/json. The .lottie extension is not in the default list, and ASP.NET Core does not serve unknown file types, so the request ends up as a 404.
The fix is to map the extension. Microsoft's page on serving static files in ASP.NET Core shows how to use FileExtensionContentTypeProvider and its Mappings dictionary, then pass the provider to UseStaticFiles through StaticFileOptions.ContentTypeProvider. The dotLottie specification lists the media type as application/zip+dotlottie, so a one-line mapping such as provider.Mappings[".lottie"] = "application/zip+dotlottie"; does the job.
Two details from the same documentation are worth following:
- Don't switch on
ServeUnknownFileTypesto get around the 404. The docs describe it as a security risk and recommend explicit mappings instead. - Apps on .NET 9 and later often use
MapStaticAssets. The docs list custom MIME mapping as a static file middleware feature, so either addUseStaticFileswith your provider for these files, or define aStaticWebAssetContentTypeMappingitem in the project file so the build-time manifest knows the content type.
Configure the provider once at startup and don't change it afterward, since the docs note that its mappings dictionary is not thread-safe for concurrent writes.
Accessibility: Respecting prefers-reduced-motion
Some users get dizzy or distracted by motion, and operating systems let them say so. The MDN reference for prefers-reduced-motion explains that the media feature reports whether the user has asked to minimize non-essential motion, with the values no-preference and reduce.
The JS module above checks this with matchMedia and turns off autoplay and looping when reduction is requested. Other good habits:
- Show a meaningful static frame instead of a blank box. With lottie-web,
goToAndStop()lets you jump to a chosen frame. - Give decorative animations
aria-hidden="true"on the container, and make sure success or error messages also appear as text. - Avoid long infinite loops near forms. A loader should stop when loading stops.
Performance: Lazy Loading and File Size
Lottie files are small compared with video, but a dashboard with ten animations can still add weight. Keep it lean:
- Lazy-load the player. Import the JS module only in components that use it, as in the example, rather than loading the player on every page.
- Defer off-screen animations. Use an
IntersectionObserverin your module to callplay()only when the container scrolls into view. - Ask for lean exports. Fewer layers and masks, no embedded high-resolution images, and a trimmed timeline make a real difference.
- Compress responses. Enable response compression or let your reverse proxy compress JSON.
.lottiefiles are already ZIP-compressed. - Cache aggressively. Animation files rarely change, so long cache lifetimes with versioned file names are safe.
These small steps fit the broader reasons teams pick the framework in the first place, which we covered in what makes ASP.NET Core a hot option for web application development.
FAQ
Does Lottie work in Razor Pages and MVC, not just Blazor?
Yes. In Razor Pages and MVC you call lottie.loadAnimation() from a regular script on the page. JS interop is only needed when Blazor components control playback.
Can Blazor WebAssembly use the same approach?
Yes. The interop code is the same for server and WebAssembly components. The JS module, IJSObjectReference calls and disposal pattern don't change.
Do I need a NuGet package for Lottie?
No. The players are JavaScript libraries, so a script reference or npm package plus a small interop module is all you need.

