API

API

Load the module with:

local neotheme = require("neotheme")

setup(options)

Validates configuration, resolves the selected built-in or custom palette, stores the resolved state, and returns the Neotheme module.

require("neotheme").setup({
	theme = "gruber-dark",
	bold = false,
})

setup does not apply highlights by itself. Load colorscheme neotheme after setup.

See Configuration for the complete option schema.

palette()

Returns a deep copy of the currently resolved semantic palette:

local palette = require("neotheme").palette()
print(palette.surface.base)

If no palette has been resolved yet, palette() resolves the current configuration first. Mutating the returned table does not alter Neotheme state.

Use configure_palette during setup when a change must affect highlights.

themes()

Returns a sorted copy of the available theme names:

local names = require("neotheme").themes()
print(vim.inspect(names))

The list contains:

custom
gruber-dark
gruber-dark-muted
gruber-darker
gruber-light
gruber-light-muted
gruber-lighter

Mutating the returned list does not alter the internal registry.

load()

Applies the resolved palette and configuration. The file colors/neotheme.lua calls this function, so normal use should prefer:

vim.cmd.colorscheme("neotheme")

load() performs these operations:

1. Requires Neovim 0.12 or newer.
2. Sets background from the selected theme.
3. Clears existing highlights when another colorscheme is active.
4. Enables termguicolors.
5. Sets vim.g.colors_name to neotheme.
6. Applies core, Tree-sitter, LSP, terminal, and enabled integration highlights.
7. Invalidates Neotheme's cached Lualine modules.
8. Recreates Neotheme's colorscheme and sidebar autocmds.

State lifecycle

The normal lifecycle is:

setup options -> resolve palette -> load colorscheme -> apply highlights

Calling setup again replaces the resolved configuration and palette. Reload the colorscheme to apply that state.

Errors and warnings

Neotheme raises errors for:

• Unsupported Neovim versions during load
• Unknown option keys
• Incorrect option types
• Unknown theme names
• Unknown palette categories or fields
• Invalid palette color values
• A non-nil return from configure_palette

Neotheme emits a warning, rather than an error, when a resolved palette is missing semantic roles. The warning lists all missing paths.

See Troubleshooting for fixes and Palette Customization for palette rules.