Mantine Scene - Cinematic Backgrounds for Your React Apps

Layer gradients, glowing blobs, star fields, auroras, and more into rich, composable decorative backgrounds — all powered by Mantine.

Introduction

Mantine Scene is a brand-new composable background component for React that lets you build atmospheric, animated backgrounds by stacking visual layers. Think of it as a stage director for your UI — you compose the mood by combining gradients, glow effects, dot grids, star fields, snowfall, auroras, and more, all with first-class Mantine theme integration, responsive props, and accessibility baked in from day one.

This 1.0.0 release ships with 10 composable sub-components, full interactive mouse-tracking support, GPU-accelerated animations, and a complete documentation site with live configurators for every layer type.

What's New in 1.0.0

The Scene Component

The root Scene component acts as a container for all visual layers. It supports fullscreen mode, interactive mouse tracking, and respects prefers-reduced-motion out of the box.

import { Scene } from '@gfazioli/mantine-scene';

function HeroBackground() {return (
    <Scene fullscreen interactive>
      <Scene.Gradient from="violet" to="transparent" animate />
      <Scene.Glow color="blue" size={300} />
      <Scene.StarField count={80} twinkle />
      <Scene.Noise opacity={0.03} />
    </Scene>);}

Enter fullscreen mode Exit fullscreen mode

Root Props:

10 Composable Sub-Components

Every sub-component is a visual layer you can freely compose. Layer order follows DOM order — the last child renders on top.

✨ Scene.Gradient

Radial, linear, or conic gradients with optional rotate or pulse animation. Supports interactive mouse tracking for radial/conic types.

<Scene.Gradienttype="radial"from="violet"to="transparent"fromOpacity={0.2}animateanimationType="rotate"duration={20}/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.Glow

Floating, animated glow blobs. Choose between float, pulse, or breathe animation styles. Supports responsive size and blur props and interactive mouse tracking.

<Scene.Glowcolor="cyan"size={{ base: 200, md: 400 }}blur={{ base: 80, md: 120 }}opacity={0.5}animateanimationType="float"driftX="30px"driftY="20px"/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.DotGrid

Repeating dot patterns with optional stagger (honeycomb) layout, fade masks, and twinkle animation. Supports responsive spacing.

<Scene.DotGridcolor="gray"spacing={{ base: 16, md: 24 }}staggerfade="radial"animate/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.Mesh

Multi-stop radial gradient overlay simulating a mesh gradient. Supports hue-rotate animation and blend modes.

<Scene.Meshstops={[
    { color: 'violet', position: '20% 30%', spread: 50 },
    { color: 'pink', position: '80% 20%', spread: 40 },
    { color: 'blue', position: '50% 80%', spread: 60 },]}animateblend="screen"/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.Noise

SVG-based film grain texture. Add subtle texture to any background with configurable grain, seed, and color tint.

<Scene.Noise opacity={0.03} grain={0.65} type="fractalNoise" tint="blue" />

Enter fullscreen mode Exit fullscreen mode

✨ Scene.StarField

CSS-only star field with deterministic PRNG positioning and twinkle animation across 3 staggered layers. Supports responsive count.

<Scene.StarField count={{ base: 50, md: 100 }} twinkle duration={3} seed={42} />

Enter fullscreen mode Exit fullscreen mode

✨ Scene.StarWarp

Hyperspace warp-speed effect with configurable focal point, direction, and streak trails. Supports responsive count and interactive mouse tracking for the focal point.

<Scene.StarWarpcount={100}speed={1.5}direction="out"trailcolor="white"/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.ShootingStar

Animated shooting star trails at configurable angles and intervals. Multiple lanes with randomized timing for a natural feel.

<Scene.ShootingStarcount={3}angle={215}trailLength={80}speed={1}minInterval={3}maxInterval={8}/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.Snow

Falling snowflakes with horizontal drift and wind control. Supports responsive count for performance-conscious responsive designs.

<Scene.Snowcount={{ base: 30, md: 50 }}speed={1}drift={30}wind={0.2}/>

Enter fullscreen mode Exit fullscreen mode

✨ Scene.Aurora

