Skip to content
WingoUI
ComponentsTemplatesDocsPricingAI agentsBlogChangelogContact
Components
Buttons & Actions
ButtonButton GroupCopy ButtonDelete ButtonTheme ToggleToggleToggle Group
Inputs
Avatar UploadCalendarCheckboxColor PickerComboboxCountry SelectCron PickerCurrency InputDate PickerDate Range PickerDate Time PickerDuration PickerEmail InputEmoji PickerFile UploadFilter BuilderInputInput GroupListboxMasked InputMention InputMonth PickerMulti SelectNumber InputOTP InputPassword InputPhone InputRadio GroupRatingSearch InputSegmented ControlSelectSignature PadSliderSwitchTag InputTextareaTime PickerTimezone SelectTree Select
Forms
Address InputBooking WidgetCSV ImportFieldForm WizardInline EditInvoice line itemsRich Text EditorSchema Builder
Navigation
Back To TopBounce SidebarBreadcrumbCommand MenuGlobal SearchGooey NavHook SidebarNav MenuNav TabsPaginationProximity SidebarScroll ProgressSidebarStepsTable Of ContentsTabsTopbarUser MenuWorkspace Switcher
Overlays
Alert DialogContext MenuDialogDrawerDropdown MenuFamily DrawerHover CardPopoverShare DialogSheetShortcuts DialogTooltipTour
Feedback
AlertBannerCookie ConsentEmoji ReactionEmpty StateNotification BellNotification CenterProgressRoute ProgressSetup ChecklistSkeletonSpinnerToast
Data Display
Approval FlowAvatarBadgeCalendar ViewCode BlockComment ThreadContact cardCountdownDescription ListDiff ViewerFile ListFile managerFolderGanttJSON ViewerKbdLog ViewerMarkdownPresenceSchedulerTagTimelineTree View
Tables & Lists
Audit LogData TableDeal PipelineEditable GridKanbanListMembers tablePermissions MatrixTableTask ListVirtual List
Charts & Stats
Animated CounterArea chartBar chartDonut chartFunnel chartGaugeGitHub ActivityHeatmap calendarLeaderboardLine chartRadar chartRadial barSparklineStat CardTrackerTrend badge
Layout
AccordionApp ShellCardCollapsibleDetail LayoutEntity HeaderPage HeaderScroll AreaSeparatorSettings LayoutSplit ViewToolbar
Media
Audio PlayerCarouselCSV ViewerDOCX EditorDOCX ViewerExcel ViewerFile SystemImage compareImage CropperImage GalleryImage LightboxLocation MapPDF ViewerPowerPoint ViewerQR CodeStep PlayerVideo Player
AI Kit
Agent Status CardChat MessageChat ThreadChat WidgetConversation ListFluid OrbGrid RevealMatrix OrbModel PickerPrompt InputReasoning IndicatorRule BuilderSuggestion ChipsTool Call TimelineUsage MeterVoice InputWorkflow Canvas
Text & Effects
Background PatternGravity LettersMarqueeTerminalText AnimateText Rotate
Mobile
Action SheetBottom Tab BarFABHaptic ButtonHero HeaderInstall PromptLarge Title HeaderNotification BannerOnboarding CarouselPicker WheelPull To RefreshSlide To ConfirmSticky CTA BarSwipe DeckSwipeable Tabs
Commerce
Cart drawerCategory pickerCheckout stepsCoupon inputFavorite buttonFilter panelListing cardListing gridOrder trackerPricePrice rangePricing tableProduct galleryQuantity stepperReviewsSeller card
Marketing Sections
App Download SectionBlog Cards SectionCTA SectionFAQ SectionFeature GridFeature ShowcaseHero SectionIntegrations SectionLogo CloudMarketing FooterMarketing HeaderMarketing SectionNewsletter SectionPricing SectionStats SectionSteps SectionTeam SectionTestimonials SectionTimeline SectionVideo Section
Blocks
Admin Dashboard PageAdmin ShellAI Chat PageAPI Keys PageAutomation Builder PageCheckout PageCRM Contact PageCRM Pipeline PageError PagesInbox PageInvoice PageKPI DashboardListing Detail PageLogin PageMarketplace Home PageMarketplace Search PageMarketplace ShellMobile App HomeOnboarding FlowOrder History PagePost Listing WizardPricing PageProfile PageRegister PageSettings PageUsers Admin Page
Templates
About PageAcademy PageAccessibility PageAffiliate PageAgency PageAI Product PageAppointment Booking PageBlog PageBlog Post PageBug Bounty PageCareers PageChangelog PageCommunity PageCompare PageContact PageCustomer Story PageCustomers PageDemo Booking PageDevelopers PageDocs Home PageDownload PageEnterprise PageEvents PageExperts PageFAQ PageFeature PageGlossary PageHelp Article PageHelp Center PageHome Services PageImpact PageIntegration Detail PageIntegrations PageJob Detail PageLanding PageLaunch PageLegal PageManifesto PagePortfolio PagePress PageProduct Tour PagePromo PageReal Estate PageReferral PageResearch Report PageRestaurant PageRoadmap PageROI Calculator PageSecurity PageSolutions PageStartups PageStatus PageStorefront PageSwitch PageTemplate Gallery PageTravel PageWaitlist PageYear in Review Page
Hooks & Utilities
AI ChatChart kitCommerceDate utilsFile exportFile typesFiltersForm validationHapticsInvoicingMotion presetsNavigationNumber formatRelative timeRomanian locationsSpreadsheetText matchTonesUIProvideruseClipboarduseConsentuseControllableStateuseCooldownuseDebounceuseKeyboardInsetuseLocaleuseLongPressuseMediaControlsuseMediaQueryuseOverflowItemsusePersistedStateuseScrollEdgesuseScrollStateuseSelectionuseShortcutuseStickToBottom
GalleryTheme

