# Home Widget
URL: https://remocn.dev/docs/product-scenes/home-widget

A phone home screen jiggles, a widget is picked from the gallery and dropped in, and its numbers count up.

- Install: `npx shadcn@latest add @remocn/home-widget`
- Vibe: playful
- Natural length: 256f @ 30fps

## Installation

```bash
npx shadcn@latest add @remocn/home-widget
```

## Usage

```tsx
// src/Root.tsx
import { Composition } from "remotion";
import { HomeWidget } from "@/components/remocn/home-widget";

const HomeWidgetScene = () => (
  <HomeWidget
    appName="Acme"
    widgetName="Renders"
    size="medium"
    bars={[42, 58, 36, 70, 64, 88, 76]}
  />
);

export const RemotionRoot = () => (
  <Composition
    id="HomeWidget"
    component={HomeWidgetScene}
    durationInFrames={290}
    fps={30}
    width={1280}
    height={720}
  />
);
```

The home screen icons jiggle, the plus opens a widget gallery, the cursor picks a size and the widget lands on the page. Its headline number then counts up and the last bar grows live. Set `size` to `small` or `medium`, `stat` for the number and `bars` for the week; `lines` are the three captions beside the phone. Ships light (daytime wallpaper) and dark (dusk).

The ground is a live gradients.sh shader (`GshGround`), installed with the component as `@remocn/gsh`. Pick another look with the `ground` preset prop.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `appName` | `string` | `"remocn"` | Name on the placed app icon |
| `widgetName` | `string` | `"Renders"` | Widget name in the gallery |
| `widgetDescription` | `string` | `"Track renders and views at a glance."` | Description line under the widget in the gallery |
| `size` | `"small" \| "medium"` | `"medium"` | Widget size picked in the gallery |
| `stat` | `{ label: string; from: number; to: number; delta: string }` | — | Headline stat: label, count-up range and delta text |
| `bars` | `number[]` | `[42, 58, 36, 70, 64, 88, 76]` | Seven daily values; the last bar grows live |
| `accent` | `string` | `"#3B5BFD"` | Accent color for highlights, buttons and progress |
| `speed` | `number` | `1` | Playback speed multiplier for the whole timeline |
| `theme` | `"light" \| "dark"` | `"light"` | Light or dark palette |
| `lines` | `[string, string, string]` | — | Three captions beside the phone, one per beat |
| `ground` | `GshPresetId` | — | gradients.sh preset id for the backdrop shader |
| `groundParams` | `Partial<GradientParams>` | — | Overrides for the backdrop shader parameters |

## Use when
- A launch for an app with a home-screen widget where setup should look effortless.
- A feature announcement that ends on live data (a counter and weekly bars) instead of a static icon.
- A short vertical clip with three off-device lines: edit, pick a size, glance.

## Don't use when
- You want a lock-screen status that counts down in real time — use `live-activity`.
- The scene is a store page and install flow — use `app-store-listing`.
- You want incoming alerts piling up instead — use `notification-avalanche`.