AnimatedBackground

A composable wrapper for decorative animated layers. Handles content layering, reduced-motion friendly timing, and ambient intensity controls.

View source Installation

Preview

Ambient containerComposes any decorative preset

Hero section with depth

Use the wrapper to keep content readable while decorative layers animate underneath.

Import

import { AnimatedBackground, GradientOrbs } from '@velocityuikit/velocityui'

Props

Prop	Type	Default	Description
background	`ReactNode`	—	Decorative layer rendered behind the content, such as GradientOrbs or GridGlow.
contentClassName	`string`	—	Optional className applied to the foreground content wrapper.
intensity	`'subtle' \| 'medium' \| 'vivid'`	`'medium'`	Controls blur, scale, and overall ambient presence.
speed	`'slow' \| 'medium' \| 'fast'`	`'medium'`	Adjusts animation timing for child ambient effects.
interactive	`boolean`	`false`	Allows pointer events to pass through to the background layer when needed.

Examples

Hero shell

Wrap content and keep decorative motion isolated behind it.

import { AnimatedBackground, Button, GradientOrbs } from '@velocityuikit/velocityui'

export default function Example() {
  return (
    <AnimatedBackground
      background={<GradientOrbs variant="hero" />}
      intensity="medium"
      speed="slow"
      style={{ borderRadius: '1.5rem', border: '1px solid var(--vui-border)' }}
      contentClassName="hero-content"
    >
      <div style={{ padding: '2rem', maxWidth: '28rem' }}>
        <h2 style={{ margin: 0 }}>Launch faster</h2>
        <p style={{ marginTop: '0.75rem', color: 'var(--vui-text-muted)' }}>
          Add ambient motion behind marketing or auth content without disturbing layout.
        </p>
        <div style={{ marginTop: '1rem' }}>
          <Button>Get started</Button>
        </div>
      </div>
    </AnimatedBackground>
  )
}

Low-motion panel

import { AnimatedBackground, GridGlow } from '@velocityuikit/velocityui'

export default function Example() {
  return (
    <AnimatedBackground
      background={<GridGlow variant="panel" />}
      intensity="subtle"
      speed="slow"
      style={{ borderRadius: '1rem', minHeight: 240 }}
    >
      <div style={{ padding: '1.5rem' }}>Dashboard content</div>
    </AnimatedBackground>
  )
}

Theming

Apply a named theme class to <body> or any parent element. All VelocityUI components inside that element will automatically adopt its colors, shadows, and effects. Combine with a density modifier for complete control:

/* Pick any named theme */
<body class="vui-theme-ocean">

/* Add a density modifier (optional) */
<body class="vui-theme-midnight vui-density-compact">
<body class="vui-theme-construction vui-density-spacious">

/* Available themes */
/* default  midnight  ocean  dark-cyan  tangerine */
/* construction  glass  soft  high-contrast  monochrome-red */

/* Available densities */
/* vui-density-compact  vui-density-comfortable  vui-density-spacious */