Folder

A file tree for hierarchical file structures. Aligned with React @ant-design/x Folder (2.4+, including the 2.8 context menu).

中文：Folder 文件夹

When to use

• Show file / folder hierarchies
• Need selection, expand/collapse, preview, and a context menu
• Need to drag-resize the tree and preview panes

Examples

Basic

Project Files

src

App.vue

main.ts

package.json

App.vue

<script setup lang="ts">
const msg = 'Hello Folder';
</script>

<template>
  <div>{{ msg }}</div>
</template>

Basic

File tree with inline content preview. Drag the divider between the tree and preview to resize.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderBasicV2' });

import { Folder, type FolderProps } from 'ant-design-x-vue';

const treeData: FolderProps['treeData'] = [
  {
    title: 'src',
    path: 'src',
    children: [
      {
        title: 'App.vue',
        path: 'App.vue',
        content: `<script setup lang="ts">\nconst msg = 'Hello Folder';\n<\/script>\n\n<template>\n  <div>{{ msg }}</div>\n</template>`,
      },
      {
        title: 'main.ts',
        path: 'main.ts',
        content: "import { createApp } from 'vue';\nimport App from './App.vue';\ncreateApp(App).mount('#app');",
      },
    ],
  },
  {
    title: 'package.json',
    path: 'package.json',
    content: '{\n  "name": "demo",\n  "version": "1.0.0"\n}',
  },
];

defineRender(() => (
  <div style={{ height: 420 }}>
    <Folder
      treeData={treeData}
      directoryTitle="Project Files"
      defaultSelectedFile={['src', 'App.vue']}
    />
  </div>
));
</script>

Hide source

Custom file service

remote

a.ts

b.ts

Custom file service

Load file content dynamically with fileContentService.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderCustomServiceV2' });

import { Folder, type FolderProps } from 'ant-design-x-vue';

const treeData: FolderProps['treeData'] = [
  {
    title: 'remote',
    path: 'remote',
    children: [
      { title: 'a.ts', path: 'a.ts' },
      { title: 'b.ts', path: 'b.ts' },
    ],
  },
];

const fileContentService: FolderProps['fileContentService'] = {
  async loadFileContent(filePath) {
    await new Promise((r) => setTimeout(r, 300));
    return `// loaded from service: ${filePath}\nexport default {};`;
  },
};

defineRender(() => (
  <div style={{ height: 360 }}>
    <Folder
      treeData={treeData}
      fileContentService={fileContentService}
      defaultSelectedFile={['remote', 'a.ts']}
    />
  </div>
));
</script>

Hide source

Controlled file selection

docs

guide.md

api.md

guide.md

# Guide
Controlled selection.

Controlled file selection

Control selection with selectedFile / onSelectedFileChange.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderFileControlledV2' });

import { Button, Space } from 'ant-design-vue';
import { Folder, type FolderProps } from 'ant-design-x-vue';
import { ref } from 'vue';

const treeData: FolderProps['treeData'] = [
  {
    title: 'docs',
    path: 'docs',
    children: [
      { title: 'guide.md', path: 'guide.md', content: '# Guide\nControlled selection.' },
      { title: 'api.md', path: 'api.md', content: '# API\nFolderProps...' },
    ],
  },
];

const selectedFile = ref<string[]>(['docs', 'guide.md']);

defineRender(() => (
  <div style={{ height: 360 }}>
    <Space style={{ marginBottom: 12 }}>
      <Button onClick={() => (selectedFile.value = ['docs', 'guide.md'])}>Select guide.md</Button>
      <Button onClick={() => (selectedFile.value = ['docs', 'api.md'])}>Select api.md</Button>
    </Space>
    <Folder
      treeData={treeData}
      selectedFile={selectedFile.value}
      onSelectedFileChange={(file) => {
        selectedFile.value = file.path;
      }}
    />
  </div>
));
</script>

Hide source

Custom icons

📁pages

index.html

readme.md

readme.md

# Pages

Custom icons

Customize directory and extension icons with directoryIcons. Set false to hide icons.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderCustomIconsV2' });

import { FileMarkdownOutlined, Html5Outlined } from '@ant-design/icons-vue';
import { Folder, type FolderProps } from 'ant-design-x-vue';

const treeData: FolderProps['treeData'] = [
  {
    title: 'pages',
    path: 'pages',
    children: [
      { title: 'index.html', path: 'index.html', content: '<!doctype html>' },
      { title: 'readme.md', path: 'readme.md', content: '# Pages' },
    ],
  },
];

