---
title: Files
description: A component that allows you to display a list of files and folders.
icon: files
author:
  name: imskyleen
  url: https://github.com/imskyleen
search:
  keywords: [file list, attachments]
related:
  - /dropzone
  - /attachment
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Base UI', url: 'https://base-ui.com/react/components/accordion' },
    { name: 'Animate UI', url: 'https://animate-ui.com/docs/components/files' },
    { name: 'Motion', url: 'https://motion.dev/' },
    { name: 'Lucide', url: 'https://lucide.dev/' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/files
```

<ComponentPreview name="files-demo" />

## When to use

Use this decision tree to determine when to use the Files component:

```mermaid
graph TD;
    A[❓ Need to display file structure?] --> B{What type of display?};
    B --> C[✅ Hierarchical file tree];
    B --> D[⚠️ Simple file list];
    B --> E[⚠️ File upload interface];

    C --> F[❓ Interactive behavior?];
    D --> G[⚠️ Use basic List instead];
    E --> H[⚠️ Use Dropzone instead];

    F --> I[✅ Expandable folders];
    F --> J[ℹ️ Static display only];

    I --> K[❓ Default state?];
    J --> L[ℹ️ Simple Files structure];

    K --> M["✅ Some folders open (defaultOpen)"];
    K --> N[ℹ️ All folders closed];

    M --> O[❓ Controlled state needed?];
    N --> O;
    L --> O;

    O --> P[✅ Use open/onOpenChange props];
    O --> Q[ℹ️ Uncontrolled component];

    P --> R[❓ Additional features?];
    Q --> R;

    R --> S[✅ Side panel/details view];
    R --> T[✅ Custom highlighting];
    R --> U[ℹ️ Basic file tree];

    S --> V[✅ Use sideComponent prop];
    T --> W[✅ Use activeClassName prop];
    U --> X[ℹ️ Standard Files implementation];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class C,I,M,P,S,T,V,W recommended;
    class D,E,G,H discouraged;
    class A,B,F,K,O,R decision;
    class J,L,N,Q,U,X neutral;
```

## Usage

Files presents nested folder disclosures, not an ARIA tree widget. Tab moves between folder buttons; Enter or Space expands or collapses the focused folder. File leaves are passive display rows. Expanding one folder does not close its siblings.

`Files.open` controls its immediate child folders. A `Folder`'s `open` controls that folder's immediate child folders, using their names as IDs. Use `defaultOpen` for uncontrolled groups. Folder names must be unique within each group.

```tsx
<Files>
  <Folder name="Folder 1">
    <File name="file1.txt" />
    <File name="file2.txt" />
  </Folder>
  <Folder name="Folder 2">
    <File name="file3.txt" />
    <File name="file4.txt" />
  </Folder>
</Files>
```

Use `status="modified"` or `status="untracked"` for Git status. The owner supplies the text tone and indicator: a folder dot or a file's M/U marker. Status is also available as text to assistive technology; folder buttons expose it as their description. A custom `sideComponent` replaces the visual indicator without removing the status description. Keep folder side content non-interactive because the folder row is already a button.

Folders own their disclosure element and content. Customize their displayed children and `sideComponent`, not a replacement `render` host. Disclosure layout changes immediately; folder icons and the moving row-hover highlight retain their animation. Keyboard focus has its own visible ring and does not depend on pointer hover.

## Examples

### Files Advanced

<ComponentPreview name="files-advanced-demo" />

## Props

### Files

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | - | The children of the component. |
| `className?` | `string` | - | The class name of the component. |
| `activeClassName?` | `string` | - | The class name of the highlight. |
| `defaultOpen?` | `string[]` | - | The child folders open by default. |
| `open?` | `string[]` | - | The child folders open. |
| `onOpenChange?` | `function` | - | The callback function when the child folders open change. |
| `sideComponent?` | `React.ReactNode` | - | The component to display on the right side of the component. |

### Folder

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | The name of the folder. |
| `status?` | `'modified' \| 'untracked'` | - | Git status with an owned text tone, visual indicator and accessible description. |
| `children?` | `React.ReactNode` | - | The children of the component. |
| `className?` | `string` | - | The class name of the component. |
| `defaultOpen?` | `string[]` | - | The child folders open by default. |
| `open?` | `string[]` | - | The child folders open. |
| `onOpenChange?` | `function` | - | The callback function when the child folders open change. |

### File

| Prop | Type | Default | Description |
| - | - | - | - |
| `className?` | `string` | - | The class name of the component. |
| `name` | `string` | - | The name of the file. |
| `status?` | `'modified' \| 'untracked'` | - | Git status with an owned text tone, M/U marker and readable status text. |

## Credits

- We use [Animate UI](https://github.com/animate-ui/animate-ui) from [imskyleen](https://github.com/imskyleen) for all the animations.