# transparent.nvim

**Repository Path**: rootquan/transparent.nvim

## Basic Information

- **Project Name**: transparent.nvim
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# transparent.nvim

Remove all background colors to make nvim transparent.

![demo](https://user-images.githubusercontent.com/47070852/226154013-bc0168ba-c914-442e-9132-1e86d1899bc5.gif)

---

## Installation

`xiyaowong/transparent.nvim`

Same as other normal plugins, use your favorite plugin manager to install.

> [!NOTE]
> Avoid lazy-loading this plugin to ensure the highlight-clearing logic is triggered. The plugin's function runs quickly.

## Usage

All available options:

```lua
 -- Optional, you don't have to run setup.
require("transparent").setup({
  -- table: default groups
  groups = {
    'Normal', 'NormalNC', 'Comment', 'Constant', 'Special', 'Identifier',
    'Statement', 'PreProc', 'Type', 'Underlined', 'Todo', 'String', 'Function',
    'Conditional', 'Repeat', 'Operator', 'Structure', 'LineNr', 'NonText',
    'SignColumn', 'CursorLine', 'CursorLineNr', 'StatusLine', 'StatusLineNC',
    'EndOfBuffer',
  },
  -- table: additional groups that should be cleared
  extra_groups = {},
  -- table: groups you don't want to clear
  exclude_groups = {},
  -- function: code to be executed after highlight groups are cleared
  -- Also the user event "TransparentClear" will be triggered
  on_clear = function() end,
})
```

Normally, you don't need to call setup. There are two better ways for configuration.

### `g:transparent_groups`

Add additional highlight groups by explicitly assigning the variable `g:transparent_groups`.

For example, if you want to add group `ExtraGroup`, you can do it like this:

```lua
vim.g.transparent_groups = vim.list_extend(vim.g.transparent_groups or {}, { "ExtraGroup" })
-- vimscript: let g:transparent_groups = extend(get(g:, 'transparent_groups', []), ["ExtraGroup"])
```

**You can execute this statement anywhere and as many times as you want, without worrying about whether the plugin has already been loaded or not.**

Here is an example about [akinsho/bufferline.nvim](https://github.com/akinsho/bufferline.nvim).
Simply copy it and paste it after initializing bufferline in your configuration.

```lua
vim.g.transparent_groups = vim.list_extend(
  vim.g.transparent_groups or {},
  vim.tbl_map(function(v)
    return v.hl_group
  end, vim.tbl_values(require('bufferline.config').highlights))
)
```

### `clear_prefix`

Some plugins define highlights dynamically, especially the highlights of icons. e.g. BufferLineDevIcon*, lualine\_*\_DevIcon\*.

So, this plugin provide a helper function `clear_prefix`. It will clear all highlight groups starting with the prefix.

For some plugins of ui, you would like to clear all highlights. At this point you should use `clear_prefix`.

e.g.

- `akinsho/bufferline.nvim`

```lua
require('transparent').clear_prefix('BufferLine')
```

- `nvim-neo-tree/neo-tree.nvim`

```lua
require('transparent').clear_prefix('NeoTree')
```

- `nvim-lualine/lualine.nvim`

```lua
require('transparent').clear_prefix('lualine')
```

---

This plugin will provide a global variable: `g:transparent_enabled` (lua: `vim.g.transparent_enabled`)

Some plugins or themes support setting transparency, and you can use this variable as a flag.<br/>
eg: `require("tokyonight").setup{ transparent = vim.g.transparent_enabled }`

**NOTE**: The plugin will cache and automatically apply transparency settings, so you only need to call the following command.

## Commands

```
:TransparentEnable
:TransparentDisable
:TransparentToggle
```

## FAQ

### How to enable transparent for plugin panels?

You can try adding this highlight group to the options:

```lua
{
  extra_groups = {
    "NormalFloat", -- plugins which have float panel such as Lazy, Mason, LspInfo
    "NvimTreeNormal" -- NvimTree
  },
}
```

### Floating windows?

It is not recommended to set the floating window to be transparent, it will become very weird, and everything will be mixed together.

For more information: https://github.com/xiyaowong/transparent.nvim/issues?q=label%3A%22float+window%22+sort%3Aupdated-desc

## Aknowledgement

[vim-transparent](https://github.com/Kjwon15/vim-transparent)