defineRender(() => (
  <div style={{ height: 320 }}>
    <Folder
      treeData={treeData}
      defaultSelectedFile={['pages', 'readme.md']}
      directoryIcons={{
        directory: () => <span>📁</span>,
        md: () => <FileMarkdownOutlined />,
        html: () => <Html5Outlined />,
      }}
    />
  </div>
));
</script>

Hide source

Context menu

Right-click any file or folder

my-project

src

App.vue

README.md

App.vue

<template><div>Hello</div></template>

Context menu

Global contextMenu with per-node overrides (including false to disable). Use ref methods updateNode / deleteNode / addNode for immutable updates.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderContextMenuV2' });

import {
  CopyOutlined,
  DeleteOutlined,
  EditOutlined,
  FileAddOutlined,
} from '@ant-design/icons-vue';
import { message, Space, Tag } from 'ant-design-vue';
import {
  Folder,
  type FolderProps,
  type FolderRef,
  type FolderTreeData,
} from 'ant-design-x-vue';
import { ref } from 'vue';

const initialTreeData: FolderProps['treeData'] = [
  {
    title: 'my-project',
    path: 'my-project',
    children: [
      {
        title: 'src',
        path: 'src',
        children: [
          {
            title: 'App.vue',
            path: 'App.vue',
            content: '<template><div>Hello</div></template>',
          },
        ],
      },
      {
        title: 'README.md',
        path: 'README.md',
        content: '# My Project',
        contextMenu: [
          { key: 'edit', label: 'Edit README', icon: <EditOutlined /> },
          { key: 'copy', label: 'Copy Path', icon: <CopyOutlined /> },
        ],
      },
    ],
  },
];

const folderRef = ref<FolderRef>();
const data = ref<FolderTreeData[]>(initialTreeData);
const lastAction = ref('');
let counter = 1;

const parseKey = (key: string) => key.split('/').filter(Boolean);

const baseMenu: FolderProps['contextMenu'] = (node) => {
  const isFolder = !!node.children && node.children.length > 0;
  if (isFolder) {
    return [
      { key: 'newFile', label: 'New File', icon: <FileAddOutlined /> },
      { key: 'copyPath', label: 'Copy Path', icon: <CopyOutlined /> },
      { type: 'divider' },
      { key: 'delete', label: 'Delete', icon: <DeleteOutlined />, danger: true },
    ];
  }
  return [
    { key: 'copyPath', label: 'Copy Path', icon: <CopyOutlined /> },
    { key: 'rename', label: 'Rename', icon: <EditOutlined /> },
    { type: 'divider' },
    { key: 'delete', label: 'Delete', icon: <DeleteOutlined />, danger: true },
  ];
};

const handleMenuAction = (actionKey: string, fullPathKey: string) => {
  const pathSegments = parseKey(fullPathKey);
  const api = folderRef.value;
  switch (actionKey) {
    case 'rename': {
      const newName = `renamed_${counter++}`;
      data.value = api?.updateNode(pathSegments, { title: newName, path: newName }) ?? data.value;
      message.success(`Renamed to ${newName}`);
      lastAction.value = `Rename: ${fullPathKey} → ${newName}`;
      break;
    }
    case 'delete': {
      data.value = api?.deleteNode(pathSegments) ?? data.value;
      message.success(`Deleted ${fullPathKey}`);
      lastAction.value = `Delete: ${fullPathKey}`;
      break;
    }
    case 'newFile': {
      const fileName = `new_file_${counter++}.ts`;
      data.value =
        api?.addNode(pathSegments, {
          title: fileName,
          path: fileName,
          content: `// ${fileName}`,
        }) ?? data.value;
      message.success(`Created ${fileName}`);
      lastAction.value = `New File: ${fileName}`;
      break;
    }
    case 'copyPath':
    case 'copy':
      navigator.clipboard?.writeText(fullPathKey);
      message.success(`Copied: ${fullPathKey}`);
      lastAction.value = `Copy Path: ${fullPathKey}`;
      break;
    case 'edit':
      message.info(`Edit: ${fullPathKey}`);
      lastAction.value = `Edit: ${fullPathKey}`;
      break;
    default:
      break;
  }
};

const contextMenuWithHandler: FolderProps['contextMenu'] = (node, key) => {
  const items = typeof baseMenu === 'function' ? baseMenu(node, key) : baseMenu;
  if (!items) return items;
  return items.map((item) => {
    if (item && 'key' in item) {
      return {
        ...item,
        onClick: () => handleMenuAction(String(item.key), key),
      };
    }
    return item;
  });
};

