nonicons.nvim/doc/nonicons.nvim.txt

*nonicons.nvim.txt*                                    Nonicons for Neovim

Author:  Barrett Ruth <br.barrettruth@gmail.com>
License: MIT

==============================================================================
INTRODUCTION                                                   *nonicons.nvim*

nonicons.nvim replaces nvim-web-devicons glyphs with icons from the nonicons
font (https://github.com/ya2s/nonicons). It wraps devicons functions so
that any plugin using nvim-web-devicons automatically displays nonicons glyphs.

==============================================================================
REQUIREMENTS                                          *nonicons-requirements*

- nvim-web-devicons (https://github.com/nvim-tree/nvim-web-devicons)
- nonicons font installed in your terminal

==============================================================================
SETUP                                                        *nonicons-setup*

Load nvim-web-devicons before nonicons.nvim. For example, with lazy.nvim: >lua
    {
      'barrettruth/nonicons.nvim',
      dependencies = { 'nvim-tree/nvim-web-devicons' },
      lazy = false,
    }
<
The plugin works automatically with no configuration required. For
customization, see |nonicons-config|.

==============================================================================
CONFIGURATION                                               *nonicons-config*

Configure via `vim.g.nonicons` before the plugin loads: >lua
    vim.g.nonicons = {
      override = true,
    }
<
                                                    *nonicons.config.override*
override ~
    `boolean` (default: `true`)
    Whether to wrap nvim-web-devicons functions with nonicons glyphs.

==============================================================================
API                                                            *nonicons-api*

                                                            *nonicons.get()*
`require('nonicons').get(name)`
    Returns the nonicons character for the given icon name, or `nil` if the
    name is not in the mapping.

    Parameters: ~
        {name}  `string`  Icon name (e.g. `'lua'`, `'python'`, `'git-branch'`)

    Returns: ~
        `string?`  The single-character nonicons glyph

                                                       *nonicons.get_icon()*
`require('nonicons').get_icon(name, ext)`
    Returns the nonicons character for a file, resolved by filename and/or
    extension. Returns `nil` if no match is found (caller decides fallback).

    Resolution order: exact extension → exact filename → extracted extension.

    Parameters: ~
        {name}  `string?`  Filename (e.g. `'init.lua'`, `'Makefile'`)
        {ext}   `string?`  File extension (e.g. `'lua'`, `'py'`)

    Returns: ~
        `string?`  The single-character nonicons glyph

                                              *nonicons.get_icon_by_filetype()*
`require('nonicons').get_icon_by_filetype(ft)`
    Returns the nonicons character for a vim filetype. Returns `nil` if no
    match is found.

    Resolution order: direct mapping key → extension table → filetype table.

    Parameters: ~
        {ft}  `string`  Vim filetype (e.g. `'python'`, `'typescriptreact'`)

    Returns: ~
        `string?`  The single-character nonicons glyph

                                                        *nonicons.mapping*
`require('nonicons').mapping`
    The raw `table<string, integer>` mapping icon names to Unicode codepoints.
    Useful for advanced use cases where you need the codepoint directly: >lua
        local code = require('nonicons').mapping['lua']
        local icon = vim.fn.nr2char(code)
<

==============================================================================
RECIPES                                                    *nonicons-recipes*

Plugins that call nvim-web-devicons functions (oil.nvim, telescope.nvim,
fzf-lua, etc.) pick up nonicons glyphs automatically. The recipes below are
for plugins that accept icon configuration directly.

lualine ~
>lua
    local get = require('nonicons').get

    require('lualine').setup({
      sections = {
        lualine_a = {
          {
            'mode',
            fmt = function(mode)
              local map = {
                NORMAL = get('vim-normal-mode'),
                INSERT = get('vim-insert-mode'),
                VISUAL = get('vim-visual-mode'),
                ['V-LINE'] = get('vim-visual-mode'),
                ['V-BLOCK'] = get('vim-visual-mode'),
                REPLACE = get('vim-replace-mode'),
                COMMAND = get('vim-command-mode'),
                SELECT = get('vim-select-mode'),
                TERMINAL = get('vim-terminal-mode'),
              }
              return map[mode] or mode
            end,
          },
        },
      },
    })
<

nvim-notify ~
>lua
    require('notify').setup({
      icons = {
        ERROR = require('nonicons').get('x-circle'),
        WARN = require('nonicons').get('alert'),
        INFO = require('nonicons').get('info'),
        DEBUG = require('nonicons').get('bug'),
        TRACE = require('nonicons').get('play'),
      },
    })
<

mason.nvim ~
>lua
    require('mason').setup({
      ui = {
        icons = {
          package_installed = require('nonicons').get('check'),
          package_pending = require('nonicons').get('sync'),
          package_uninstalled = require('nonicons').get('x'),
        },
      },
    })
<

oil.nvim ~

    No configuration needed. oil.nvim detects nonicons.nvim and uses it as a
    direct icon provider. If devicons is also loaded, the devicons override
    still applies to other plugins.

fzf-lua ~
>lua
    require('fzf-lua').setup({
      file_icon_padding = ' ',
    })
<

telescope.nvim ~
>lua
    local get = require('nonicons').get

    require('telescope').setup({
      defaults = {
        prompt_prefix = '  ' .. get('telescope') .. '  ',
        selection_caret = ' > ',
        entry_prefix = '   ',
      },
    })
<

nvim-tree ~
>lua
    local get = require('nonicons').get

    require('nvim-tree').setup({
      renderer = {
        icons = {
          glyphs = {
            default = get('file'),
            symlink = get('file-symlink-file'),
            folder = {
              default = get('file-directory-fill'),
              open = get('file-directory-open-fill'),
              symlink = get('file-submodule'),
              empty = get('file-directory-outline'),
              arrow_open = get('chevron-down'),
              arrow_closed = get('chevron-right'),
            },
          },
        },
      },
    })
<

==============================================================================
FONT SETUP                                                    *nonicons-font*

The nonicons font must be installed and configured in your terminal emulator.

Download the font from: https://github.com/ya2s/nonicons/releases

ghostty ~
>
    font_codepoint_map = "U+f101-U+f25c=nonicons"
<

kitty ~
>
    symbol_map U+F101-U+F219 Nonicons
<

wezterm ~
>lua
    config.font = wezterm.font_with_fallback({
      'YourMainFont',
      'Nonicons',
    })
<

iTerm2 ~

    Preferences > Profiles > Text > Non-ASCII Font > select Nonicons

==============================================================================
HEALTH CHECK                                                *nonicons-health*

Run `:checkhealth nonicons` to verify:
- nvim-web-devicons is available
- The nonicons font is installed (via `fc-list`)
- The mapping table loaded successfully

==============================================================================
ACKNOWLEDGEMENTS                                    *nonicons-acknowledgements*

- ya2s/nonicons (https://github.com/ya2s/nonicons) — icon font
- ya2s/nvim-nonicons (https://github.com/ya2s/nvim-nonicons) — original plugin

==============================================================================
vim:tw=78:ts=8:ft=help:norl: