# Folder

> A project tile that holds your actual files: it opens on a hinge, fans real sheets, and takes a dropped file with weight.

A folder in a product is usually a flat icon with a name under it, and uploading into it means opening something else. This one is the upload target and the preview in one tile. The sheets behind its front show your real file names and pictures. A mouse over it leans the front open and fans them, each with its own weight, so they never move in step. Open it and they rise far enough to read and click. Drag a file over and it gapes; let go and a sheet with that name falls in, the folder takes the weight and the count rolls up. If the upload fails, the sheet pops back out and the folder says so.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/folder.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): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/folder
- Registry item (source): https://hairlineui.com/r/folder.json

## Usage

```tsx
import { Folder } from "@/components/folder";

<Folder
  name="Northwind launch"
  files={[
    { id: "1", name: "Brand brief.pdf" },
    { id: "2", name: "Invoice 0412.pdf" },
    { id: "3", name: "Launch notes.md" },
  ]}
/>
```

## With a real upload

Upload in onDropFiles and add the stored files to your list before it resolves. Throw and the sheet comes back out.

```tsx
"use client";
import { useState } from "react";
import { Folder, type FolderFile } from "@/components/folder";

export function ClientFolder({ initial }: { initial: FolderFile[] }) {
  const [files, setFiles] = useState(initial);

  return (
    <Folder
      name="Client uploads"
      files={files}
      onFileOpen={(file) => window.open(`/files/${file.id}`)}
      onDropFiles={async (dropped) => {
        const body = new FormData();
        dropped.forEach((file) => body.append("files", file));
        const response = await fetch("/api/files", { method: "POST", body });
        if (!response.ok) throw new Error("Upload failed");
        const stored: FolderFile[] = await response.json();
        setFiles((list) => [...list, ...stored]);
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | – | Written on the front. |
| `files` | `FolderFile[]` | – | id, name, image, tint. The last three show as sheets. |
| `count` | `number` | – | The total on the front, if you only pass the latest files. |
| `noun` | `string` | `"files"` | What the count counts. |
| `open / defaultOpen` | `boolean` | `false` | Whether the sheets are raised. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when it opens or closes. |
| `onFileOpen` | `(file: FolderFile) => void` | – | Makes raised sheets clickable. |
| `onDropFiles` | `(files: File[]) => Promise<unknown> \| unknown` | – | Turns on dropping. Add the stored files to `files` by the time it resolves; throw to send them back out. |
| `color / foreground` | `string` | `var(--primary) / var(--primary-foreground)` | The folder and the text on its front. |
| `size` | `number` | `240` | Width in px; everything scales from it. It keeps room above for the sheets to rise into. |
| `ref` | `Ref<FolderHandle>` | – | addFiles(files) adds files as a drop would, for your own file picker. |

## States

- **rest**: Three sheets stand behind the glass front, with the front tipped 7° on its hinge.
- **hover**: The front opens to 21° and the sheets fan out, leaning toward the mouse. Keyboard focus does the same without the lean.
- **open**: The sheets rise to be read and clicked, and the front opens to 31°. Escape or a press elsewhere closes it.
- **drag over**: The folder gapes to 40°, the sheets part, and the line on the front turns to "Drop to add".
- **drop**: A sheet falls in from above. As it lands the folder squashes by how fast it was falling, and the count rolls up.
- **failed**: The sheet goes back up and fades, the folder shakes, the count rolls down, and the front says what failed for 2.6s.
- **reduced motion**: Poses change in place and a dropped file appears where it belongs.

## What it handles

Drop targets, optimistic uploads and hover previews usually mean three separate pieces of UI. Here one tile does all of it, and every step is interruptible.

- **Your real upload**: onDropFiles gets the File objects. The sheet falls in straight away, and if your function throws it comes back out with a shake and a message.
- **Interruptions**: Springs carry their speed, so moving the mouse in and out mid-flight curves on from where each sheet is.
- **Real content**: File names, image URLs and tints come from your data. Dropped images preview from the file itself until your upload finishes.
- **Keyboard and phones**: A real button with aria-expanded; focus fans it, Enter opens it, raised sheets are in the tab order, and Escape closes it. Open stays open on touch.
- **Any brand**: One colour prop mixes the back, the glass front and the light along its edge, in light and dark.
- **Screen readers**: The button says the name and count, and uploads and failures are announced in a status region outside it.

## Replaces

folder icon with a label, separate upload dialog, hover preview popover

## Where it fits

- **Project lists**: A grid of projects where each tile shows what is inside before you open it.
- **Client portals**: A folder per client that people drop their documents straight into.
- **File sharing**: Collections with a live count, and files one click from the tile.
- **Asset libraries**: Pass image URLs and the sheets become real thumbnails.

## Notes

- Reduced motion: poses change in place, with no lean, wobble or fall.
- Keep room above it: the height includes the space the sheets rise into, so they never cover what is above the tile.
- The front is the one piece of glass, because the sheets really are behind it. Without backdrop-filter support it is simply a little less blurred.
- Colours come from your theme or the color prop. The small shadows sit on the folder and its sheets only.

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