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.

See Architecture for module boundaries, copy isolation, and the full resolution pipeline.