Configuration

Configuration

Call setup before loading the neotheme colorscheme. Options are validated, merged with the defaults, and used to resolve the selected palette.

Complete default configuration

require("neotheme").setup({
	theme = "gruber-dark-muted",
	configure_palette = nil,
	bold = true,
	italic = {
		comments = true,
		strings = true,
		folds = true,
		operators = false,
	},
	underline = true,
	undercurl = true,
	integrations = {
		nvim_tree = false,
		cmp = false,
		blink_cmp = false,
		telescope = false,
		fzf_lua = false,
		gitsigns = false,
		fugitive = false,
		lspsaga = false,
		rainbow_delimiters = false,
		bufferline = false,
		lazy = false,
		which_key = false,
		trouble = false,
		noice = false,
		snacks = false,
	},
})

vim.cmd.colorscheme("neotheme")

You only need to provide values that differ from these defaults. Nested option tables are merged, so setting one integration or one italic option does not replace its siblings.

Top-level options

Option	Type	Default	Purpose
theme	string	"gruber-dark-muted"	Selects a built-in theme or "custom".
configure_palette	function or nil	nil	Mutates the resolved semantic palette before highlights are applied.
bold	boolean	true	Enables bold emphasis in supported groups.
italic	table	See below	Controls italics by content type.
underline	boolean	true	Enables underline emphasis and supported links.
undercurl	boolean	true	Enables diagnostic and unnecessary-code undercurls.
integrations	table	All false	Enables plugin-specific highlight groups.

Italic options

Option	Default	Applies to
italic.comments	true	Comments and comment-derived groups
italic.strings	true	Strings
italic.folds	true	Folded text
italic.operators	false	Operators

Some groups use italics as part of their fixed meaning, including inlay hints, code lenses, quotes, documentation modifiers, and pre-insert completion text. The options above control the user-facing typography categories, not every fixed semantic annotation.

Integration options

Every integration defaults to false and must be enabled explicitly.

Option	Plugin surface
blink_cmp	blink.cmp
bufferline	bufferline.nvim
cmp	nvim-cmp
fugitive	vim-fugitive
fzf_lua	fzf-lua
gitsigns	gitsigns.nvim
lazy	lazy.nvim UI
lspsaga	lspsaga.nvim
noice	noice.nvim
nvim_tree	nvim-tree.lua
rainbow_delimiters	rainbow-delimiters.nvim
snacks	snacks.nvim
telescope	telescope.nvim
trouble	trouble.nvim
which_key	which-key.nvim

See Integrations for behavior and setup examples.

Palette configuration

configure_palette receives a private copy of the selected complete palette:

require("neotheme").setup({
	theme = "gruber-dark",
	configure_palette = function(palette)
		palette.ui.accent = palette.syntax.function_name
		palette.ui.search = palette.diagnostic.warning
		palette.surface.selected = palette.surface.raised
	end,
})

The function must mutate its argument and return nil. Unknown categories, unknown fields, non-string values, and colors outside the six-digit #RRGGBB format raise an error.

See Palette Customization for every semantic role and Custom Themes for an empty starting palette.

Applying configuration changes

setup resolves configuration and palette state. colorscheme neotheme applies that state to Neovim.

To change a theme or palette after startup, run both operations again:

require("neotheme").setup({ theme = "gruber-lighter" })
vim.cmd.colorscheme("neotheme")

Loading the colorscheme also:

• Sets background to dark or light for a built-in theme
• Sets background to dark for theme = "custom"
• Enables termguicolors
• Rebuilds core, Tree-sitter, LSP, terminal, and enabled integration highlights
• Invalidates the cached Neotheme Lualine modules
• Applies sidebar styling to help and quickfix windows

Validation behavior

Neotheme fails early for unknown option keys and incorrect option types. Unknown theme names fail while the palette is resolved. Partial custom palettes are allowed but emit one warning listing every missing semantic path.

For common errors and their fixes, see Troubleshooting.