Media

File System

Media

File System React component for Tailwind CSS v4

Excel ViewerImage compare
Live props
Content
rootLabel
defaultFolderId
Behavior
defaultView
foldersFirst
searchScope
confirmDelete
accept
maxFileSizeNo limit
commandShortcut
locale
Appearance
iconSize
variant
radius
tone
color
folderColor
State
loading
error
Layout
showToolbar
showSidebar
defaultSidebarOpen
sidebarWidth200px
showRecents
defaultPreviewOpen
showPathBar
showStatusBar
showSearch
height640px
Code
import { FileSystem } from "@/components/ui/file-system"

<FileSystem />
  1. Home
  2. Components
  3. Media
  4. File System
Pro

File System React component for Tailwind CSS v4

v1.0.0·Added in 1.4.0

A React file browser in the style of Finder: a sidebar, icons, list, columns and gallery views, a preview panel and Quick Look on real documents.

Browse folders like in Finder. The sidebar lists favorites, locations (Recents and your roots) and colored tags; drag its edge to resize it, the panel button or Alt+⌘S hides it, and in a narrow frame it opens as a sheet. Four views: Icons (a grid of thumbnails), List (Name, Date modified, Size and Kind columns, click a header to sort, the chevron opens a folder in place), Columns (a column per folder level and a preview of the selected file; on phones one level at a time with a back row) and Gallery (a large live preview with a filmstrip). Every view is virtualized, so a folder of 10,000 files scrolls and sorts instantly. Click to select, Shift+click for a range, ⌘ / Ctrl+click to add, drag across empty space for a rectangle, ⌘A for all; arrows move, Shift+arrows extend, typing a name jumps to it. Double-click or Enter opens: folders open in place, images in the lightbox, other files in Quick Look; Space opens Quick Look on any file (PDF, Word, Excel, CSV, PowerPoint, images, video, audio, Markdown, JSON, code and text) and the arrows move through the folder. Back and forward (⌘[ ⌘]), Backspace or ⌘↑ go up, the path bar at the bottom jumps to any parent. Right-click, Shift+F10, a long press or the ⋯ of a row opens the actions: open, Get info (⌘I), rename (F2, Enter saves, Escape cancels), duplicate (⌘D), move to, copy to, copy and paste (⌘C, ⌘V, ⌥⌘V moves), download, copy path, favorites, tags and delete (⌘⌫, with a confirmation). Drag items onto a folder, a crumb or a sidebar row to move them (hold ⌥ to copy, rest on a folder to spring it open), onto a tag to tag them; drop files from the desktop to upload them. Search (⌘F) looks through the whole tree, accents and case ignored, with a 2 of 14 counter and Enter / Shift+Enter between results. The preview panel shows the selection's details. Menus, the search and dialogs become bottom sheets on phones, where rows are 44px or taller and a tap opens.

