[icon themes] File icon sets contribution point documentation

[aeschli]

Here's the latest state of the work for #10600 for the August release, planned for September 12.

Check out the latest insiders build, produced every night (US timezone), to try out the latest and write your extensions... :-)

Summary

We introduce the new concept of 'file icon themes'. File icon themes can be contributed by extensions and selected by users as their favourite set of file icons. File icons are shown in the file explorer, but in the future also at other places like in tab folders.

User Settings

To enable and to pick a icon theme, the user can either:

• use the global menu File > Preferences > File Icon Theme
• use the 'File Icon Theme' command (F1)

By default, no file icon set is configured, therefore the file explorer shows no icons. Once an icon theme is selected, it will be persisted and shown again when restarting VSCode.

Out of the box, VS code ships with two icon themes

• 'Minimal' consisting only of file and folder icons. The 'vs-minimal' fileTheme is defined here.
• 'Seti' based on the Seti UI theme. The 'vs-seti' fileTheme is defined here.

We hope the community will contribute many more themes (including the popular vs-icons extension) :-)

APIs for Extensions

For an extension to contribute a new file icon theme, the following contribution point needs to be implemented. Thats in package.json, as usual.

    "contributes": {
        "iconThemes": [
            {
                "id": "martin",
                "label": "Martin",
                "path": "./fileicons/martin-icon-theme.json"
            }
        ]
    }

The id is used internally. In the future it might be used in the settings, so keep it not only unique but also readable. label is shown in the icon theme configuration dialog.
The path points to a file in the extension that defines the icon set. If your icon set name follows the *icon-theme.json name scheme, you will get completion support and hovers in VS Code.

Icon Set File

The icon set file is a JSON file consisting file icon associations and icon definitions.

A icon association maps a file type ('file', 'folder', 'json-file'...) to an icon definition. Icon definitions define where the icon is located: That can be an image file or also glyph in a font.

Icon definitions

The iconDefinitions section contains all definitions. Each definition has an id, which will be used to reference the definition. A definition can be referenced also by more than one file association.

    "iconDefinitions": {
        "_folder_dark": {
            "iconPath": "./images/Folder_16x_inverse.svg"
        }
    }

This icon definition contains definition with the identifier _folder_dark.

The following properties are supported:

• iconPath: When using a svg/png: the path to the image.
• fontCharacter: When using a glyph font: The character in the font to use
• fontColor: When using a glyph font: The color to use for the glyph
• fontSize: When using a font: The font size. By default the size specified in the font specification is used. Should be a relative size (e.g. 150%) to the parent font size.
• fontId: When using a font: The id of the font. If not specified, the first font specified in font specification section will be picked.

Possible additions under consideration are:

• image path to high resolution image

File association

Icons can be associated to folders, folder names, files, file extensions, file names and language ids.

Additionally each of these associations can be refined for 'light' and 'highContrast' color themes.

Each file association points to a icon definition.

    "file": "_file_dark",
    "folder": "_folder_dark",
    "folderExpanded": "_folder_open_dark",
    "folderNames": {
        ".vscode": "_vscode_folder",
    },
    "fileExtensions": {
        "ini": "_ini_file",
    },
    "fileNames": {
        "win.ini": "_win_ini_file",
    },
    "languageIds": {
        "ini": "_ini_file"
    },
    "light": {
        "folderExpanded": "_folder_open_light",
        "folder": "_folder_light",
        "file": "_file_light",
        "fileExtensions": {
            "ini": "_ini_file_light",
        }
    },
    "highContrast": {
    }
}

• file is the default file icon, shown for all files that don't match any extension, filename or language id. Currently all properties defined by the definition of the file icon will be inherited (only relevant for font glyphs, useful for the fontSize)
• folder is the folder icon for collapsed folders, and if folderExpanded is not set, also for expanded folders. Icons for specific folder names can be associated using the folderNames property .
  The folder icon is optional. If not set, no icon will be shown for folder.
