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>
  );
}

Root Props:

Prop	Type	Default	Description
fullscreen	boolean	false	Cover the entire viewport with position: fixed
interactive	boolean	false	Enable mouse tracking for compatible sub-components
interactiveEasing	number	0.12	Smoothness of cursor tracking (0–1)
reducedMotion	`'auto' \	'always' \	'never'`
zIndex	number	0	z-index in fullscreen mode

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.Gradient
  type="radial"
  from="violet"
  to="transparent"
  fromOpacity={0.2}
  animate
  animationType="rotate"
  duration={20}
/>

---

✨ 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.Glow
  color="cyan"
  size={{ base: 200, md: 400 }}
  blur={{ base: 80, md: 120 }}
  opacity={0.5}
  animate
  animationType="float"
  driftX="30px"
  driftY="20px"
/>

---

✨ Scene.DotGrid

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

<Scene.DotGrid
  color="gray"
  spacing={{ base: 16, md: 24 }}
  stagger
  fade="radial"
  animate
/>

---

✨ Scene.Mesh

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

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

---

✨ 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" />

---

✨ 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} />

---

✨ 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.StarWarp
  count={100}
  speed={1.5}
  direction="out"
  trail
  color="white"
/>

---

✨ Scene.ShootingStar

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

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

---

✨ Scene.Snow

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

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

---

✨ Scene.Aurora

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

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

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 }} />

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>
  );
}

Getting Started

Installation

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

Import Styles

Add the styles import to your app entry point:

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

Or use the @layer variant for CSS cascade control:

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

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