File System is a Pro React component in the React media components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add file-system, together with Alert Dialog, Audio Player, Breadcrumb, Button, Code Block and 27 more and the npm packages @tanstack/react-virtual and lucide-react.

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

npx wingo-ui@latest add file-system

File System is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans or unlock it free with an account

Usage

Import FileSystem from @/components/ui/file-system.

import { FileSystem, type FileSystemNode } from "@/components/ui/file-system"

const items: FileSystemNode[] = [
  {
    id: "documents",
    name: "Documents",
    kind: "folder",
    children: [
      { id: "report", name: "Q3 sales report.xlsx", kind: "file", size: 145926, url: "/files/q3-sales-report.xlsx" },
      { id: "agreement", name: "Service agreement.pdf", kind: "file", size: 7905, url: "/files/service-agreement.pdf" },
    ],
  },
  { id: "readme", name: "README.md", kind: "file", url: "/files/readme.md" },
]

export function Drive() {
  return (
    <FileSystem
      items={items}
      height="80dvh"
      onSelectionChange={(ids) => console.log(ids)}
      onRename={async (node, name) => {
        await fetch(`/api/files/${node.id}`, { method: "PATCH", body: JSON.stringify({ name }) })
      }}
    />
  )
}

Props

  • items
    FileSystemNode[]

    The tree, nested (children) or flat (parentId), or both. A node is { id, name, kind: "file" | "folder", size?, modified?, created?, mime?, url?, thumbnail?, tags?, locked?, info?, hasChildren? }. Files with a url open in the viewers; the rest show their details.

  • loadChildren
    (folder: FileSystemNode | null) => Promise<FileSystemNode[]>

    Fetches the contents of a folder with hasChildren the first time it is shown (null: the root, when items is empty). Skeleton rows while it runs, a Try again state when it rejects.

  • resolveUrl
    ((file: FileSystemNode) => string | Promise<string>)

    A url for files that have none yet (a presigned link), asked once per file when it is previewed or downloaded.

  • rootLabeldefault ""
    string

    The name of the root in the sidebar, the title and the path bar. Empty uses labels.root (Home).

  • tags
    FileSystemTag[]

    Colored tags ({ id, label, color }) listed in the sidebar; a tag opens everything that has it. Nodes reference them by id.

  • locations
    FileSystemLocation[]

    Rows under Locations: { id, label, folderId, icon? }. The root by default.

  • defaultViewdefault "icons"
    "icons" | "list" | "columns" | "gallery"

    The view it opens in. ⌘1 to ⌘4 and the toolbar switch it; view and onViewChange control it.

  • iconSizedefault "md"
    "sm" | "md" | "lg"

    Tiles of the Icons view: 88, 104 or 128px wide.

  • foldersFirstdefault true
    boolean

    Folders before files in every sort, like Finder's Keep folders on top.

  • searchScopedefault "all"
    "all" | "folder"

    Where search looks: the whole tree, or the open folder and everything below it.

  • confirmDeletedefault true
    boolean

    Asks before deleting (an alert dialog that waits for onDelete's promise); the action reads Delete… while it does.

  • acceptdefault ""
    string

    File types the upload takes (".pdf,image/*"). Other files are listed as not uploaded.

  • maxFileSizedefault 0
    number

    Bytes per uploaded file; bigger files are listed as not uploaded. 0 means no limit.

  • commandShortcutdefault ""
    string

    Opens the Go to palette (actions, places and every file) from anywhere, in mod+k notation. Empty binds nothing; the palette stays in the ⋯ menu.

  • localedefault "en-US"
    string

    Locale for sizes, dates, relative times and the sort order of names. Unset, it follows the UIProvider locale, then the browser's.

  • loadingdefault false
    boolean

    Skeleton tiles or rows in place of the open folder, for a tree that is still on its way.

  • errordefault ""
    ReactNode

    Replaces the files with an error state and this text; onRetry adds Try again.

  • showToolbardefault true
    boolean

    The toolbar: sidebar, back and forward, the folder name, views, sort, new folder, upload, preview, search and the ⋯ menu.

  • showSidebardefault true
    boolean

    Favorites, locations and tags; a sheet below 560px of width.

  • defaultSidebarOpendefault true
    boolean

    Whether the sidebar starts open where there is room for it.

  • sidebarWidthdefault 200
    number

    Starting width of the sidebar in px (160 to 320); drag its edge or use the arrow keys on it, double-click resets it.

  • showRecentsdefault true
    boolean

    A Recents location: the 100 most recently modified files.

  • defaultPreviewOpendefault true
    boolean

    The preview panel beside the files (from 900px of width): the selection's thumbnail, details, tags, download and delete. ⇧⌘P toggles it.

  • showPathBardefault true
    boolean

    The path bar under the files; every crumb opens that folder and takes dropped items.

  • showStatusBardefault true
    boolean

    Item and selection counts, and what is running (Moving, Uploading).

  • showSearchdefault true
    boolean

    The search field (a button and a sheet when narrow) and ⌘F / Ctrl+F inside the component.

  • heightdefault 640
    number | string

    Height of the frame: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.

  • variantdefault "surface"
    "surface" | "outline" | "plain"

    surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.

  • radiusdefault "md"
    "none" | "sm" | "md" | "lg"

    Corner radius of the frame: 0, 12, 16 or 24px.

  • tonedefault "neutral"
    "neutral" | "brand" | "success" | "warning" | "danger" | "info"

    Selected rows and name tags, the open sidebar row and drop targets. Neutral is black in light mode and white in dark mode.

  • colordefault ""
    string

    Any CSS color; replaces the tone (text on it turns black or white by its lightness).

  • folderColordefault "#4f9ef5"
    string

    The folder glyphs, back plate in this color and front plate lighter. Also --file-system-folder on the frame.

  • folderId
    string | null

    The open folder, controlled (null is the root). Pair it with onFolderChange.

  • defaultFolderIddefault ""
    string | null

    The folder it opens in, uncontrolled; null or empty is the root. The playground offers folders of the sample drive.

  • onFolderChange
    (folderId: string | null) => void

    Called when another folder opens (double-click, the path bar, the sidebar, back and forward).

  • selectedIds
    string[]

    The selection, controlled. Pair it with onSelectionChange.

  • defaultSelectedIdsdefault "[]"
    string[]

    The selection it starts with, uncontrolled.

  • onSelectionChange
    (ids: string[], nodes: FileSystemNode[]) => void

    Called with the ids and the nodes whenever the selection changes.

  • view
    "icons" | "list" | "columns" | "gallery"

    The view, controlled. Pair it with onViewChange.

  • onViewChange
    (view: FileSystemView) => void

    Called when the toolbar, the ⋯ menu, the palette or ⌘1 to ⌘4 switch the view.

  • sort
    FileSystemSort

    The order, controlled: { key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.

  • defaultSortdefault "{ key: "name", direction: "asc" }"
    FileSystemSort

    The order it starts with, uncontrolled.

  • onSortChange
    (sort: FileSystemSort) => void

    Called when a list header or the sort menu changes the order.

  • favorites
    string[]

    Ids under Favorites in the sidebar, controlled. Add to favorites / Remove from favorites change it.

  • defaultFavoritesdefault "[]"
    string[]

    The favorites it starts with, uncontrolled.

  • onFavoritesChange
    (ids: string[]) => void

    Called with the new list of favorite ids.

  • onOpen
    (file: FileSystemNode, event: FileSystemOpenEvent) => void

    Called when a file is opened (double-click, Enter, a tap). event.preventDefault() keeps the lightbox or Quick Look from opening.

  • onPreviewChange
    (file: FileSystemNode | null) => void

    Called when Quick Look opens a file, moves to another one, or closes (null).

  • onCreateFolder
    ((parentId: string | null, name: string) => void | Promise<unknown>)

    Enables New folder (⇧⌘N): a folder appears with its name selected; Enter calls this. A rejected promise keeps the name and shows why.

  • onRename
    ((node: FileSystemNode, name: string) => void | Promise<unknown>)

    Enables rename: F2, the menu, or a slow second click on the name. Enter saves, Escape cancels; a rejected promise keeps the text and shows its message.

  • onMove
    ((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)

    Enables moving: drag onto a folder, a crumb or a sidebar row, Move to…, or ⌥⌘V after ⌘C. A folder never goes into itself.

  • onCopy
    ((nodes: FileSystemNode[], targetId: string | null) => void | Promise<unknown>)

    Enables copying: ⌥ while dragging, Copy to…, Duplicate (⌘D, into the same folder) and ⌘C then ⌘V.

  • onDelete
    ((nodes: FileSystemNode[]) => void | Promise<unknown>)

    Enables Delete (⌘⌫ or Delete), after a confirmation unless confirmDelete is off. Locked nodes are never passed.

  • onUpload
    ((files: File[], targetId: string | null) => void | Promise<unknown>)

    Enables Upload files and dropping files from the desktop onto the view, a folder, a crumb or a sidebar row. accept and maxFileSize filter first.

  • onDownload
    (nodes: FileSystemNode[]) => void

    Replaces the built-in download (a link per file with a url or a resolved url).

  • onTagChange
    ((nodes: FileSystemNode[], tagId: string, add: boolean) => void | Promise<unknown>)

    Enables tagging: the Tags submenu, the tag buttons in Get info, and dropping items onto a sidebar tag.

  • onLoadError
    (error: unknown, folder: FileSystemNode | null) => void

    Called when loadChildren rejects; the folder shows the error with Try again.

  • onRetry
    (() => void | Promise<unknown>)

    Adds Try again to the error state; a returned promise shows it loading.

  • toolbarActions
    ReactNode

    Your own buttons at the end of the toolbar, before the ⋯ menu: share, request files, sync.

  • now
    Date | number

    Relative times (5 minutes ago) are measured from it. Unset, the clock is read after hydration; demos pin it.

  • ref
    Ref<FileSystemHandle> (a useRef object or an (handle) => void callback)

    open(id or path), goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().

  • labels
    Partial<FileSystemLabels>

    Every string, English by default (DEFAULT_FILE_SYSTEM_LABELS): toolbar, sidebar, menus, states, dialogs and announcements, including items(count, formatted), results(active, total), deleteTitle(count, name), busy and kinds.

  • classNames
    Partial<Record<"toolbar" | "sidebar" | "sidebarItem" | "content" | "item" | "name" | "preview" | "pathBar" | "statusBar" | "quickLook" | "state", string>>

    Extra classes for the toolbar, the sidebar and its rows, the content, every tile or row and its name, the preview panel, the path bar, the status bar, Quick Look and the empty, loading and error states.

  • className
    string

    Extra classes for the frame, merged last. Other div props are forwarded to it.

Parts

  • FileSystemNode

    type

    A file or folder: id, name, kind, parentId or children, hasChildren (lazy), size, modified, created, mime, url, thumbnail, tags (tag ids), locked and info (extra rows for the details, like Owner).

  • FileSystemTag

    type

    A sidebar tag: { id, label, color }.

  • FileSystemLocation

    type

    A row under Locations: { id, label, folderId (null is the root), icon? }.

  • FileSystemHandle

    type

    What the ref gets: open(target) with an id or a path of names ("Documents/Q3 2026/Sales"), which returns false when nothing matches; goBack(), goForward(), goUp(), select(ids), getSelection(), getCurrentFolder(), refresh(), openPreview(id?), closePreview() and getViewportElement().

  • FileSystemSort

    type

    { key: "name" | "kind" | "size" | "modified" | "created", direction: "asc" | "desc" }.

  • FileSystemOpenEvent

    type

    What onOpen receives as its second argument: preventDefault() and defaultPrevented.

  • FileSystemLabels

    type

    The shape of labels: every string the component renders.

  • DEFAULT_FILE_SYSTEM_LABELS

    constant

    The English labels. Spread it to translate a few strings.

  • DEFAULT_FILE_SYSTEM_SORT

    constant

    The default order: { key: "name", direction: "asc" }.

Examples

Selection outside the component

onSelectionChange hands over the selected nodes, onOpen the file someone double-clicked; Shift and ⌘ / Ctrl pick several.

Every view, controlled

view and onViewChange drive Icons, List, Columns and Gallery from outside; ⌘1 to ⌘4 switch them from the keyboard.

Operations that return promises

Rename, new folder, move (drag onto a folder, ⌥ copies), copy, delete and upload wait for the promise; a rejected save keeps the name you typed.

Your own toolbar actions and a command palette

toolbarActions adds Share and Request files; commandShortcut="mod+k" opens Go to, which finds any file in the tree.

On a phone

Locations open as a sheet, rows are two lines and 56px tall, a tap opens, a long press or ⋯ shows the actions, columns go one level at a time.

Lazy folders, errors and an empty folder

loadChildren fetches a folder the first time it opens (skeleton rows meanwhile); Archive fails once and offers Try again.

Romanian locale

locale="ro-RO" formats dates (23 sept. 2026), relative times (acum 3 ore) and sizes; labels stay in English unless you pass labels.

50,000 files

A folder with 10,000 files and a ten-year archive: sorting, search and every view stay instant because only the visible rows render.

Dependencies

@tanstack/react-virtuallucide-reactalert-dialogaudio-playerbreadcrumbbuttoncode-blockcommand-menucontext-menucsv-viewerdialogdocx-viewerdropdown-menuexcel-viewerfile-typesfile-uploadimage-lightboxmarkdownpdf-viewerpopoverpptx-viewerrelative-timesheettext-matchtonestooltiptree-viewui-configuse-clipboarduse-controllable-stateuse-localeuse-media-queryuse-shortcutvideo-player

Files

  • components/ui/file-system.tsx

FAQ

Is the React File System component free?

The preview, props and docs are free; copying the source needs a Pro plan. See plans.

How do I install File System?

Run npx wingo-ui@latest add file-system. It also adds the Wingo UI items it builds on (Alert Dialog, Audio Player, Breadcrumb, Button, Code Block and 27 more) and the npm packages @tanstack/react-virtual and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/file-system.

How does File System behave on phones?

Four views: Icons (a grid of thumbnails), List (Name, Date modified, Size and Kind columns, click a header to sort, the chevron opens a folder in place), Columns (a column per folder level and a preview of the selected file; on phones one level at a time with a back row) and Gallery (a large live preview with a filmstrip).

See also

File managerPDF ViewerExcel ViewerTree ViewFile List

More React media components

Image compareImage GalleryStep PlayerQR CodeCarouselPowerPoint Viewer
All 17 React media components

Articles using this component

  • React File Manager: Folders, Uploads and the Backend API

    Component guides · Nov 6, 2026 · 10 min read

New components by email

New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.

PreviousExcel ViewerNext Image compare
Home

Favorites

Locations

Tags

Documents3 items
Media3 items
Photos9 items
ZIPBrand kit.zip18 KB
MDNorthwind README.md1 KB
  1. Home
1 selected · 5 items