Shimmering aurora borealis bands with wave animation. Configurable band count, position, and colors.

<Scene.Auroracolors={['green', 'teal', 'cyan']}bands={3}position="top"opacity={0.3}blur={60}/>

Enter fullscreen mode Exit fullscreen mode

Key Features

🎨 Full Mantine Theme Integration

Every color prop accepts MantineColor values, so your backgrounds stay consistent with your theme. Shade overrides are available on components like Glow and DotGrid.

📱 Responsive Props

Key numeric props support Mantine's responsive object syntax. This means you can adjust visual density based on breakpoint — fewer stars on mobile, larger glows on desktop:

<Scene.StarField count={{ base: 40, sm: 60, md: 100 }} /><Scene.Glow size={{ base: 150, md: 400 }} blur={{ base: 60, md: 120 }} />

Enter fullscreen mode Exit fullscreen mode

Responsive props are available on: Glow (size, blur), DotGrid (spacing), StarField (count), StarWarp (count), Snow (count).

🖱️ Interactive Mouse Tracking

Set interactive on the root Scene to enable cursor-driven effects:

• Glow — blob position follows the mouse

• Gradient — radial/conic center follows the mouse

• StarWarp — focal point tracks the mouse

The interactiveEasing prop controls how smoothly elements follow the cursor (0 = sluggish, 1 = instant). Components gracefully fall back to their default positions when the mouse leaves.

♿ Accessibility

• The root component renders with aria-hidden="true" — it's purely decorative

• reducedMotion="auto" respects prefers-reduced-motion by default

• Set reducedMotion="always" to disable all animations, or "never" to force them on

⚡ Performance

• All animations use GPU-accelerated CSS (transform, opacity) — no JavaScript animation loops

• Deterministic PRNG (seeded) for StarField, StarWarp, ShootingStar, and Snow ensures reproducible layouts without runtime randomness

• StarWarp caps at 200 elements; Snow recommends ~80 max for smooth performance

• Responsive count props let you reduce particle counts on lower-powered devices

🎛️ Styles API

Full Mantine Styles API support. Override styles for any part of any sub-component using classNames, styles, or unstyled props. CSS variables are exposed for all dynamic values (e.g., --scene-glow-size, --scene-aurora-duration).

Putting It All Together

Here's a complete example combining multiple layers into a rich hero background:

import { Scene } from '@gfazioli/mantine-scene';

function CosmicHero() {return (
    <Scene fullscreen interactive interactiveEasing={0.08}>
      {/* Base gradient */}
      <Scene.Gradient type="radial" from="indigo" fromOpacity={0.2} animate />

      {/* Mesh overlay */}
      <Scene.Mesh
        stops={[
          { color: 'violet', position: '25% 25%' },
          { color: 'blue', position: '75% 75%' },
        ]}
        blend="screen"
        opacity={0.6}
      />

      {/* Floating glows */}
      <Scene.Glow color="cyan" size={350} top="20%" left="30%" />
      <Scene.Glow color="violet" size={250} top="60%" left="70%" delay={2} />

      {/* Stars */}
      <Scene.StarField count={{ base: 60, md: 120 }} twinkle />
      <Scene.ShootingStar count={2} />

      {/* Subtle texture */}
      <Scene.Noise opacity={0.02} />
    </Scene>);}

Enter fullscreen mode Exit fullscreen mode

Getting Started

Installation

npm install @gfazioli/mantine-scene
# or
yarn add @gfazioli/mantine-scene

Enter fullscreen mode Exit fullscreen mode

Import Styles

Add the styles import to your app entry point:

import '@gfazioli/mantine-scene/styles.css';

Enter fullscreen mode Exit fullscreen mode

Or use the @layer variant for CSS cascade control:

import '@gfazioli/mantine-scene/styles.layer.css';

Enter fullscreen mode Exit fullscreen mode

Requirements

• React 18 or 19

• @mantine/core >= 7.0.0

• @mantine/hooks >= 7.0.0

Links

• 📦 npm package

• 📖 Documentation & Live Demos

• 🔗 GitHub Repository

• 🌐 Mantine Extensions Hub