• folderExpanded is the folder icon for expanded folders. The expanded folder icon is optional. If not set, the icon defined for folder will be shown.
• folderNames associates folder names to icons. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive.
• folderNamesExpanded associates folder names to icons for expanded folder. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive.
• languageIds associates languages to icons. The key in the set is the language id as defined in the language contribution point. The language of a file is evaluated based on the file extensions and file names as defined in the language contribution. Note that the 'first line match' of the language contribution is not considered.
• fileExtensions associates file extensions to icons. The key in the set is the file extension name. The extension name is a file name segment after a dot (not including the dot). File names with multiple dots such as lib.d.ts can match multiple extensions; 'd.ts' and 'ts'. Extensions are compared case insensitive.
• fileNames associates file names to icons. The key in the set is the full file name, not including any path segments. Patterns or wildcards are not supported. File name matching is case insensitive. A 'fileName' match is the strongest match, and the icon associated to the file name will be preferred over a icon of a matching fileExtension and also of a matching language Id.

A file extension match is preferred over a language match, but is weaker than a file name match.

The light and the highContrast section have the same file association properties as just listed. They allow to override icons for the corresponding themes.

Font definitions

The 'fonts' section lets you declare any number of glyph fonts that you want to use. You can later reference these font in the icon definitions. The font declared first will be used as by default if an icon definition does not specify a font id.

    "fonts": [
        {
            "id": "martin-font",
            "src": [
                {
                    "path": "./martin.woff",
                    "format": "woff"
                }
            ],
            "weight": "normal",
            "style": "normal",
            "size": "150%"
        }
    ],
    "iconDefinitions": {
        "_file": {
            "fontCharacter": "\\E002",
            "fontColor": "#5f8b3b",
            "fontId": "martin-font"
        }
    }

[robertohuertasm]

@aeschli Great document! Really, really useful! 😀

Just a question: Is there any plan of supporting complex extensions like .blade.php or even .d.ts? This was a use case that some users demanded and I think it would be very cool to implement it. vscode-icons does currently implement it already so it would be nice if users won't lose any functionality during the migration of the extension.

[bpasero]

+1 for supporting extensions like d.ts however I am not sure how to best support this via CSS classes. @aeschli should I just add another class for the full extension (anything after the first dot of the file name)?

[aeschli]

+1 for supporting two-part extensions.
@bpasero We could add another ext-file-icon class the node. And maybe use the full filename in the name extension?
E.g. for lib.d.ts we would end up with
lib\.d\.ts-name-file-icon d\.ts-ext-file-icon ts-ext-file-icon.

[robertohuertasm]

Sorry to bother you again. Are folder icons planned in any way? It would be also nice to be able to customize the look of some special folders: .git, .meteor, node_modules, typings...

[aeschli]

We added support for folder name associations as well as we support now complex extensions (any number of dots).
Note that there has been some renames in the iconDefinitions in regard to the properties for font glyphs.
Also note that when you name your icon-theme file with the ending icon-theme.json the JSON language mode will give you tooling support (hovers, validation and intellisense)

[robertohuertasm]

That's really cool! Will folder name association support open/close states too? That would be awesome!

[aeschli]

What's still on the todo list:

• changing from a user setting to a Preferences > File Icon Theme action. That's mostly for UX consistency with the color themes. But having both Theme and File Icons in the settings is something we might still do in the future.

[be5invis]

love it :)

[be5invis]

How about the custom styleing? (i.e. full-workbench themeing)

[aeschli]

• I renamed the contribution point from 'fileIcons' to 'iconThemes'. For now only file icons will be part of the theme, but we want to keep the name general enough for future developments.
• I removed the files.iconTheme and explorer.showFileIcons user settings. To select a theme, now use the 'File > Preferences > Icon Theme' menu item. The setting is persisted per VSCode application. We are open to add this to a user setting at a later moment again, but for now we rather be consistent with the color theme configuration experience.
  By default, no icon theme is selected, thus no icons are shown in the explorer.
