DOCSEARCHbyAlgolia
Submit Docs

nvim-web-devicons

repository·master·Indexed 25 days ago

https://github.com/nvim-tree/nvim-web-devicons

A Neovim plugin providing Nerd Font icons (glyphs) and associated colors. It supports extension-based and filename-based icon matching, light/dark variants, and provides a Lua API for custom icon management, including functions to retrieve icons, colors, and registered icon lists.

Tokens
2K
Snippets
6
Records
7
Agent score
33%

What's inside nvim-web-devicons

  1. Install nvim-web-devicons

    master

    Install the plugin using your preferred Neovim plugin manager. For Neovim 0.12+ using the native vim.pack manager, use the following command:

    vim.pack.add({
  { src = 'https://github.com/nvim-tree/nvim-web-devicons' }
})

    Requirements:

    • Neovim >= 0.7.0
    • A Patched Nerd Font >= 3.3

    Compatibility Note: If you are using older Nerd Font versions, pin the plugin to the appropriate compatibility tag:

    • Nerd Font 3.3: use nerd-v3.2-compat
    • Nerd Font 3.0: use nerd-v2-compat

  2. Configure nvim-web-devicons via setup()

    master

    Use the setup() function to configure icon overrides, color behavior, and display variants.

    Important: If your overrides are not being applied, it is likely because another plugin called setup() before you did. Ensure you call require('nvim-web-devicons').setup() before configuring other plugins that depend on it.

    If you change your colorscheme, you may need to re-call setup() to re-apply highlight groups.

    require'nvim-web-devicons'.setup {
 -- your personal icons can go here (to override)
 -- you can specify color or cterm_color instead of specifying both of them
 -- DevIcon will be appended to `name`
 override = {
  zsh = {
    icon = "",
    color = "#428850",
    cterm_color = "65",
    name = "Zsh"
  }
 };
 -- globally enable different highlight colors per icon (default to true)
 -- if set to false all icons will have the default icon's color
 color_icons = true;
 -- globally enable default icons (default to false)
 -- will get overriden by `get_icons` option
 default = true;
 -- globally enable "strict" selection of icons - icon will be looked up in
 -- different tables, first by filename, and if not found by extension; this
 -- prevents cases when file doesn't have an extension but still gets some icon
 -- because its name matched some extension (default to false)
 strict = true;
 -- set the light or dark variant manually, instead of relying on `background`
 -- (default to nil)
 variant = "light|dark";
 -- override blend value for all highlight groups :h highlight-blend. 
 -- setting this value to `0` will make all icons opaque. (default to nil)
 blend = 0;
 -- same as `override` but specifically for overrides by filename
 -- takes effect when `strict` is true
 override_by_filename = {
  [".gitignore"] = {
    icon = "",
    color = "#f1502f",
    name = "Gitignore"
  }
 };
 -- same as `override` but specifically for overrides by extension
 -- takes effect when `strict` is true
 override_by_extension = {
  ["log"] = {
    icon = "",
    color = "#81e043",
    name = "Log"
  }
 };
 -- same as `override` but specifically for operating system
 -- takes effect when `strict` is true
 override_by_operating_system = {
  ["apple"] = {
    icon = "",
    color = "#A2AAAD",
    cterm_color = "248",
    name = "Apple",
  },
 };
}

  4. Get an icon for a file

    master

    Use get_icon(filename, extension, options) to retrieve an icon and its highlight name.

    • filename: The name of the file (e.g., .bashrc). Matches are case-insensitive.
    • extension: The file extension (e.g., lua). Matches are case-sensitive.
    • options: An optional table containing:
      • default (boolean): If true, returns a default icon if no match is found.
      • strict (boolean): If true, looks up by filename first, then extension, then fallback to default.

    Use require('nvim-web-devicons').has_loaded() to check if the plugin is initialized.

    require'nvim-web-devicons'.get_icon(filename, extension, { default = true })

  5. Get icon and color codes

    master

    To retrieve the actual color hex code or cterm color instead of the highlight group name, use the following functions:

    • get_icon_color(filename, extension): Returns icon, color (where color is the GUI hex code).
    • get_icon_cterm_color(filename, extension): Returns icon, cterm_color.

    For filetype-specific lookups, use the _by_filetype variants:

    • get_icon_color_by_filetype(filetype, opts)
    • get_icon_cterm_color_by_filetype(filetype, opts)
    local icon, color = require'nvim-web-devicons'.get_icon_color("init.lua", "lua")
assert(icon == "")
assert(color == "#51a0cf")

  6. Retrieve all registered icons

    master

    You can fetch all registered icons or filter them by category using these functions:

    • get_icons(): Returns all registered icons.
    • get_icons_by_filename()
    • get_icons_by_extension()
    • get_icons_by_operating_system()
    • get_icons_by_desktop_environment()
    • get_icons_by_window_manager()
    require'nvim-web-devicons'.get_icons()

  7. Set or override icons

    master

    You can programmatically set or override icons using these methods:

    Override specific icons: Use set_icon({...}) with a table containing icon, color, cterm_color, and name.

    Override the default icon: Use set_default_icon(icon, color, cterm_color).

    Set icons by filetype: Use set_icon_by_filetype({ filetype = "new_icon" }) to map a filetype to a specific icon string.

    require("nvim-web-devicons").set_icon {
  zsh = {
    icon = "",
    color = "#428850",
    cterm_color = "65",
    name = "Zsh"
  }
}

require("nvim-web-devicons").set_default_icon('', '#6d8086', 65)

require("nvim-web-devicons").set_icon_by_filetype { cpp = "c", pandoc = "md" }