VimDevIcons - Add Icons to Your Plugins

VimDevIcons adds filetype glyphs (icons) to other plugins such as NERDTree, vim-airline, CtrlP, powerline, Denite, unite, lightline.vim, vim-startify, vimfiler, and flagship.

Features

VimDevIcons integrates with these plugins and more:

NERDTree | vim-airline | CtrlP | powerline | Denite | unite | lightline.vim | vim-startify | vimfiler | flagship | vim-workspace

• Customizable and extendable glyphs (icons) settings
  • ability to override defaults and use your own characters or glyphs
• Supports a wide range of file type extensions (» More details... «)
• Supports full filename matches (» More details... «)
• Supports library pattern matches (» More details... «)
• Works with patched fonts, especially Nerd Fonts

Quick Links

Screenshots	API	Fonts ➶	Patcher ➶

Table of Contents

TL;DR Installation

Installation

Usage

• Lightline Setup
• Powerline Setup
• Extra Configuration
• Character Mappings

Features

Screenshots

Methods

Developer

• API
• Contributing
• Inspiration and special thanks
• Todo
• License

FAQ / Troubleshooting

Rationale

Quick Installation (TL;DR)

1. Download and install a patched Nerd Font (or patch your own) (» More details... «)

2. Install the plugin per your usual method (» More details... «)

3. Configure Vim (» More details... «)

• a. vim: Set your terminal emulator font
• b. gvim: Set guifont in your vimrc

Installation

Step 1 Nerd Font

Get a Nerd Font! or patch your own. Without this, things break

Step 2 VimDevIcons Plugin

Choose your favorite plugin manager

Pathogen

• git clone https://github.com/ryanoasis/vim-devicons ~/.vim/bundle/vim-devicons

NeoBundle

• Add to vimrc:

  NeoBundle 'ryanoasis/vim-devicons'

• And install it:

  :so ~/.vimrc
  :NeoBundleInstall

Vundle

• Add to vimrc:

  Plugin 'ryanoasis/vim-devicons'

• And install it:

  :so ~/.vimrc
  :PluginInstall

Manual

• copy all of the files into your ~/.vim directory

Step 3 Configure Vim

Add the following in your .vimrc or .gvimrc:

Set VimDevIcons to load after these plugins!

NERDTree | vim-airline | CtrlP | powerline | Denite | unite | lightline.vim | vim-startify | vimfiler | flagship

Set encoding to UTF-8 to show glyphs

set encoding=utf8

Set Vim font to a Nerd Font

Linux

set guifont=<FONT_NAME> <FONT_SIZE>

set guifont=DroidSansMono\ Nerd\ Font\ 11

macOS (OS X) and Windows

set guifont=<FONT_NAME>:h<FONT_SIZE>

set guifont=DroidSansMono\ Nerd\ Font:h11
" or:
set guifont=DroidSansMono_Nerd_Font:h11

Note: if you don't set guifont then you'll have to set your terminal's font, else things break!

If you use vim-airline you need this

let g:airline_powerline_fonts = 1

vimrc examples

• Sample Windows vimrc configuration 1
• Sample Linux vimrc configuration 1

That's it! You're done. ✅

Usage

If you installed and setup things correctly you should now see icons in the supported plugins!

Notes on include order:

• for support of these plugins: NERDTree, vim-airline, CtrlP, powerline, Denite, unite, vimfiler, flagship you must configure vim to load those plugins before vim-devicons loads.
• for better nerdtree-git-plugin support, you should configure vim to load nerdtree-git-plugin before VimDevIcons loads.

Lightline Setup and Powerline Setup require some extra setup as shown below:

Lightline Setup

To add the appropriate icon to lightline, call the function WebDevIconsGetFileTypeSymbol() and/or WebDevIconsGetFileFormatSymbol() in your .vimrc. For example, you could set your sections to:

let g:lightline = {
      \ 'component_function': {
      \   'filetype': 'MyFiletype',
      \   'fileformat': 'MyFileformat',
      \ }
      \ }

function! MyFiletype()
  return winwidth(0) > 70 ? (strlen(&filetype) ? &filetype . ' ' . WebDevIconsGetFileTypeSymbol() : 'no ft') : ''
endfunction

function! MyFileformat()
  return winwidth(0) > 70 ? (&fileformat . ' ' . WebDevIconsGetFileFormatSymbol()) : ''
endfunction

Powerline Setup

• Note this is for the current Powerline not the deprecated vim-powerline

To enable for Powerline some vimrc and powerline configuration changes are needed:

