SyntaxCircus.FancyBlazor 0.4.0

FancyBlazor

<p align="center"> <img src="docs/assets/fancyblazor-marketing-640.png" width="320" alt="FancyBlazor optical mark" /> </p>

Live demo: Explore the FancyBlazor catalog

Roadmap: See the approved pre-1.0 expansion phases

Composable visual effects for Blazor: backgrounds, borders, viewport reveals, pointer motion, parallax, and shimmer—without React islands, a runtime CDN, or consumer JavaScript tooling.

FancyBlazor targets net10.0 and works with static SSR, Interactive Server, Interactive WebAssembly, Interactive Auto, and standalone WebAssembly. It is CSS-framework-agnostic and keeps meaningful child content as ordinary semantic DOM.

Preview software. The API may change before 1.0. Published as-is and maintained on a best-effort basis; there is no support SLA.

Install and register

dotnet add package SyntaxCircus.FancyBlazor

Register the shared runtime in every executable host. Interactive Auto apps register it in both server and client Program.cs files.

using SyntaxCircus.FancyBlazor;

builder.Services.AddFancyBlazor();

Import the root namespace in _Imports.razor:

@using SyntaxCircus.FancyBlazor

No script tag, npm package, CDN, or manual stylesheet import is required.

First effect

<ShaderBackground Effect="ShaderEffect.Nacre"
                  Palette="FancyPalettes.Witchlight">
    <section class="hero">
        <h1>Build something that catches light.</h1>
        <p>This remains semantic HTML before and after WebGL initializes.</p>
    </section>
</ShaderBackground>

Before interactivity—or when WebGL is unavailable—the component displays a palette-derived CSS background and leaves the content usable.

Kinetic text

WordRotate, MorphText, and Typewriter cycle, crossfade, or progressively type decorative text while keeping the visible motion aria-hidden and exposing a complete accessible mirror to assistive technology. They all share the same lifecycle as the other JS-light effects and respect prefers-reduced-motion.

<WordRotate Words="@(new[] { "Compose", "Animate", "Ship" })" Interval="TimeSpan.FromSeconds(1.5)" />
<MorphText Words="@(new[] { "Frosted", "Faceted", "Filament" })" Mode="MorphMode.CharSplit" />
<Typewriter Text="@(new[] { "Hello, world.", "Compose with FancyBlazor." })" />

See kinetic text overview, WordRotate, MorphText, and Typewriter for parameter references and composition examples.

Atmospheric fields

CausticsBackground, TopographicBackground, and RainBackground draw bounded Canvas 2D atmospheric fields behind semantic child content, sharing the same lifecycle as the other Canvas 2D backgrounds: paused offscreen, disposed cleanly, and replaced by a palette-derived static gradient when JavaScript, Canvas 2D, or motion is unavailable.

<CausticsBackground Palette="FancyPalettes.Glacier">
    <article>Semantic content</article>
</CausticsBackground>

See CausticsBackground, TopographicBackground, and RainBackground for parameter references and composition examples.

Interaction and scroll

ScrollVelocity reacts to scroll speed, CompareReveal reveals one piece of content against another by dragging a handle, and Lens shows a pointer-following magnified view of an image over semantic content.

<CompareReveal BeforeLabel="Muted" AfterLabel="Vivid">
    <Before><img src="/images/before.jpg" alt="Before" /></Before>
    <After><img src="/images/after.jpg" alt="After" /></After>
</CompareReveal>

See ScrollVelocity, CompareReveal, and Lens for parameter references and composition examples.

Optional WebGL preview

SyntaxCircus.FancyBlazor.WebGL is a separately installed preview companion. It publishes at the same version as the core package while keeping Three.js and the GPU lifecycle out of applications that do not opt in.

dotnet add package SyntaxCircus.FancyBlazor.WebGL

builder.Services.AddFancyBlazorWebGl();

This also registers core defaults. Call AddFancyBlazor(...) first when you need to configure the shared motion, quality, pause, or diagnostics options.

<HolographicSurface Palette="FancyPalettes.Witchlight" Interactive>
    <article>Semantic content remains ordinary HTML.</article>
</HolographicSurface>

