+
+ );
+}
diff --git a/apps/docs/app/trees/demo-data.ts b/apps/docs/app/trees/demo-data.ts
index 9a49405e7..5447957bd 100644
--- a/apps/docs/app/trees/demo-data.ts
+++ b/apps/docs/app/trees/demo-data.ts
@@ -7,16 +7,25 @@ import type {
export const sampleFileList: string[] = [
'README.md',
'package.json',
+ 'bunfig.toml',
+ 'stylelint.config.js',
+ '.browserslistrc',
+ '.oxlintrc.json',
+ '.github/workflows/ci.yml',
'build/index.mjs',
'build/scripts.js',
'build/assets/images/social/logo.png',
'config/project/app.config.json',
+ 'public/404.html',
+ 'public/favicon.ico',
+ 'scripts/deploy.sh',
'src/components/Button.tsx',
'src/components/Card.tsx',
'src/components/Header.tsx',
'src/components/Sidebar.tsx',
'src/lib/mdx.tsx',
'src/lib/utils.ts',
+ 'src/styles/globals.css',
'src/utils/stream.ts',
'src/utils/worker.ts',
'src/utils/worker/index.ts',
diff --git a/apps/docs/app/trees/docs/CoreTypes/constants.ts b/apps/docs/app/trees/docs/CoreTypes/constants.ts
index 29c2502cd..0f775b3db 100644
--- a/apps/docs/app/trees/docs/CoreTypes/constants.ts
+++ b/apps/docs/app/trees/docs/CoreTypes/constants.ts
@@ -13,7 +13,7 @@ export const FILE_TREE_OPTIONS_TYPE: PreloadFileOptions = {
name: 'FileTreeOptions.ts',
contents: `import type {
FileTreeOptions,
- FileTreeIconConfig,
+ FileTreeIcons,
FileTreeStateConfig,
FileTreeSearchMode,
FileTreeCollision,
@@ -48,8 +48,8 @@ interface FileTreeOptions {
// Optional: Git status entries for file status indicators.
gitStatus?: GitStatusEntry[];
- // Optional: custom SVG sprite sheet and icon remapping.
- icons?: FileTreeIconConfig;
+ // Optional: built-in icon set selection, colors, and custom remapping.
+ icons?: FileTreeIcons;
// Optional: paths that cannot be dragged when drag and drop is enabled.
lockedPaths?: string[];
@@ -168,8 +168,15 @@ export const FILE_TREE_ICON_CONFIG_TYPE: PreloadFileOptions = {
name: 'FileTreeIconConfig.ts',
contents: `import type { FileTreeIconConfig } from '@pierre/trees';
-// FileTreeIconConfig lets you replace built-in icons with custom SVG symbols.
+// FileTreeIconConfig lets you pick a built-in set, enable semantic colors,
+// or inject your own SVG symbols.
interface FileTreeIconConfig {
+ // Optional: use one of the built-in sets, or "none" for custom-only rules.
+ set?: 'minimal' | 'standard' | 'complete' | 'none';
+
+ // Optional: enable built-in per-file-type colors. Default: true.
+ colored?: boolean;
+
// An SVG string with definitions injected into the shadow DOM.
spriteSheet?: string;
@@ -179,12 +186,35 @@ interface FileTreeIconConfig {
| string
| { name: string; width?: number; height?: number; viewBox?: string }
>;
+
+ // Remap file icons by exact basename (e.g. package.json, .gitignore).
+ byFileName?: Record<
+ string,
+ | string
+ | { name: string; width?: number; height?: number; viewBox?: string }
+ >;
+
+ // Remap file icons by extension (e.g. ts, tsx, spec.ts).
+ byFileExtension?: Record<
+ string,
+ | string
+ | { name: string; width?: number; height?: number; viewBox?: string }
+ >;
+
+ // Remap file icons when filename contains a substring (e.g. dockerfile).
+ byFileNameContains?: Record<
+ string,
+ | string
+ | { name: string; width?: number; height?: number; viewBox?: string }
+ >;
}
-// Example: replace the file and chevron icons with custom symbols.
+// Example: use the built-in file-type set with colors enabled, then override one icon.
const options = {
initialFiles: ['src/index.ts', 'src/components/Button.tsx'],
icons: {
+ set: 'standard',
+ colored: true,
spriteSheet: \`
\`,
+ byFileExtension: {
+ ts: 'my-file',
+ },
remap: {
- 'file-tree-icon-file': 'my-file',
'file-tree-icon-chevron': { name: 'my-folder', width: 16, height: 16 },
},
},
diff --git a/apps/docs/app/trees/docs/CoreTypes/content.mdx b/apps/docs/app/trees/docs/CoreTypes/content.mdx
index 252690906..9861a24fd 100644
--- a/apps/docs/app/trees/docs/CoreTypes/content.mdx
+++ b/apps/docs/app/trees/docs/CoreTypes/content.mdx
@@ -46,7 +46,7 @@ folder containing `index.ts`, `utils/helpers.ts`, and a `components` folder with
| `lockedPaths` | Optional list of file/folder paths that cannot be dragged when drag and drop is enabled. |
| `onCollision` | Optional callback for drag collisions. Return `true` to overwrite destination. |
| `gitStatus` | Optional `GitStatusEntry[]` used to show Git-style file status (`added`, `modified`, `deleted`). Folders with changed descendants also receive a change indicator. [Live demo](/preview/trees#path-colors). |
-| `icons` | Optional `FileTreeIconConfig` to provide a custom SVG sprite sheet and remap built-in icon names to your own symbols. [Live demo](/preview/trees#custom-icons). |
+| `icons` | Optional built-in icon set selection or `FileTreeIconConfig` for semantic colors, CSS-themable palettes, and custom sprite overrides. [Live demo](/preview/trees#custom-icons). |
| `sort` | Sort children within each directory. `true` (default) uses the standard sort (folders first, dot-prefixed next, case-insensitive alphabetical). `false` preserves insertion order. `{ comparator: fn }` for custom sorting. |
| `virtualize` | Enable virtualized rendering so only visible items are rendered. Pass `{ threshold: number }` to activate when item count exceeds the threshold, or `false` to disable. Default: `undefined` (off). |
diff --git a/apps/docs/app/trees/docs/Icons/content.mdx b/apps/docs/app/trees/docs/Icons/content.mdx
index 683e77b1e..2f965adc3 100644
--- a/apps/docs/app/trees/docs/Icons/content.mdx
+++ b/apps/docs/app/trees/docs/Icons/content.mdx
@@ -1,16 +1,35 @@
-## Custom Icons
+## Icons
-Use the `icons` option inside `FileTreeOptions` to swap built-in icons with your
-own SVG symbols. Try the live demo at
+Use the `icons` option inside `FileTreeOptions` to choose one of the built-in
+icon sets or inject your own SVG sprite. Try the live demo at
[/preview/trees#custom-icons](/preview/trees#custom-icons).
+- `icons: 'minimal' | 'standard' | 'complete'` — use one of the shipped icon
+ tiers. Each tier is cumulative: `standard` includes everything in `minimal`
+ plus language icons, and `complete` adds brands and tooling on top.
+- `set` — use the object form to combine a built-in set with `colored`,
+ `spriteSheet`, or file-specific overrides.
+- `colored` — semantic per-file-type colors for built-in `standard` and
+ `complete` icons. Defaults to `true`; set `colored: false` to disable it.
+ Override the palette with CSS variables like
+ `--trees-file-icon-color-javascript`.
- `spriteSheet` — an SVG string containing `` definitions. It is
- injected into the shadow DOM alongside the default sprite sheet.
+ injected into the shadow DOM alongside the selected built-in sprite sheet.
- `remap` — a map from a built-in icon name to either a replacement symbol id
(string) or an object with `name`, optional `width`, `height`, and `viewBox`.
+- `byFileName` — remap the file icon for exact basenames (for example
+ `package.json` or `.gitignore`).
+- `byFileNameContains` — remap the file icon when a basename contains a pattern
+ (for example `dockerfile` or `license`).
+- `byFileExtension` — remap the file icon by extension (for example `ts`, `tsx`,
+ `spec.ts`, or `json`).
-You can re-map any of the existing, default icons (listed below) by creating new
-SVG symbols that use the same IDs.
+You can remap any of the existing built-in icon slots (listed below) by creating
+new SVG symbols that use the same IDs.
+
+For file rows, icon resolution order is: `byFileName` → `byFileNameContains` →
+`byFileExtension` (most specific suffix first) → built-in set mapping →
+`remap['file-tree-icon-file']` → fallback file icon.
| Icon ID | Description |
| ------------------------ | ------------------------------------------------------------------- |
diff --git a/apps/docs/app/trees/docs/ReactAPI/constants.ts b/apps/docs/app/trees/docs/ReactAPI/constants.ts
index bc7821653..5715886d0 100644
--- a/apps/docs/app/trees/docs/ReactAPI/constants.ts
+++ b/apps/docs/app/trees/docs/ReactAPI/constants.ts
@@ -83,26 +83,14 @@ export const REACT_API_CUSTOM_ICONS_EXAMPLE: PreloadFileOptions = {
name: 'custom_icons_file_tree.tsx',
contents: `import { FileTree } from '@pierre/trees/react';
-const customSpriteSheet = \`
-
-\`;
-
-export function CustomIconsTree() {
+export function IconSetTree() {
return (
= {
name: 'custom_icons_file_tree.ts',
contents: `import { FileTree } from '@pierre/trees';
-const customSpriteSheet = \`
-
-\`;
-
const fileTree = new FileTree({
initialFiles: [
'src/index.ts',
@@ -147,10 +137,8 @@ const fileTree = new FileTree({
'package.json',
],
icons: {
- spriteSheet: customSpriteSheet,
- remap: {
- 'file-tree-icon-file': 'my-file',
- },
+ set: 'standard',
+ colored: true,
},
});
diff --git a/apps/docs/app/trees/tree-examples/CustomIconsSection.tsx b/apps/docs/app/trees/tree-examples/CustomIconsSection.tsx
index 689be14ba..7da32c4fd 100644
--- a/apps/docs/app/trees/tree-examples/CustomIconsSection.tsx
+++ b/apps/docs/app/trees/tree-examples/CustomIconsSection.tsx
@@ -1,4 +1,4 @@
-import { IconBrush, IconFire } from '@pierre/icons';
+import { IconBrush, IconFileTreeFill, IconFire } from '@pierre/icons';
import { FileTree } from '@pierre/trees/react';
import { preloadFileTree } from '@pierre/trees/ssr';
import type { CSSProperties } from 'react';
@@ -12,61 +12,41 @@ import {
} from './demo-data';
import { TreeExampleSection } from './TreeExampleSection';
-const customSpriteSheet = `
-
-`;
-
const panelStyle = {
...DEFAULT_FILE_TREE_PANEL_STYLE,
'--trees-search-bg-override': 'light-dark(#fff, oklch(14.5% 0 0))',
} as CSSProperties;
+const minimalPrerenderedHTML = preloadFileTree(
+ {
+ ...baseTreeOptions,
+ id: 'built-in-icons-minimal',
+ lockedPaths: ['package.json'],
+ icons: 'minimal',
+ },
+ {
+ initialExpandedItems: ['src', 'src/components'],
+ }
+).shadowHtml;
+
const defaultPrerenderedHTML = preloadFileTree(
{
...baseTreeOptions,
- id: 'custom-icons-default',
+ id: 'built-in-icons-default',
lockedPaths: ['package.json'],
+ icons: 'standard',
},
{
initialExpandedItems: ['src', 'src/components'],
}
).shadowHtml;
-const remappedPrerenderedHTML = preloadFileTree(
+const completePrerenderedHTML = preloadFileTree(
{
...baseTreeOptions,
- id: 'custom-icons-remapped',
+ id: 'built-in-icons-complete',
lockedPaths: ['package.json'],
- icons: {
- spriteSheet: customSpriteSheet,
- remap: {
- 'file-tree-icon-file': {
- name: 'custom-file-icon',
- width: 12,
- height: 12,
- },
- 'file-tree-icon-chevron': {
- name: 'custom-folder-icon',
- width: 12,
- height: 12,
- },
- 'file-tree-icon-lock': {
- name: 'custom-lock-icon',
- width: 12,
- height: 12,
- },
- },
- },
+ icons: 'complete',
},
{
initialExpandedItems: ['src', 'src/components'],
@@ -78,11 +58,14 @@ export function CustomIconsSection() {
- Swap out our default icons by using a custom SVG sprite that remaps
- the built-in icon names to your custom symbols. See the{' '}
+ Choose between the shipped minimal,{' '}
+ standard, and complete icon tiers. Each
+ tier is cumulative. Override the built-in palette with CSS variables
+ like --trees-file-icon-color-javascript, or fall back
+ to a fully custom sprite. See the{' '}
FileTreeIconConfig docs
{' '}
@@ -90,25 +73,24 @@ export function CustomIconsSection() {
}
/>
-
+
}
+ icon={}
description={
- <>
- The default icons used when no icons option is set.
-
+ <>Generic file, folder, and image icons with no file types.
}
>
- Default
+ Minimal
}
- description={
- <>
- Pass a spriteSheet and remap via the{' '}
- icons option.
-
- }
+ description={<>Icons for common languages and file types.}
+ >
+ Standard
+
+
+