File and folder icons

File icons and Interface icons have independent selections in Settings > Themes. An icon theme is a data package with a native wrapper and a VS Code-format icon document.

A small file icon theme

The complete package is in examples/plain-file-icons. It contains theme.jsonc, icons.json and file.svg.

theme.jsonc:

{
  "version": 2,
  "name": "Plain file icons",
  "iconTheme": { "kind": "file", "path": "icons.json" }
}

icons.json:

{
  "iconDefinitions": {
    "document": { "iconPath": "./file.svg" }
  },
  "file": "document",
  "fileExtensions": { "md": "document", "mdx": "document" }
}

file.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#7a8fa6" stroke-width="1.5">
  <path d="M6 3h8l4 4v14H6zM14 3v5h4M9 12h6M9 16h6" />
</svg>

Import the folder, switch to File icons and select Plain file icons. The file association supplies the default file icon; the extension associations demonstrate how to address Markdown files explicitly.

Paths in the icon document are relative to that document. Keep all referenced images and fonts inside the package. A wrapper with iconTheme cannot also contain color surfaces or resources.

File associations

The application handles filename and parent-folder associations, multipart extensions, language IDs, root folders, expanded folders and light/high-contrast variants. Matching follows the supported VS Code specificity rules, with declaration order breaking equal-specificity ties.

Supported association fields include:

file, folder, folderExpanded, rootFolder, rootFolderExpanded,
fileNames, fileExtensions, languageIds,
folderNames, folderNamesExpanded,
rootFolderNames, rootFolderNamesExpanded

light and highContrast supply variant associations. jsonc falls back to the json language association when no explicit JSONC association exists. hidesExplorerArrows hides the visual arrow while keeping the expansion control accessible.

File icons are used in Explorer and other resource views, including tabs, project folders, search results and file prompts. Unmatched resources retain built-in fallback icons.

The application does not install VS Code language extensions. Their separately registered language-mode icons are unavailable, even though showLanguageModeIcons metadata is retained for export.

Interface icons

Use iconTheme.kind: "product" for interface icons. Product themes use glyph fonts and fontCharacter definitions. The practical starting point is Interface icons > Create icon theme or Duplicate on the built-in icon set. The copy includes a working font and definitions you can edit.

Supported semantic IDs include terminal, search, settings-gear, close, add, save and git-branch. The complete mapping and aliases are in product-icons.ts.

Missing definitions fall back to built-in Lucide icons. Product themes affect mapped application controls. They do not replace icons inside third-party webpages, arbitrary plugin components or the separate file icon theme.

Edit and export

Use Open icon definitions to open the installed package folder. Edit the icon document and its assets, then use Refresh if needed. Selected packages are watched for changes; a resource failure keeps the last working appearance.

Export to VS Code includes the selected document and all referenced image/font resources in a data-only VSIX. Unused definitions and supported unknown metadata are retained. Built-in file and interface icons can also be exported with their bundled license.

Limits

Icon documents can be up to 2 MiB. Resource files can be up to 20 MiB, with 64 MiB per package. A theme can declare up to 32 fonts, each with 1 to 8 sources. Supported font formats are WOFF, WOFF2, TTF and OTF. Missing files, paths outside the package and invalid font definitions prevent the theme from being applied.

Complete association example

The Workspace file icons package includes a wrapper, seven SVGs and this icons.json. Import the whole folder. The definition IDs are your names; association values must refer to an existing definition.

{
  "iconDefinitions": {
    "document": {
      "iconPath": "./file.svg"
    },
    "folder": {
      "iconPath": "./folder.svg"
    },
    "open": {
      "iconPath": "./folder-open.svg"
    },
    "code": {
      "iconPath": "./code.svg"
    },
    "declaration": {
      "iconPath": "./declaration.svg"
    },
    "readme": {
      "iconPath": "./readme.svg"
    },
    "light": {
      "iconPath": "./light-file.svg"
    }
  },
  "file": "document",
  "folder": "folder",
  "folderExpanded": "open",
  "rootFolder": "folder",
  "rootFolderExpanded": "open",
  "fileExtensions": {
    "ts": "code",
    "d.ts": "declaration",
    "src/ts": "code"
  },
  "fileNames": {
    "readme.md": "readme"
  },
  "languageIds": {
    "json": "code"
  },
  "folderNames": {
    "src": "folder"
  },
  "folderNamesExpanded": {
    "src": "open"
  },
  "light": {
    "file": "light"
  }
}

Resource	Selected definition
`notes.txt` in dark mode	`document`
`notes.txt` in light mode	`light`
`lib/main.ts`	`code`
`lib/types.d.ts`	`declaration`
`src/main.ts`	`code`, through the parent-qualified association
`README.md`	`readme`, including in light mode
`settings.jsonc` in dark mode	`code`, through the JSON language fallback
Collapsed / expanded `src`	`folder` / `open`

Matching rules in detail

Keys are matched case-insensitively. Extension keys omit the leading dot: ts or d.ts. src/ts restricts that extension to the immediate parent named src; it is not a glob. fileNames accepts exact basenames and immediate-parent/basename forms. folderNames and folderNamesExpanded accept names with an optional immediate parent; root-folder maps match the root name.

More specific associations normally win: default file, language, extension, multipart extension, then exact filename. An immediate parent increases specificity. Expanded-folder associations can outrank a named collapsed-folder association, so define folderNamesExpanded as well when customizing an open folder. Root folders use root associations, with ordinary folder defaults as fallbacks.

Light/high-contrast associations participate in the same specificity ranking; they do not blindly replace all base associations. Equal-ranked rules are ordered by the definition order derived from association traversal, not simply the last textual JSON field. Matching declarations combine per property, which matters for font size and color. For predictable packages, avoid competing rules of equal specificity.

highContrast is selected when the active imported color theme has vscode.type equal to hcDark or hcLight. It takes the place of the light association layer. There is no separate high-contrast switch for icon themes.

Images and glyphs

A file icon definition can use iconPath for an image or fontCharacter with a font from fonts. fontId selects a declared font, otherwise the first font is used. See font declarations for the structure and bounds. Font definitions can inherit attributes from other matched associations; avoid mixing image and glyph definitions for the same resource unless you have checked the result.

For file glyphs, fontColor supports rendered hexadecimal colors. fontSize overrides the font’s size; supported rendered sizes are percentages or whole pixel values, with a default of 150%. Product icons have different color and sizing behavior.

usesCurrentColor: true makes image icons use a current-color mask. Use this for monochrome silhouettes; leave it unset for colored images. hidesExplorerArrows affects the arrow decoration, not whether folders can be expanded. All boolean flags require actual JSON booleans.

For control symbols and their complete ID list, continue to Interface icons.

Source: icon types and matching, native icon validation.