# Open envelope

An isometric shadcn/ui inbox-full state: an open envelope with a document pushed out and an alert badge, with its heading, copy and buttons as props.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available for the docs, pricing and about pages: append `.md` to the URL or send an `Accept: text/markdown` header (the home page answers the header too). An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## At a glance

- **Good for:** Inbox full and storage limit screens in mail apps; Quota reached and upgrade prompts in SaaS products; File storage and attachment limit warnings; Empty and overflow states for messaging tools
- **Category:** Communication · **Type:** Objects · **Style:** Line, Flat, Dark mode
- **See it:** [Live preview](https://www.craftui.space/docs/isometrics/open-envelope) · [Screenshot](https://www.craftui.space/llms.md/preview/open-envelope.5f42ee82.jpg)

![Open envelope](https://www.craftui.space/llms.md/preview/open-envelope.5f42ee82.jpg)

## Install

```bash
pnpm dlx shadcn@latest add https://www.craftui.space/r/open-envelope.json
```

This is a paid item (ISO-CX14WM): the install needs a craftUI plan or a purchase of it. Signed in, the docs page gives your personal install command. Plans: https://www.craftui.space/pricing

## Usage

```tsx
import OpenEnvelope from "@/components/isometric/open-envelope";

export default function Page() {
  return <OpenEnvelope />;
}
```

With no props it renders with demo content; pass your own through the props below.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionLabel` | `string` | `"Upgrade storage"` | Label of the main button, up to about 18 characters. An empty string hides it. |
| `onAction` | `() => void` | — | Called when the main button is clicked. |
| `secondaryLabel` | `string` | `"Clear space"` | Label of the second button, up to about 18 characters. An empty string hides it. |
| `onSecondary` | `() => void` | — | Called when the second button is clicked. |
| `children` | `ReactNode` | — | Your own actions under the copy, in place of the two built-in buttons. |
| `alert` | `string` | `"!"` | Mark on the alert badge: "!" (default) is a drawn exclamation mark; any other short mark, up to three characters (a count), is printed. An empty string leaves the badge out. |
| `tone` | `IsoTone` | `"primary"` | Brand colour: a theme token name (primary, destructive, chart-2…) or any CSS colour. It shows on the alert badge; the envelope and the document stay neutral. |
| `variant` | `IsoVariant` | `"ink"` | "ink" (default): a fine outline with a whisper of shading on the walls. "line": the outline alone, faces the colour of the page. "soft", "duotone" and "solid" are the lit, coloured looks. |
| `strokeWidth` | `number` | `0.23` | Line weight: in `ink` and `line` the default 0.23 is a 1 px outline at any size (0.3 is the 1.3 px of the larger scenes). |
| `active` | `boolean` | — | Pushes the document out each time it turns true (hover, focus, new mail…), tucking it back in first. Left out, it is pushed out once when the envelope scrolls into view. Pass false to keep it out and still until you say. |
| `loop` | `boolean` | `false` | Tuck the document back in and push it out again after a long hold (while `active`, or always when `active` is left out). Off (default) suits a state people sit in front of. |
| `view` | `"front" \| "isometric"` | `"front"` | How it faces: "front" (default) turns it square to the screen, level and plumb; "isometric" shows it at the isometric three-quarter angle. |
| `grid` | `boolean` | `false` | Dashed construction grid on the floor. |
| `rotate` | `IsoRotate` | `"pointer"` | Let the viewer turn the envelope: "pointer" (leans toward the pointer and settles back), "drag" (drag sideways or use the arrow keys), or "off". |
| `orbit` | `IsoOrbit` | — | How far it turns, in degrees: a number for both ways, or [min, max]. Default 16 in the front view, [-14, 24] in the isometric one. |
| `title` | `string` | — | Accessible description of the illustration. Without it the envelope is decorative and the copy speaks for it. |
| `artClassName` | `string` | — | Classes for the illustration alone; size it with width (it keeps its aspect ratio). Default `w-50` in the front view, `w-60` in the isometric one. |
| `className` | `string` | — | Classes for the wrapper of the whole state (it is a centred column, `max-w-sm` wide). |
| `heading` | `string` | `"Your mail is full"` | Heading under the art, up to about 28 characters. An empty string hides it. |
| `description` | `string` | `"Your inbox is out of space. Clear some by deleting files, or upgrade your stor…` | The line under the heading: one or two short sentences. An empty string hides it. |
| `onPlayEnd` | `() => void` | — | Called each time the beat has played and settled. |

## Files

The install adds:

- `components/isometric/open-envelope.tsx`
- `components/isometric/iso-line.tsx`
- `components/isometric/iso-core.tsx`

npm dependencies (installed for you): `motion`.

shadcn/ui components it uses (the shadcn CLI adds any that are missing): `button`.