defineRender(() => (
  <div style={{ height: 420 }}>
    <Space style={{ marginBottom: 12, display: 'flex', flexWrap: 'wrap' }}>
      <Tag color="blue">Right-click any file or folder</Tag>
      {lastAction.value ? <Tag color="green">{lastAction.value}</Tag> : null}
    </Space>
    <Folder
      ref={folderRef as any}
      treeData={data.value}
      defaultSelectedFile={['my-project', 'src', 'App.vue']}
      contextMenu={contextMenuWithHandler}
      onRightClick={({ node }) => {
        lastAction.value = `Right-clicked: ${String(node?.title ?? node?.key)}`;
      }}
    />
  </div>
));
</script>

Hide source

Custom preview

notes.txt

notes.txt

custom preview · lang=txt

line1
line2
line3

Custom preview

Customize the preview pane with previewRender.

<script setup lang="tsx">
defineOptions({ name: 'AXFolderPreviewRenderV2' });

import { Folder, type FolderProps } from 'ant-design-x-vue';

const treeData: FolderProps['treeData'] = [
  {
    title: 'notes.txt',
    path: 'notes.txt',
    content: 'line1\nline2\nline3',
  },
];

defineRender(() => (
  <div style={{ height: 280 }}>
    <Folder
      treeData={treeData}
      defaultSelectedFile={['notes.txt']}
      previewRender={(file, { originNode }) => (
        <div>
          <div style={{ marginBottom: 8, color: '#1677ff' }}>
            custom preview · lang={file.language}
          </div>
          {originNode}
        </div>
      )}
    />
  </div>
));
</script>

Hide source

API

FolderProps

Prop	Description	Type	Default	Version
treeData	Tree data	FolderTreeData[]	[]	-
selectable	Enable selection	boolean	true	-
selectedFile	Selected file path (controlled)	string[]	-	-
defaultSelectedFile	Default selected file path	string[]	[]	-
onSelectedFileChange	Selection change	(file: { path: string[]; title?: FolderTreeData['title']; content?: string }) => void	-	-
directoryTreeWith	Initial directory tree width (drag the divider to resize)	number | string	278	-
emptyRender	Empty state; false hides it	false | VNode | string | (() => VNode | string | null)	-	-
previewRender	Custom preview	VNode | string | ((file, info) => VNode | string | null)	-	-
expandedPaths	Expanded paths (controlled)	string[]	-	-
defaultExpandedPaths	Default expanded paths	string[]	-	-
defaultExpandAll	Expand all by default	boolean	true	-
onExpandedPathsChange	Expand/collapse change	(paths: string[]) => void	-	-
fileContentService	File content loader	FileContentService	-	-
onFileClick	File click	(filePath: string, content?: string) => void	-	-
onFolderClick	Folder click	(folderPath: string) => void	-	-
directoryTitle	Tree title; false hides it	false | VNode | string | (() => VNode | string | null)	-	-
previewTitle	Preview title	false | VNode | string | (({ title, path, content }) => VNode | string | null)	-	-
directoryIcons	Custom icons; false hides them	false | Record<'directory' | string, VNode | string | (() => ...)>	-	-
contextMenu	Global context menu, overridable per node	MenuProps['items'] | ((node, key) => MenuProps['items'])	-	-
onRightClick	Right-click callback	(info: { event, node }) => void	-	-
classNames	Semantic class names	Record<SemanticType, string>	-	-
styles	Semantic styles	Record<SemanticType, CSSProperties>	-	-

SemanticType: root | directoryTree | directoryTitle | filePreview | previewTitle | previewRender

FolderTreeData

Prop	Description	Type	Default
title	Display name	string | VNode	-
path	Path segment	string	-
content	Optional file content	string	-
children	Children	FolderTreeData[]	-
contextMenu	Node menu; false disables it	MenuProps['items'] | false | ((key) => ...)	-

FileContentService

interface FileContentService {
  loadFileContent(filePath: string): Promise<string>;
}

Ref methods

const folderRef = ref<FolderRef>();

folderRef.value?.getNode(['src', 'App.tsx']);
folderRef.value?.updateNode(['src', 'App.tsx'], { title: 'Main.tsx', path: 'Main.tsx' });
folderRef.value?.deleteNode(['src', 'unused.ts']);
folderRef.value?.addNode(['src'], { title: 'new.ts', path: 'new.ts', content: '' });

Method	Description	Type
getNode	Get a node by path	(path: string[]) => FolderTreeData | undefined
updateNode	Immutable update; returns new treeData	(path, data) => FolderTreeData[]
deleteNode	Immutable delete; returns new treeData	(path) => FolderTreeData[]
addNode	Immutable add; returns new treeData	(parentPath, node) => FolderTreeData[]

Semantic structure

:::semantic

folder

:::