• I added folder name associations for expanded folders. As always that's optional. If not set, the regular folder icon will be shown.

[skolmer]

It would be nice if you could do something like this:

"folderNames": {
    ".vscode": {
        "tasks.json": "_vscode_tasks_json_file",
        "launch.json": "_vscode_launch_json_file"
    }
}

This could be useful if you want to individually style launch.json, tasks.json e.g. in .vscode folder

[robertohuertasm]

Hi @aeschli, I'm starting to integrate the extension but I have a couple of questions:

1. How does the folderNamesExpanded work? I'm setting my icon definition, then I create my folderNamesExpanded with a reference to the name of the folder and the icon definition. Finally, never gets to work. It's always showing the not expanded version.

"folderNames":{
    "typings": "_f_typings"
  },
"folderNamesExpanded":{
    "typings": "_f_typings_open"
},

1. Can users modify the default associations? I mean, if I want to associate .jsx to js icon instead of jsx icon could I do that?

Thanks for your support!

[aeschli]

@robertohuertasm I pushed a fix for the folderNamesExpanded issue. Thanks for reporting!

You can't customize the language associations. You could give all js-language files the jsx icon, but I guess that's not what you want. Currently the language associations are stronger than the file extension associations. Do you think this should be reversed?

[robertohuertasm]

@aeschli I think it would be better to prioritize extensions over language. I'm thinking about the d.ts case. .ts and .d.ts extension are both associated to typescript but I want to provide a custom icon for both and I don't want to create multiple filename associations as this would be cumbersome. Then I would need to associate some icon to the .d.ts extension which will invalidate using language associations at all as now my .ts files should be using extension associations instead of language association.

The order would be:

1. file name
2. file extension
3. file language

On the other hand, vscode-icons provides the ability to use regular expressions by the user in order to modify the proposed icon associations. You can take a look at this case #181. It can be superuseful in order to cover extended use cases like this without the need to alter the extension and by letting the user decide what they want to do.

Besides that, the fact that the user can decide what kind of extensions are associated to a file I think is a must. We can propose an initial state of things, and certainly they will be able to create PR or raise issues but if they already have the ability to change what's been already established by the creators of the extension I think that's cool and some of the current users are taking profit of it.

I know this may not be an easy task by now but I would like you to consider its implementation. Otherwise, current users will be losing a big part of the current functionality provided by vscode-icons.

As usual, thanks for your support! 😀

[aeschli]

Makes sense, I'll change the order as you suggest!

[wclr]

@aeschli just FYI there is a request about icons vscode-icons/vscode-icons#235

[gsaadeh]

That is great news! Love the new feature!

[zozzz]

Another idea. I would like to define the folder icon based on its contents like this:

src
  |_ package_name <- display package icon, because folder contains __init__.py
       |_ __init__.py

example:

{
    "folderNames": {
        "*>__init__.py": "_package_icon"
    }
}

• > match files / folders which is a direct child of folder
• >> same as above, just any level
• * any folder name

[aeschli]

@zozzz and @skolmer Thanks for the suggestions but hierarchy depended icons are currently not planned, sorry!

[aeschli]

Last changes:

• the Standard icon theme got renamed to 'Minimal'
• we also added a Visual Studio Code Seti theme to the built-in themes.

I'm closing this issue for now. The documentation has now moved to https://code.visualstudio.com/Docs (visible once the release is out) and will be maintained there.
Thanks for all the comments!

[APerricone]

Hi, I created a language extension, how can I add an icon only for my supported language?

[atian25]

hi, is there any api to got iconDefinitions ?

I'm writing a Custom tree view and want to use it as my TreeItem iconPath.

[aeschli]

@atian25 No there is no such API. You need to file an issue against the tree API to let you enable file icons. Having a file icons URI isn't working as can come from a font and the logic to evaluate the correct icon is non-trivial.