The companion vendors the unmodified official Three.js r184 ESM build under MIT and requires no Node, npm, CDN, or manual script import. Its visual direction was informed by the ThreeUI effect catalog, but it includes no ThreeUI source code or assets. Treat its components, parameters, defaults, and visual output as preview API that may change before 1.0.

Optional UI companion

SyntaxCircus.FancyBlazor.UI is a separately installed companion for styled, accessible controls: buttons, links, badges, cards, and a navbar. It publishes at the same version as the core package and depends only on core—installing it never pulls in the WebGL preview.

dotnet add package SyntaxCircus.FancyBlazor.UI

builder.Services.AddFancyBlazorUi();

This also registers core defaults. Call AddFancyBlazor(...) first when you need to configure the shared motion, quality, pause, or diagnostics options.

<FancyNavbar AriaLabel="Site">
    <Brand><FancyLink Href="/">Acme</FancyLink></Brand>
    <Links><FancyLink Href="/pricing">Pricing</FancyLink></Links>
    <Actions><FancyButton>Sign in</FancyButton></Actions>
</FancyNavbar>

Every control is a native HTML element (<button>, <a>, <span>, <article>, <nav>, <table>, …) with typed theme tokens. All but one are JavaScript-free; FaqAccordion is the sole exception, using a small module to own click-driven open/closed state. Controls coexist cleanly with Bootstrap 5's Reboot and other CSS frameworks: see Bootstrap 5 compatibility. Treat its components, parameters, defaults, and visual output as preview API that may change before 1.0.

Preview components

UI companion components

Components intentionally compose:

<ShaderBackground>
    <Reveal Effect="RevealEffect.BlurUp">
        <Tilt Glare>
            <GlowBorder Color="currentColor">
                <article>Existing content</article>
            </GlowBorder>
        </Tilt>
    </Reveal>
</ShaderBackground>

Global defaults

builder.Services.AddFancyBlazor(options =>
{
    options.MotionPreference = FancyMotionPreference.RespectSystem;
    options.Quality = FancyQuality.Auto;
    options.PauseWhenHidden = true;
    options.PauseWhenOffscreen = true;
    options.EnableDiagnostics = false;
});

Reduced motion is respected by default. Decorative canvases and glare layers are hidden from assistive technology, wrapper components add no tab stops, and continuous rendering stops while hidden or offscreen.

Documentation and examples

• Getting started
• Component guides and API tables
• HolographicSurface preview guide
• Palettes and styling
• Accessibility
• Performance
• Hosting modes
• Deploy the interactive demo container
• Troubleshooting
• Expressive effects: what to expect
• Expressive-effects demo
• Spatial surfaces
• Spatial-surfaces demo
• WebGL surface showcase
• Narrative motion
• Narrative-motion demo
• Interaction feedback
• Interaction-feedback demo
• CSS-first catalog
• CSS-first catalog demo
• Composition and authoring
• Composition-and-authoring demo
• Atmosphere-and-accents demo
• Core-kinetic-catalog demo
• Bootstrap 5 compatibility
• UI companion demo
• Changelog
• Compiling Interactive Auto demo

Validation

dotnet restore SyntaxCircus.FancyBlazor.slnx
dotnet build SyntaxCircus.FancyBlazor.slnx --no-restore --configuration Release
dotnet test SyntaxCircus.FancyBlazor.slnx --no-build --configuration Release
dotnet pack src/SyntaxCircus.FancyBlazor/SyntaxCircus.FancyBlazor.csproj --no-build --configuration Release --output artifacts/release-preview
dotnet pack src/SyntaxCircus.FancyBlazor.WebGL/SyntaxCircus.FancyBlazor.WebGL.csproj --no-build --configuration Release --output artifacts/release-preview
pwsh eng/verify-docs.ps1
pwsh eng/verify-package.ps1 -PackageDirectory artifacts/release-preview
pwsh eng/verify-webgl-package.ps1 -PackageDirectory artifacts/release-preview -CorePackageDirectory artifacts/release-preview
pwsh eng/verify-release-packages.ps1 -PackageDirectory artifacts/release-preview

Install the Playwright browser once before the first local browser-test run; the exact command is documented in AGENTS.md.

Contributing and license

Read AGENTS.md before changing public behavior or vendored assets. FancyBlazor is MIT licensed; see LICENSE. Bundled shader.gallery and Three.js notices are in THIRD-PARTY-NOTICES.md.