# Snowfall

> Snow that settles on whatever you wrap: it caps your logo, packs into the gaps between its shapes, and a tap knocks it off.

Snow on a website is usually a layer of dots falling over the page, through the logo and the buttons as if they were not there. Here the snow lands. Wrap your logo, a button or a card and flakes drift down at three depths around it: far ones pass behind it, near ones blur past in front, and the ones in between settle. They build a cap on every top edge that rounds off at the ends, and a full cap sheds snow from its ends. In a logo made of shapes on a plate, the narrow gaps between the shapes catch the snow and fill from the bottom up, so the gaps are drawn in white. Once it is dressed the snowfall thins out and stops, and nothing moves. Tap it and the element jolts: the snow pops up with it, breaks into clumps that crumble to powder as they fall, and it starts to snow again.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/snowfall.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/snowfall
- Registry item (source): https://hairlineui.com/r/snowfall.json

## Usage

```tsx
import { Snowfall } from "@/components/snowfall";

<Snowfall>
  <Logo />
</Snowfall>
```

## Your logo in December

Wrap the header logo only while the season lasts. The mark is read from its own SVG, so it works with the logo you already have; give decorative overlays data-snow="ignore" so snow does not land on them.

```tsx
"use client";
import Link from "next/link";
import { Snowfall } from "@/components/snowfall";
import { Logo } from "@/components/logo";

// From the first of December to the sixth of January.
function isWinter(date = new Date()) {
  const m = date.getMonth();
  return m === 11 || (m === 0 && date.getDate() <= 6);
}

export function HeaderLogo() {
  const logo = (
    <Link href="/" aria-label="Home">
      <Logo className="size-8" />
    </Link>
  );
  return isWinter() ? <Snowfall intensity={0.6}>{logo}</Snowfall> : logo;
}

// On a holiday sale button, with a gentle snowfall that keeps going.
export function SaleButton() {
  return (
    <Snowfall keepFalling>
      <a href="/pricing" className="inline-flex h-11 items-center rounded-full bg-primary px-5 text-primary-foreground">
        Holiday sale · 30% off
      </a>
    </Snowfall>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | One element for the snow to settle on: an inline SVG logo, an image, a button, a link or a card. |
| `snowing` | `boolean` | `true` | Whether snow is falling. Turn it off and the flakes in the air finish their fall; settled snow stays. |
| `intensity` | `number` | `1` | How heavily it snows, from 0.25 to 2. |
| `keepFalling` | `boolean` | `false` | Keep a light snowfall going once the element is dressed, instead of stopping. |
| `shake` | `boolean` | `true` | Knock the snow off when the element is pressed with a pointer, Enter or Space. The press still reaches the element. |
| `onSettled` | `() => void` | – | Called when a snowfall has dressed the element and everything is still. |

## States

- **falling**: Flakes drift down at three depths, each swaying on its own and pushed by a slow wind. The sky above the element starts full, so the first flakes land within a moment.
- **settling**: Landed snow settles in over about 0.15s. Caps grow on every top edge and round off towards the ends; narrow gaps fill from the bottom up. A full cap sheds snow from its nearest end.
- **dressed**: Once about 93% of the room is filled the snowfall eases off over a second or two and stops. Nothing moves, and onSettled is called.
- **shaken**: A press jolts the element up on a spring (about 0.4s). The snow pops up with it in clumps that fall under gravity and crumble to powder, and after 0.7s it starts to snow again.
- **reduced motion**: The element appears already dressed in snow, with no flakes and no shake.

## What it handles

A snow effect is usually a full-page overlay of dots that falls through your content and never stops. Making snow land on a logo means knowing where its edges are, which parts stand in front, where the gaps are, and how much a cap can hold. This reads that from the element itself.

- **Reads your logo**: An inline SVG is drawn once with each shape in its own colour, so the snow knows every edge and which shapes sit on others; images go by their alpha, other elements by their box.
- **Caps and gaps**: Snow builds on every top edge and rounds off at the ends; narrow gaps between raised shapes fill from the bottom up like a channel.
- **Three depths**: Far flakes pass behind the element, near ones blur past in front, and only the middle ones land, so the snowfall has depth.
- **Stops when dressed**: Once the element is covered the snowfall eases off and stops; nothing moves until the next one, or keepFalling keeps a light fall going.
- **Tap to shake**: The element jolts on a spring, the snow pops up with it and breaks into clumps that crumble to powder, then it snows again.
- **Light in any theme**: Snow is lit from above and shaded where it faces down or packs against a wall; on light pages it gets a cool rim so it never vanishes into white.

## Replaces

react-snowfall, snowfall overlay, Christmas snow script, Lottie snow animation, snowstorm.js, seasonal logo artwork

## Where it fits

- **Header logo in December**: Snow settles on your mark when the page opens, then stays still; a tap knocks it off.
- **Holiday sale button**: The call to action wears a cap of snow for the season, with no change to the button itself.
- **Launch and splash screens**: With keepFalling, a light snowfall goes on around the app icon while the app loads.
- **Seasonal campaign pages**: Cards, badges and pricing plans dressed in snow for the holiday version of a landing page.

## Notes

- The snow is drawn on a canvas hidden from assistive tech; the wrapped element keeps its own role, name and focus.
- An inline SVG is read shape by shape from its computed styles, so CSS variables and gradients work; shapes under half opacity and anything marked data-snow="ignore" are skipped. A shape whose outline mostly touches another stands in front of it, and gaps up to about 7% of the element's size between such shapes catch snow. An <img> is read by its alpha (same-origin only); any other element by its box and corner radius. Text inside an SVG is read with a fallback font.
- The canvas reaches past the element on every side for the snowfall, so leave room around it; it takes no clicks.
- It starts when it scrolls into view and stops off screen and in hidden tabs. Once dressed and still it draws nothing until something changes.
- Rendering is WebGL 2: the settled snow is a coarse field drawn smooth and clipped by a fine mask of the shape, the flakes are instanced quads. Without WebGL 2 the element shows as it is.
- Under reduced motion the element appears already dressed in snow, with no flakes and no shake.

License: MIT (https://hairlineui.com/license#components)
