React Rainfall

Animated precipitation and optional weather layers for any positioned element. Pick a profile, then adjust only what you need.

Installation

Install the package, then import its stylesheet once in your app.

bash
npm install react-rainfall

Basic usage

Rain fills its parent element, so give the parent position: relative and a height. The rain layer is decorative and never intercepts pointer events.

tsx
import { Rain } from "react-rainfall";
import "react-rainfall/dist/style.css";
function WeatherPanel() {
return (
<div style={{ position: "relative", height: 600 }}>
<Rain />
</div>
);
}

Profiles

A profile is a preset for the whole scene. It supplies defaults for the properties it defines, and any prop you pass yourself takes precedence.

profile
string
Applies a preset for drop count, style, speed, angle, impacts and weather layers. Start here, then override individual props.
Default: none
  • light-drizzle
  • steady-rain
  • passing-shower
  • heavy-rain
  • misty-rain
  • snow
  • hail
  • cartoon
  • rainbow

Particles

Control how many particles fall, what they look like and how fast they move.

numDrops
number
Target particle count before quality scaling and the maxDrops cap. Angled rain adds extra drops so the edges stay covered.
Default: profile value, else parent width ÷ 25
dropletColor
rgb() string
Particle color. Use rgb() syntax, for example rgb(170, 195, 255).
Default: rgb(183, 212, 255)
dropStyle
string
Particle shape. Choosing one sets a matching baseline size and opacity unless you also set size or dropletOpacity.
Default: streak
  • streak
  • pixel
  • soft
  • glow
  • orb
  • snowflake
  • hailstone
  • cartoon
size
string
Particle size. When dropStyle is set explicitly, its own baseline size applies unless size is also provided.
Default: profile or style default
  • short
  • default
  • long
dropletOpacity
number, 0 to 1
Particle opacity. An explicitly chosen dropStyle supplies its own baseline unless this prop is set.
Default: 0.5
duration
string
Controls how fast particles fall.
Default: normal
  • slow
  • normal
  • fast
angle
number, degrees
Tilt from vertical. Positive values drift right and negative values drift left. Clamped to −75 through 75.
Default: 0
depth
boolean
Varies size, speed, opacity and impact scale per particle to suggest foreground and background layers.
Default: false

Impacts

Impacts play where a particle reaches the bottom edge of the parent.

showImpact
boolean
Shows an impact when a particle lands.
Default: true
impactStyle
string
A small upward splash, a wider spray, or expanding water rings.
Default: splash
  • splash
  • spray
  • ripple
impactThickness
number, 0.5 to 8
Impact line thickness in pixels.
Default: 2.5
impactOpacity
number, 0 to 1
Impact opacity.
Default: 0.65
impactDensity
number, 0 to 1
Fraction of drops that make an impact. The selection is stable per drop, so impacts do not flicker.
Default: 0.25

Clouds

Animated clouds drift behind the precipitation. Turn them on with showClouds, or with rainFromClouds.

tsx
<Rain
profile="heavy-rain"
angle={18}
showClouds
cloudCount={5}
showLightning
lightningFrequency={15}
dropStyle="pixel"
depth
/>
showClouds
boolean
Shows animated clouds behind the precipitation.
Default: false
cloudProfile
string
Cloud appearance.
Default: puffy
  • soft
  • puffy
  • rolling
  • cartoon
cloudCount
number, 0 to 24
How many clouds to render.
Default: 3
cloudSize
number, px
Approximate cloud width in pixels.
Default: 320
cloudSpeed
number, seconds
Time for a cloud to drift in one direction before easing back.
Default: cloud profile value
cloudOpacity
number, 0 to 1
Cloud opacity.
Default: cloud profile value
cloudDrift
number, px
Horizontal cloud travel in pixels. Negative values drift left.
Default: cloud profile value
cloudBlur
number, 0 to 40
Cloud blur in pixels.
Default: cloud profile value
cloudColor
CSS color
Color of the cloud shapes.
Default: cloud profile value
rainFromClouds
boolean
Clusters drops under the clouds. Clouds turn on automatically and profile-based drop counts are reduced. An explicit numDrops is respected.
Default: false

Lightning

Lightning is a visual flash only. There is no thunder audio.

showLightning
boolean
Enables lightning flashes at random intervals.
Default: false
lightningFrequency
number, seconds
Average time between flashes.
Default: 9
lightningFlashDuration
number, 80 to 4000
Flash duration in milliseconds.
Default: 450
lightningColor
CSS color
Flash color.
Default: #dfe6ff

Wind

Wind slants the rain and varies the slant over time in gusts.

showWind
boolean
Adds a directional slant and gradual gust drift.
Default: false
windProfile
string
Wind preset. Selecting one enables wind, so showWind is not needed.
Default: none
  • subtle
  • breezy
  • gusty
  • squall
windVariation
number, 0 to 30
Wind strength, in degrees of slant.
Default: 8
gustFrequency
number, seconds
Base time for one gust cycle.
Default: 8

Glass surface

Render the rain as if it falls on a window instead of through open air.

surface
string
Set to glass for a fogged pane with animated water runs.
Default: air
  • air
  • glass
glassFog
number, 0 to 1
Strength of the fog overlay.
Default: 0.18
glassRefraction
number, 0 to 12
Backdrop blur in pixels.
Default: 2

Rendering and performance

The DOM renderer is the default. The canvas renderer draws precipitation and impacts together, which removes most particle DOM nodes. Clouds, glass, wind and lightning stay DOM/CSS in both.

tsx
<Rain renderer="canvas" profile="heavy-rain" quality="high" maxDrops={1200} />
renderer
string
Choose DOM or canvas particles.
Default: dom
  • dom
  • canvas
quality
string
Scales particle count: low uses 40%, medium 70%, high 100%.
Default: high (DOM), medium (canvas)
  • low
  • medium
  • high
maxDrops
number, 0 to 5000
Upper limit on particles, applied after quality scaling.
Default: 600 (DOM), 400 (canvas)

Playback

Start, pause and scale the animation, and decide when it should stop on its own.

intensity
number, 0 to 1
Scales how many particles are active. Can also be changed through the ref or hook.
Default: 1
playing
boolean
Starts or pauses the animation. Can also be controlled through the ref or hook.
Default: true
pauseWhenHidden
boolean
Pauses the animation while the browser tab is hidden.
Default: false
respectReducedMotion
boolean
Follows the system prefers-reduced-motion setting. Leave false to always animate.
Default: false

Imperative controls

Use a ref when controls should act directly on Rain without mirroring animation state in React state. Use useRainfall when other UI needs to show the current play state and intensity.

tsx
const rainRef = useRef<RainHandle | null>(null);
<Rain ref={rainRef} profile="heavy-rain" />
<button onClick={() => rainRef.current?.triggerLightning()}>
Flash lightning
</button>
start()
ref method
Resumes the animation.
stop()
ref method
Pauses the animation.
setIntensity(value)
ref method, 0 to 1
Scales the number of active particles.
triggerLightning()
ref method
Requests a flash even when automatic lightning is disabled.
useRainfall(initial)
hook
Returns ref, props, playing, intensity and the same control methods.