# Folder

> A React animated folder icon whose cards fan out on hover and lift open on click, behind a 3D-tilted glass flap.

- Type: React component (Data Display)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add folder-component`
- Docs: https://wingo-ui.com/components/folder-component

## Interaction

Hover (or tab to it) to fan the three cards out of the folder while the flap tips back, then click, tap, Enter or Space to lift the folder open and send the cards up in a spread. Click again, press Escape, or move the pointer away to drop everything back in.

## Installation

```bash
npx wingo-ui@latest add folder-component
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/folder-component.json`

Files:

- `components/ui/folder-component.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { Folder } from "@/components/ui/folder-component"

export function Demo() {
  return (
    <div className="h-96">
      <Folder label="Design files" />
    </div>
  )
}

// put your own previews on the cards, back to front:
// <Folder color="blue" cards={[<img src="/a.jpg" alt="" />, <img src="/b.jpg" alt="" />, <img src="/c.jpg" alt="" />]} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `"auto" \| "black" \| "white" \| "blue"` | `"auto"` | Color theme of the folder, flap, and cards. Auto is white on light pages and black on dark ones, switched in CSS with the dark class so it never flashes; the others stay fixed in both themes. |
| `backColor?` | `string` | `""` | Any CSS color for the back panel, over the chosen color theme. |
| `flapColor?` | `string` | `""` | Any CSS color for the frosted front flap (it keeps the theme's glass opacity); its outline follows as a lighter shade. |
| `cardColor?` | `string` | `""` | Any CSS color for the three cards; their outline follows as a darker shade. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Overall scale of the folder. Maps to 0.65x (sm), 1x (md), and 1.35x (lg) of the 321 x 270 px base, and carries the cards and flap with it. |
| `spread?` | `number` | `1` | How wide the cards fan out: 1 is the original, 0 stacks them straight, 1.5 fans them further. Scales the sideways offsets and tilts, not the lift. |
| `label?` | `string` | `"Folder"` | Accessible name of the folder button, e.g. the name of the folder. |
| `closeOnLeave?` | `boolean` | `true` | Drops the cards back in when the pointer leaves or focus moves away. Turn it off to keep the folder open until it is clicked again. |
| `defaultOpen?` | `boolean` | `false` | Starts open when uncontrolled. Ignored when open is set. |
| `open?` | `boolean` |  | Controlled open state. Pass it with onOpenChange to drive the folder yourself. |
| `onOpenChange?` | `(open: boolean) => void` |  | Called with the next open state on click, Escape, pointer leave or blur. |
| `cards?` | `ReactNode[]` |  | Content for the three cards, back to front, each filling a 158 x 208 px rounded card (before scaling). Leave it out for the default document lines; an image or a short preview works well. |
| `className?` | `string` |  | Extra classes for the root, which fills its parent and centers the folder. Any other div prop is spread onto it too. |

## Parts

### FolderColor (type)

The color themes: "auto" (white on light pages, black on dark ones) | "black" | "white" | "blue".

## Examples

- **Photo album**: cards takes your own previews, back to front; here three photos in the blue theme.
- **Controlled**: open and onOpenChange drive it from a button; closeOnLeave off keeps the files out until you close it.
- **Empty state**: The small size with a narrow spread above an empty-state message and an upload action.

## See also

- [File manager](https://wingo-ui.com/components/file-manager) ([Markdown](https://wingo-ui.com/components/file-manager.md))
- [File List](https://wingo-ui.com/components/file-list) ([Markdown](https://wingo-ui.com/components/file-list.md))
- [Empty State](https://wingo-ui.com/components/empty-state) ([Markdown](https://wingo-ui.com/components/empty-state.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [Grid Reveal](https://wingo-ui.com/components/grid-reveal) ([Markdown](https://wingo-ui.com/components/grid-reveal.md))

---

Canonical: https://wingo-ui.com/components/folder-component
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt