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",
	motion = "interpolate",
	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".
motion	string	"interpolate"	Selects the global transition policy: "reduced", "winblend", or "interpolate".
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.

Motion policy

motion is global so browser transitions and future Neotheme transition surfaces share one preference:

• "interpolate" briefly interpolates semantic palette RGB values in the preview.
• "winblend" applies the target preview palette immediately and uses a short opacity fade.
• "reduced" applies the target preview immediately without animation.

Transition duration and frame count are internal. There are no per-browser or per-transition motion options.

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() replaces the complete configured baseline, resolves its palette, and clears the session-override marker. It does not change active highlights by itself.

During startup, apply that baseline with the colorscheme entrypoint:

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

After replacing setup during an active session, apply the new baseline with either :colorscheme neotheme or require("neotheme").reset().

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

To explore or switch themes without replacing the baseline, use :Neotheme, :NeothemeSwitch <theme>, or require("neotheme").switch(theme). Confirmed session switches copy the latest setup options, including typography, configure_palette, and integrations, and replace only the active theme. Browser row movement remains isolated to its preview namespace. See Session Theme Controls.

Validation behavior

Neotheme fails early for unknown option keys, incorrect option types, and motion values outside reduced, winblend, and interpolate. 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.