Getting Started

Getting started

Requirements

• Neovim 0.12 or newer
• A terminal or GUI with true-color support

Neotheme checks the Neovim version when the colorscheme loads and enables termguicolors automatically.

Install with lazy.nvim

{
	"alsi-lawr/neotheme.nvim",
	lazy = false,
	priority = 1000,
	config = function()
		require("neotheme").setup()
		vim.cmd.colorscheme("neotheme")
	end,
}

Loading the theme eagerly with a high priority lets other UI plugins consume its highlight groups during their own setup.

Install with vim.pack

vim.pack.add({ "https://github.com/alsi-lawr/neotheme.nvim" })

require("neotheme").setup()
vim.cmd.colorscheme("neotheme")

First launch

The minimal setup selects gruber-dark-muted:

require("neotheme").setup()
vim.cmd.colorscheme("neotheme")

Confirm the active colorscheme and theme state from Neovim:

:lua print(vim.g.colors_name)
:NeothemeCurrent

The expected colorscheme name is neotheme; the configured and active theme is gruber-dark-muted with a dark background.

Browse themes live

Run:

:Neotheme

Choose a family, press <CR> or <Space> to drill into its themes, and move through the list to update only the code preview. Press <Space> on a theme to apply it and keep browsing, or <CR> to apply it and close. <Esc> and q close at the latest confirmed theme. <Tab>, <S-Tab>, h/l, and 1/2 switch the Families and Themes tabs; backspace returns to families.

The browser re-centers when Neovim is resized. If the editor becomes smaller than its supported layout, the browser safely closes at the latest confirmed theme.

See Session Theme Controls for the complete browser and command behavior.

Select the configured baseline

Pass a built-in name to setup before loading the colorscheme:

require("neotheme").setup({
	theme = "gruber-light-muted",
})

vim.cmd.colorscheme("neotheme")

There is no separate colorscheme command for each variant. :colorscheme gruber-light-muted is not valid. setup() selects the configured baseline; the colorscheme command is always neotheme.

Session controls such as :Neotheme, :NeothemeSwitch, and their Lua equivalents do not write configuration. Restarting Neovim or applying the baseline again returns to the theme from setup.

See Themes for all families and inventories.

Enable plugin integrations

Plugin-specific highlights are opt-in:

require("neotheme").setup({
	integrations = {
		gitsigns = true,
		nvim_tree = true,
		telescope = true,
	},
})

vim.cmd.colorscheme("neotheme")

Confirmed session switches retain these latest successful setup options. Browser row previews remain isolated from integration highlights until confirmation. Neotheme defines groups for enabled integrations without requiring or loading the plugin module. See Integrations for all supported keys.

Configure Lualine

Lualine uses its own theme selection:

require("neotheme").setup()
vim.cmd.colorscheme("neotheme")

require("lualine").setup({
	options = {
		theme = "neotheme",
	},
})

See Lualine for runtime refresh behavior.