nvim-web-devicons

# Nvim-web-devicons

Provides [Nerd Font](https://www.nerdfonts.com/) [^1] icons (glyphs) for use by *Neovim* plugins:

- Icons by:
  - Extension
  - Full name
- Colours
- Light and dark variants
- API to modify/add icons

A `lua` fork of [vim-devicons](https://github.com/ryanoasis/vim-devicons).

> [!TIP]
> nvim-web-devicons is a rolling release, adding new icons as they are introduced to Nerd Fonts. Please ensure that you are using the latest version of the font as newly introduced icons may display incorrectly or as an "unknown character".

> [!IMPORTANT]
> Nerd fonts has introduced some breaking changes with the following releases.
> Please use your plugin manager to pin nvim-web-devicons to the compatibility tag, for use with earlier Nerd Font versions.
> - `3.3`: `nerd-v3.2-compat`
> - `3.0`: `nerd-v2-compat`

[^1]: Not limited to Nerd Font icons: unicode and other fonts may be used.

## Requirements

- [neovim >=0.7.0](https://github.com/neovim/neovim/wiki/Installing-Neovim)
- [A Patched Nerd Font](https://www.nerdfonts.com/) >= 3.3

## Installation

### [vim.pack](https://neovim.io/doc/user/pack.html#vim.pack) - Neovim 0.12+ Native Plugin Manager
```lua
vim.pack.add({
  { src = 'https://github.com/nvim-tree/nvim-web-devicons' }
})
```

## Additional Icons

Additional icons may be added for icons that are present in Nerd Fonts: use the [Cheat Sheet](https://www.nerdfonts.com/cheat-sheet) search for available icons.

PRs are always welcome! Please see [CONTRIBUTING](CONTRIBUTING.md)

> [!IMPORTANT]
> If the icon you need is not available on Nerd Fonts you first need to make a
> PR to a project that feeds glyphs to Nerd Fonts. Probably the most adequate
> project to contribute is <https://github.com/devicons/devicon>.
> Take into account that **months** can pass before the icon is available on the
> Nerd Fonts project, once there feel free to open a PR on this project, see 
> [CONTRIBUTING](CONTRIBUTING.md)

## Usage

### Viewing

Run `:NvimWebDeviconsHiTest` to see all icons and their highlighting.

### Variants

Light or dark color variants of the icons depend on `&background`.  
The variant can also be set manually in `setup` with the `variant` option.

The variant is updated:

- on `OptionSet` event for `background`, or
- after explicitly calling `require("nvim-web-devicons").refresh()`.

However, be advised that the plugin using nvim-web-devicons may have cached the icons.

### Case Sensitivity

Filename icons e.g. `"Dockerfile"` are case insensitively matched.

Extension icons e.g. `"lua"` are case sensitive.

### Setup

This adds all the highlight groups for the devicons
i.e. it calls `vim.api.nvim_set_hl` for all icons
this might need to be re-called in a `Colorscheme` to re-apply cleared highlights
if the color scheme changes

```lua
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`
 o