gruvbox.nvim

A port of gruvbox community theme to lua with treesitter and semantic highlights support!

Prerequisites

Neovim 0.8.0+

Installing

Using packer

use { "ellisonleao/gruvbox.nvim" }

Using lazy.nvim

{ "ellisonleao/gruvbox.nvim", priority = 1000 , config = true, opts = ...}

Using vim-plug

Plug 'ellisonleao/gruvbox.nvim'

Basic Usage

Inside init.vim

set background=dark " or light if you want light mode
colorscheme gruvbox

Inside init.lua

vim.o.background = "dark" -- or "light" for light mode
vim.cmd([[colorscheme gruvbox]])

Configuration

Additional settings for gruvbox are:

-- Default options:
require("gruvbox").setup({
  terminal_colors = true, -- add neovim terminal colors
  undercurl = true,
  underline = true,
  bold = true,
  italic = {
    strings = true,
    emphasis = true,
    comments = true,
    operators = false,
    folds = true,
  },
  strikethrough = true,
  invert_selection = false,
  invert_signs = false,
  invert_tabline = false,
  inverse = true, -- invert background for search, diffs, statuslines and errors
  contrast = "", -- can be "hard", "soft" or empty string
  palette_overrides = {},
  overrides = {},
  dim_inactive = false,
  transparent_mode = false,
})
vim.cmd("colorscheme gruvbox")

VERY IMPORTANT: Make sure to call setup() BEFORE calling the colorscheme command, to use your custom configs

Overriding

Palette

You can specify your own palette colors. For example:

require("gruvbox").setup({
    palette_overrides = {
        bright_green = "#990000",
    }
})
vim.cmd("colorscheme gruvbox")

Highlight groups

If you don't enjoy the current color for a specific highlight group, now you can just override it in the setup. For example:

require("gruvbox").setup({
    overrides = {
        SignColumn = {bg = "#ff9900"}
    }
})
vim.cmd("colorscheme gruvbox")

It also works with treesitter groups and lsp semantic highlight tokens

require("gruvbox").setup({
    overrides = {
        ["@lsp.type.method"] = { bg = "#ff9900" },
        ["@comment.lua"] = { bg = "#000000" },
    }
})
vim.cmd("colorscheme gruvbox")

Please note that the override values must follow the attributes from the highlight group map, such as:

• fg - foreground color
• bg - background color
• bold - true or false for bold font
• italic - true or false for italic font

Other values can be seen in synIDattr

Lualine Support

Gruvbox.nvim includes built-in support for lualine.nvim status line plugin.

Usage

Method 1: Traditional API (Backward Compatible)

require('lualine').setup {
  options = {
    theme = require('gruvbox').lualine() -- dark | light | nil
    -- ... other lualine options
  }
}

Method 2: Integrations Module (Recommended)

require('lualine').setup {
  options = {
    theme = require('gruvbox.integrations.lualine').get() -- dark | light | nil
    -- ... other lualine options
  }
}

Dynamic Integration Management

local integrations = require('gruvbox.integrations')

-- List all available integrations
print(vim.inspect(integrations.list())) -- { "lualine" }

-- Get integration dynamically
local lualine_theme = integrations.get('lualine').get()

require('lualine').setup {
  options = {
    theme = lualine_theme
    -- ... other lualine options
  }
}

The theme automatically adapts to your background setting (dark/light) and respects gruvbox configuration options.

Features

• Auto-detection: Automatically selects dark or light variant based on vim.o.background
• Mode-aware colors: Different colors for each Vim mode (normal, insert, visual, replace, command, inactive)
• Consistent styling: Uses the same color palette as your gruvbox theme
• Full compatibility: Works with all gruvbox configuration options

Bufferline Support

Gruvbox.nvim includes built-in support for bufferline.nvim buffer line plugin.

Usage

require('bufferline').setup {
  highlights = require('gruvbox.integrations.bufferline').get(),
  -- ... other bufferline options
}

The bufferline integration provides:

• Consistent theming: Matches your gruvbox color scheme
• Transparent mode support: Respects the transparent_mode setting
• Full diagnostic support: Proper coloring for error, warning, info, and hint indicators
• Buffer state indicators: Clear visual distinction between active, visible, and background buffers
• Customizable styling: Respects gruvbox's bold and other style options