# Counter Curtain
> A curtain that covers the page while it loads, counting from 0 to 100 with the fonts and hero images, then lifts as the headline rises out of its masks underneath, on one clock.
An animated React component from KeyframeUI, installed as source with the shadcn CLI. Built with React and Tailwind CSS.
- Docs and live preview: https://keyframeui.com/components/counter-curtain
- Tags: Preloader, Hero, Text
- npm dependencies: clsx, tailwind-merge
## Installation
Register the @keyframeui registry in `components.json` once per project:
```json
{
"registries": {
"@keyframeui": "https://keyframeui.com/r/{name}.json"
}
}
```
Then add the component. It lands in `components/ui/counter-curtain.tsx`, and the CLI also adds `lib/utils.ts` (the `cn` helper) and installs the npm dependencies:
```bash
npx shadcn@latest add @keyframeui/counter-curtain
```
Or install by URL, without registering the namespace:
```bash
npx shadcn@latest add https://keyframeui.com/r/counter-curtain.json
```
## Usage
The main demo shows typical usage.
### Studio Portfolio
The default counter over a studio's home page. The nav, headline, links and photo each rise as the curtain clears them. Press reload in the address bar to play it again.
Install this demo, with the component included:
```bash
npx shadcn@latest add @keyframeui/counter-curtain-demo
```
```tsx title="components/counter-curtain-demo.tsx"
"use client";
import * as React from "react";
import { CounterCurtain, CounterCurtainLine } from "@/components/ui/counter-curtain";
const photo =
"https://images.unsplash.com/photo-1600585154340-be6161a56a0c?auto=format&fit=crop&w=900&h=1100&q=80";
// The reload button plays it again by remounting it with a new key. On a real
// site, drop `contained` and `once={false}`: it covers the screen, once per
// visit.
export function CounterCurtainDemo() {
const [run, setRun] = React.useState(0);
return (
setRun((r) => r + 1)} />
Okto°Contact
Independent design studio, Oslo
Brands thatmove beforethey speak.
Identity, websites and motion for companies that would rather be felt
than explained.
See the work
→
{/* An image rises out of its frame like a line does. */}
);
}
```
## Examples
Finished sections built with Counter Curtain. Each one installs whole, with the component included.
### Launch Page
A custom counter in the drop's colors, with a padded number and a progress bar, on a curtain that falls away. `onComplete` starts the countdown as it goes, so the clock is already ticking when it's uncovered.
Install this demo, with the component included:
```bash
npx shadcn@latest add @keyframeui/counter-curtain-launch-demo
```
```tsx title="components/counter-curtain-launch-demo.tsx"
"use client";
import * as React from "react";
import {
CounterCurtain,
CounterCurtainLine,
CounterCurtainValue,
} from "@/components/ui/counter-curtain";
const photo =
"https://images.unsplash.com/photo-1606107557195-0e29a4b5b4aa?auto=format&fit=crop&w=1000&h=1000&q=80";
const DROP = 2 * 86400 + 14 * 3600 + 9 * 60 + 31; // seconds left when the page opens
// A custom counter: the drop's own type, a padded number and a progress bar
// driven by --counter-progress. onComplete starts the clock as the curtain
// lifts, so it's already ticking when it's uncovered.
export function CounterCurtainLaunchDemo() {
const [run, setRun] = React.useState(0);
const [live, setLive] = React.useState(false);
const replay = () => {
setLive(false);
setRun((r) => r + 1);
};
return (
);
}
```
### Editorial
The default counter set in serif on a stone curtain that slides off to the left. It waits for the three photos to load and decode, so they're sharp from the first frame.
Install this demo, with the component included:
```bash
npx shadcn@latest add @keyframeui/counter-curtain-editorial-demo
```
```tsx title="components/counter-curtain-editorial-demo.tsx"
"use client";
import * as React from "react";
import { CounterCurtain, CounterCurtainLine } from "@/components/ui/counter-curtain";
const image = (id: string) =>
`https://images.unsplash.com/photo-${id}?auto=format&fit=crop&w=900&h=1100&q=80`;
const rooms = [
{ id: "1618221195710-dd6b41faaea6", alt: "A long open living room with a sofa, coffee table and wide windows", caption: "The long room" },
{ id: "1586023492125-27b2c045efd7", alt: "A yellow armchair beside a floor lamp against a white wall", caption: "Reading corner" },
{ id: "1555041469-a586c61ea9bc", alt: "A green velvet sofa on a pale wooden floor", caption: "The snug" },
];
// The default counter, restyled with curtainClassName, leaving to the left.
// It waits for the three photos, so they're decoded and sharp before anything
// is uncovered.
export function CounterCurtainEditorialDemo() {
const [run, setRun] = React.useState(0);
return (
setRun((r) => r + 1)} />
Hollow House
Issue 12 · Autumn
Rooms thathold thelight.
A 1930s terrace in Bergen, opened up from the front door to the garden
and furnished one chair at a time.
);
}
```
## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | | The hero. Wrap each line of the headline, and anything else that should rise in, in `CounterCurtainLine`. Lines rise as the curtain's edge passes them, a beat apart, in reading order. |
| `minDuration` | `number` | `0.8` | Shortest the count can take, in seconds, even when everything has already loaded. Keep it under a second or so: it's a first impression, not a wait. |
| `maxDuration` | `number` | `3` | Longest it waits for loading, in seconds, before lifting anyway. While it waits, the count creeps on its own so it never looks stuck. A click, key press or scroll lands it within a third of a second. |
| `waitFor` | `("fonts" \| "images")[]` | `["fonts", "images"]` | What the count follows: web fonts, and the images in the visible part of the hero, decoded so the reveal doesn't stutter on them. `[]` makes it a plain timed count. |
| `once` | `boolean` | `true` | Play once per browser session. Reloads, the back button and other pages that use it go straight to the content. |
| `storageKey` | `string` | `"counter-curtain"` | The sessionStorage key that remembers it played. Curtains with the same key share it. |
| `direction` | `"up" \| "down" \| "left" \| "right"` | `"up"` | The way the curtain leaves. The lines always rise. |
| `counter` | `React.ReactNode` | | What the curtain shows in place of the default counter. Put `` where the number goes, and use `var(--counter-progress)`, from 0 to 1, for bars, like `scale-x-[var(--counter-progress)]`. |
| `onComplete` | `() => void` | | Called when the count reaches 100 and the curtain starts to lift, or straight away when it's skipped. Start a background video here, so it's already playing as it's uncovered. |
| `contained` | `boolean` | `false` | Cover this element instead of the screen, and leave the page's scroll alone. It starts counting once it's on screen. For a single section, or a preview like the ones here. |
| `curtainClassName` | `string` | | Classes for the curtain, such as its color and font. |
| `className` | `string` | | Classes for the element that wraps the hero. Other props pass through to it. |
| `nonce` | `string` | | Your Content Security Policy's nonce, for the small inline script that puts the curtain up before the page is drawn. If the script is blocked, the curtain is skipped. |
## Source
```tsx title="components/ui/counter-curtain.tsx"
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
/* ─────────────────────────────────────────────────────────
* COUNTER CURTAIN STORYBOARD
*
* cover the first paint is already the curtain. A tiny
* inline script decides before the page under it is
* drawn, so nothing flashes, even before React loads
* count 0 to 100, following the fonts and the hero's
* images. It never lands before minDuration, never
* waits past maxDuration, and creeps while it waits
* so it never looks stuck. A click, key or scroll
* hurries it along
* land 100 holds for a beat
* lift the curtain slides off the page. Its counter sinks
* back as it goes, so the edge wipes it away instead
* of carrying it off
* rise each line rises out of its mask as the edge
* uncovers it, on the same clock as the lift. Lines
* that sit together, like a headline, go in reading
* order, a beat apart
* settle every animation is dropped and the hero is plain
* HTML again
*
* The count writes straight to the DOM and everything that
* moves is a transform on the compositor, so the reveal stays
* smooth while React hydrates underneath it.
* ───────────────────────────────────────────────────────── */
const CURTAIN = {
count: [0.35, 0, 0.65, 1], // the count's shape on a fast connection, as a cubic-bezier
speed: 3, // most of the count it covers in a second, when catching up with loading
crawl: 0.85, // how far the count creeps by maxDuration while assets are still loading
hurry: 0.3, // s left on the clock after a click, key or scroll
hold: 0.1, // s at 100 before the lift; the lift's slow start adds to it
lift: { duration: 0.9, ease: [0.6, 0, 0.15, 1] },
sink: 0.4, // how far the counter falls back during the lift, as a share of the curtain
// `lead`: s a line starts before the edge reaches its middle. `near`: how
// close two lines sit, in line heights, to count as one block and rise in turn.
rise: { duration: 1, ease: [0.16, 1, 0.3, 1], stagger: 0.08, lead: 0.06, near: 0.6 },
} as const;
// A line's resting place while the curtain is down. Keep it in step with the
// class on CounterCurtainLine's inner span.
const HIDDEN = "translateY(115%)";
type Direction = "up" | "down" | "left" | "right";
type Plan = {
once: boolean;
key: string;
min: number;
max: number;
fonts: boolean;
images: boolean;
direction: Direction;
contained: boolean;
skip: boolean;
hidden: string;
t: typeof CURTAIN;
};
type Handle = {
revealed: boolean;
on: (listener: () => void) => () => void;
destroy: () => void;
};
type CurtainRoot = HTMLElement & { __counterCurtain?: Handle };
/**
* The whole sequence, from the first count to the last line settling. It runs
* as an inline