vimrc changes (only required if you don't already have powerline setup for vim):

set rtp+=$HOME/.local/lib/python2.7/site-packages/powerline/bindings/vim/

" Always show statusline
set laststatus=2

" Use 256 colours (Use this setting only if your terminal supports 256 colours)
set t_Co=256

powerline configuration changes:

file type segment

{
	"function": "vim_devicons.powerline.segments.webdevicons",
	"priority": 10,
	"draw_soft_divider": false,
	"after": "  "
}

file format segment

{
	"function": "vim_devicons.powerline.segments.webdevicons_file_format",
	"draw_soft_divider": false,
	"exclude_modes": ["nc"],
	"priority": 90
 }

for full example see sample file

Detailed Features

• Adds filetype glyphs (icons) to various vim plugins, currently supports:
  • NERDTree
    • Using the version hosted on vimscripts in favor of GitHub will lead to a outdated message, and icons will fail to show.
  • vim-airline (statusline and tabline)
  • CtrlP (All modes now supported)
    • Using the version hosted on vimscripts in favor of GitHub will lead to a outdated message, and icons will fail to show.
  • powerline (statusline)
    • see: powerline setup
  • Denite
    • Currently supports file_rec, file_old, buffer, and directory_rec
  • unite
    • Currently supports file, file_rec, buffer, file_rec/async, and file_rec/neovim
  • lightline.vim (statusline)
    • see: lightline setup
  • vim-startify
  • vimfiler
  • flagship
    • Support is experimental because the API may be changing
• Supports byte order marker (BOM)
• Customizable and extendable glyphs (icons) settings
  • ability to override defaults and use your own characters or glyphs
• Supports a wide range of file type extensions by default:
  • styl, sass, scss, htm, html, slim, ejs, css, less, md, rmd, json, js, jsx, rb, php, py, pyc, pyd, pyo, coffee, mustache, hbs, conf, ini, yml, yaml, bat, jpg, jpeg, bmp, png, gif, twig, cpp, c++, cxx, cc, cp, c, h, hpp, hxx, hs, lhs, lua, java, sh, bash, zsh, ksh, csh, awk, ps1, fish, diff, db, clj, cljs, edn, scala, go, dart, xul, sln, suo, pl, pm, t, rss, f#, fsscript, fsx, fs, fsi, rs, rlib, d, erl, hrl, vim, ai, psd, psb, ts, jl, pp
• Supports a few full filename matches, by default:
  • gruntfile.coffee, gruntfile.js, gruntfile.ls, gulpfile.coffee, gulpfile.js, gulpfile.ls, dropbox, .ds_store, .gitconfig, .gitignore, .bashrc, .zshrc, .vimrc, .bashprofile, favicon.ico, license, node_modules, react.jsx, procfile
• Supports a few library pattern matches, by default:
  • jquery, angular, backbone, requirejs, materialize, mootools, Vagrantfile
• Works with patched fonts, especially Nerd Fonts

Extra Configuration

• These options can be defined in your vimrc or gvimrc
• Most options are enabled 1 by default but can be disabled with 0
• You should not need to configure anything, however, the following options are provided for customizing or changing the defaults:

" loading the plugin 
let g:webdevicons_enable = 1

" adding the flags to NERDTree 
let g:webdevicons_enable_nerdtree = 1

" adding the custom source to unite 
let g:webdevicons_enable_unite = 1

" adding the column to vimfiler 
let g:webdevicons_enable_vimfiler = 1

" adding to vim-airline's tabline 
let g:webdevicons_enable_airline_tabline = 1

" adding to vim-airline's statusline 
let g:webdevicons_enable_airline_statusline = 1

" ctrlp glyphs
let g:webdevicons_enable_ctrlp = 1

" adding to flagship's statusline 
let g:webdevicons_enable_flagship_statusline = 1

" turn on/off file node glyph decorations (not particularly useful)
let g:WebDevIconsUnicodeDecorateFileNodes = 1

" use double-width(1) or single-width(0) glyphs 
" only manipulates padding, has no effect on terminal or set(guifont) font
let g:WebDevIconsUnicodeGlyphDoubleWidth = 1

" whether or not to show the nerdtree brackets around flags 
let g:webdevicons_conceal_nerdtree_brackets = 1

" the amount of space to use after the glyph character (default ' ')
let g:WebDevIconsNerdTreeAfterGlyphPadding = '  '

" Force extra padding in NERDTree so that the filetype icons line up vertically 
let g:WebDevIconsNerdTreeGitPluginForceVAlign = 1

Character Mappings

• ƛ is used as an example below, substitute for the glyph you actually want to use

" change the default character when no match found
let g:WebDevIconsUnicodeDecorateFileNodesDefaultSymbol = 'ƛ'

" set a byte character marker (BOM) utf-8 symbol when retrieving file encoding
" disabled by default with no value
let g:WebDevIconsUnicodeByteOrderMarkerDefaultSymbol = ''

" enable folder/directory glyph flag (disabled by default with 0)
let g:WebDevIconsUnicodeDecorateFolderNodes = 1

" enable open and close folder/directory glyph flags (disabled by default with 0)
let g:DevIconsEnableFoldersOpenClose = 1

" enable pattern matching glyphs on folder/directory (enabled by default with 1)
let g:DevIconsEnableFolderPatternMatching = 1

" enable file extension pattern matching glyphs on folder/directory (disabled by default with 0)
let g:DevIconsEnableFolderExtensionPatternMatching = 0

" enable custom folder/directory glyph exact matching 
" (enabled by default when g:WebDevIconsUnicodeDecorateFolderNodes is set to 1)
let WebDevIconsUnicodeDecorateFolderNodesExactMatches = 1

" change the default folder/directory glyph/icon
let g:WebDevIconsUnicodeDecorateFolderNodesDefaultSymbol = 'ƛ'

" change the default open folder/directory glyph/icon (default is '')
let g:DevIconsDefaultFolderOpenSymbol = 'ƛ'

" change the default dictionary mappings for file extension matches

let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols = {} " needed
let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols['js'] = 'ƛ'

" change the default dictionary mappings for exact file node matches

let g:WebDevIconsUnicodeDecorateFileNodesExactSymbols = {} " needed
let g:WebDevIconsUnicodeDecorateFileNodesExactSymbols['MyReallyCoolFile.okay'] = 'ƛ'

" add or override individual additional filetypes

let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols = {} " needed
let g:WebDevIconsUnicodeDecorateFileNodesExtensionSymbols['myext'] = 'ƛ'

" add or override pattern matches for filetypes
" these take precedence over the file extensions

let g:WebDevIconsUnicodeDecorateFileNodesPatternSymbols = {} " needed
let g:WebDevIconsUnicodeDecorateFileNodesPatternSymbols['.*jquery.*\.js$'] = 'ƛ'

specify OS to decide an icon for unix fileformat (not defined by default)

• this is useful for avoiding unnecessary system() call. see #135 for further details.

let g:WebDevIconsOS = 'Darwin'

Public Methods

" Returns the current version of the plugin
webdevicons#version()

" Calls webdevicons#softRefresh()
" basically a backwards compatibility convenience
webdevicons#refresh()

" Does a 'hard' refresh of NERDTree
" resets vim-devicons syntax and closes and reopens NERDTree
webdevicons#hardRefresh()

" Does a 'soft' refresh of NERDTree
" resets vim-devicons syntax and toggles NERDTree to the same state
webdevicons#softRefresh()

Developer

API

" returns the font character that represents the icon
" parameters: a:1 (filename), a:2 (isDirectory)
" both parameters optional
" by default without parameters uses buffer name
WebDevIconsGetFileTypeSymbol(...)

" returns the font character that represents
" the file format as an icon (windows, linux, mac)
WebDevIconsGetFileFormatSymbol()

API Examples

Simple function call

echo WebDevIconsGetFileFormatSymbol()

vim-startify

let entry_format = "'   ['. index .']'. repeat(' ', (3 - strlen(index)))"

if exists('*WebDevIconsGetFileTypeSymbol')  " support for vim-devicons
  let entry_format .= ". WebDevIconsGetFileTypeSymbol(entry_path) .' '.  entry_path"
else
  let entry_format .= '. entry_path'
endif

Custom status line

Custom vim status line (not relying on vim-airline or lightline):

:set statusline=%f\ %{WebDevIconsGetFileTypeSymbol()}\ %h%w%m%r\ %=%(%l,%c%V\ %Y\ %=\ %P%)

Todo

• more filetypes to support
• customize filetype icon colors (for a current solution see: tiagofumo/vim-nerdtree-syntax-highlight)
• more customization options in general
• more specific FAQ and Troubleshooting help

License

See LICENSE

FAQ / Troubleshooting

See FAQ

Screenshots

See Screenshots

Contributing

Best ways to contribute

• Star it on GitHub - if you use it and like it please at least star it :)
• Promote
• Open issues/tickets
• Submit fixes and/or improvements with Pull Requests

Promotion

Like the project? Please support to ensure continued development going forward:

• Star this repo on GitHub
• Follow the repo on GitHub
• Vote for it on vim.org
• Follow me
  • Twitter
  • GitHub

Source code

Contributions and Pull Requests are welcome.

No real formal process has been setup - just stick to general good conventions for now.

Rationale

After seeing the awesome theme for Atom (seti-ui) and the awesome plugins work done for NERDTree and vim-airline and wanting something like this for Vim I decided to create my first plugin.

Inspiration and special thanks

• vim-airline
• nerdtree
• nerdtree-git-plugin
• seti-ui
• devicons by Theodore Vorillas
• benatespina development.svg.icons
• Steve Losh
• Also thanks to the many contributors

License

See LICENSE