Skip to content
VenusUI
Get started

Photo Folder

A folder that opens on hover and fans out the photos inside it.

Preview

Installation

npx shadcn@latest add @venusui/photo-folder

Run this in a project set up with shadcn. If you haven’t set it up yet, run npx shadcn@latest init first.

Files added to your project

Paths use the default shadcn aliases. The CLI follows the aliases in your components.json.

  • @/components/ui/photo-folder.tsx

Usage

The code behind the preview above.

photo-folder-demo.tsx

import { PhotoFolder } from "@/components/ui/photo-folder"

// Photos: Unsplash (free under the Unsplash License).
const photo = (id: string) => `https://images.unsplash.com/photo-${id}?w=480&h=600&fit=crop&auto=format&q=75`

const FOLDERS = [
  {
    label: "Japan",
    color: "oklch(0.7 0.14 245)",
    images: [
      { src: photo("1493976040374-85c8e12f0c0e"), alt: "A pagoda at the end of an old street in Kyoto at dusk" },
      { src: photo("1478436127897-769e1b3f0f36"), alt: "A tunnel of red torii gates" },
      { src: photo("1490806843957-31f4c9a91c65"), alt: "Mount Fuji framed by cherry blossoms" },
    ],
  },
  {
    label: "Up north",
    color: "oklch(0.74 0.13 160)",
    images: [
      { src: photo("1476610182048-b716b8518aae"), alt: "A waterfall over green cliffs at sunset" },
      { src: photo("1531366936337-7c912a4589a7"), alt: "Green and purple northern lights over snow" },
      { src: photo("1504893524553-b855bce32c67"), alt: "A river winding through a mossy canyon" },
    ],
  },
  {
    label: "Tokyo nights",
    color: "oklch(0.68 0.16 300)",
    images: [
      { src: photo("1528360983277-13d401cdc186"), alt: "A red paper lantern in a narrow alley at night" },
      { src: photo("1540959733332-eab4deabeeaf"), alt: "A neon-lit shopping street full of people" },
      { src: photo("1513407030348-c983a97b98d8"), alt: "Tokyo Tower above the city at twilight" },
    ],
  },
]

export default function PhotoFolderDemo() {
  return (
    <div className="flex flex-wrap items-end justify-center gap-x-6 gap-y-14 pt-28">
      {FOLDERS.map((folder) => (
        <PhotoFolder key={folder.label} {...folder} className="w-44 sm:w-52" />
      ))}
    </div>
  )
}

API reference

PropTypeDefaultDescription
images{ src: string; alt: string }[]—Photos in the folder. Up to five fan out; the count includes all of them.
labelstring—Folder name, shown under it and used as its accessible name.
descriptionstring—Second line under the name. Defaults to the number of photos.
colorstringoklch(0.7 0.14 245)Folder color: any CSS color. The back and the lighter top of the flap are mixed from it.
openboolean—Controlled open state. Leave unset to open on hover and toggle on click.
onOpenChange(open: boolean) => void—Called when hovering or clicking opens or closes the folder.

All <button> props except children, e.g. onClick to open a gallery.

Requirements

  • React 19 and Tailwind CSS v4.

Customization

  • Size it with a width class, e.g. className="w-44"; the folder keeps a 5:4 shape.
  • Leave room above it (about 60% of its height): the photos fan out over the top.
  • Use onClick (or wrap your own logic around open) to open a full gallery when the folder is clicked.

Accessibility

  • It’s a button with aria-expanded, named after the folder and its photo count; the photos’ alt texts are its description.
  • Hover opens it; a click, tap, Enter or Space keeps it open or closes it, so touch and keyboard users can open it too.
  • With reduced motion the photos and flap move without animation.

Troubleshooting

The fanned-out photos are cut off.
A parent has overflow-hidden, or there’s too little space above the folder. Add top padding or margin.
Unknown registry "@venusui"
Your shadcn CLI couldn’t find the namespace in the shadcn registry index. Use the latest CLI (npx shadcn@latest), install by URL, or register it with its address: npx shadcn@latest registry add @venusui=https://venusui.com/r/{name}.json.
No components.json found
Run npx shadcn@latest init in your project first.
Loading preview

A card that tilts in 3D toward the pointer with spring physics.

Loading preview

Stacked cards with the next ones peeking out; Next sends the top card to the back.

Loading preview

Envelope

Interactive

A sealed envelope that opens on hover or click: the flap folds back and the letter slides out.