Avara UI
Avara UI

Folder

A tactile folder — unified skeleton cards (or your own photos) tuck behind a frosted-glass front pocket.
The back panel and its tab are one continuous squircle path, the pocket is frosted glass that tilts open in 3D, and the cards inside lift into a shallow arc on hover, tap or focus. Give it a color and the pocket, icon and cards all derive their shades from it in OKLCH. Pass files with thumbnails to show real photos, names to get hover tooltips, or switch on interactive to make it a drag-and-drop upload target with progress bars — that example lives on the File Upload page.
Explore the different variations of the Folder — each example shows a live preview with the exact code to copy. Hover a folder to open it.

Folder

Hover, tap or focus the folder to fan the cards out.

peek
is how many skeleton cards to show when no files are given — 0 is an empty folder, 3 (default) is filled.
size
is the folder width in pixels; height, tab, corner radius and card sizes all derive from it.
color
defaults to a soft tint of --primary (lightness 0.88, chroma at 40%), so the folder — body, pocket, icon and the peeking cards — follows your theme preset and the colour picker above without going heavy. Pass any CSS colour to pin one.
Peek (cards)3
Size260px
Pocket blur10px

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Two builds, same props and file — install one.

Install Folder

npx shadcn@latest add @algorize-ui/folder

components/custom/blocks/FolderBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Step 1 installs these for you. Run them yourself only if you are adding Folder to an existing project by hand. The cn helper and lucide-react are not listed — the installation guide covers them once for every component.

tooltip is a component, not a package — the shadcn CLI installs it as source files.

npx shadcn@latest add @algorize-ui/tooltip

gsap is an npm package.

npm install gsap

Examples

Fan on hover

Hover a card for its name. Use the arrows — or drag a card sideways — to page through; the window wraps at either end.

files
is the list peeking out. Without thumb each one renders as a unified skeleton card; name shows in a tooltip while the fan is open. Past five, the fan pages.

Icon

Pick an icon — it and the pocket take their shades from the theme colour chosen at the top of the page.

icon
is any lucide icon component; it sits centred on the front pocket and is darkened from color by a fixed OKLCH amount, so it stays legible on light and dark bodies alike.

Photos

Drag a photo sideways — or swipe it with a thumb — to page through; the arrows do the same.

files
entries with a thumb URL become photo cards — the picture is clipped to the card's rounded corners and fans out like the rest.

Features

Discover the Folder's capabilities for presenting a group of files as one tactile object.

One silhouette

The tab and body are a single rounded path, so the join never shows a notch and every corner — including the slant — is a true squircle.

Colour-derived shades

Pocket, icon and skeleton cards are computed from color in OKLCH, so any base colour — near-black included — stays readable.

Fits the room

The fan measures its nearest clipping ancestor and tightens the gap — then drops a card — rather than overflowing on a narrow screen.

Reachable everywhere

Hover opens it on desktop; a tap toggles it on touch; focus opens it from the keyboard. Every animation respects prefers-reduced-motion.

Best Practices & Guidelines

Leave headroom above the folder

The fan lifts cards roughly half the folder's height above it and the arrows sit just outside its width. Give the folder that space, and avoid overflow-hidden on its immediate parent.

Do not double up the click

An interactive folder spends its click on the file picker, so tap-to-toggle is off there. If an ancestor already handles clicks, pass toggleOnClick= and focusable so the fan stays keyboard-reachable.

Props Reference

<Folder> Props

PropTypeDefaultDescription
labelstring—Title under the folder.
countstring—Count / subtitle line. Falls back to "{n} items", or "Drop files or click" when interactive.
colorstringtint of --primaryFolder body colour — any CSS colour. By default a pastel of the theme colour (FOLDER_THEME_TINT: lightness 0.88, chroma at 40%). Pocket, icon and skeleton cards derive their shades from it.
iconLucideIcon—A lucide icon component shown on the front pocket.
filesFolderFile[]—{ thumb?, name?, progress? } — photo, skeleton card, or both; name shows in a tooltip on hover.
peeknumber3Skeleton cards to show when no files are given.
openboolean—Force the fan open or closed. Omit to let hover, tap, focus and drag drive it.
blurnumber10Frosted-glass blur on the pocket, in px.
sizenumber260Folder width in px. Height derives from it.
progressnumber—Overall upload progress 0–100 — drives the bar across the pocket while below 100.
stickersReactNode—Extra decoration on the pocket (emoji, etc.) — sits under the icon.
showLabelbooleantrueShow the title.
showCountbooleantrueShow the count line.
interactivebooleanfalseEnable drag-and-drop + click-to-browse.
toggleOnClickboolean!interactiveTap toggles the fan — the touch/keyboard path to the hover reveal. Turn off when an ancestor owns the click.
focusablebooleanfalseJoin the tab order and open the fan on focus without a tap toggling it — for when toggleOnClick is off.
acceptstring—Passed to the hidden file input.
multiplebooleantrueAllow picking several files at once.
onFiles(files: File[]) => void—Fires with dropped or selected files.
onRemoveFile(index: number) => void—Shows an × on each fanned card, reporting the file's index within files.
classNamestring—Merged onto the root.

SkeletonCard

Also exported. The placeholder "document" the folder draws for files without a thumb — reuse it anywhere you need a pretend file so the language stays consistent.