API

API

Load the module with:

local neotheme = require("neotheme")

setup(options)

Validates a complete setup baseline, resolves its selected built-in or custom palette, stores private copies, clears the session-override marker, and returns the Neotheme module.

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

setup() does not change active highlights by itself. Load :colorscheme neotheme during startup, or use reset() after replacing a baseline during a session. See Configuration for the option schema.

palette()

Returns a deep copy of the currently resolved semantic palette:

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

Mutating the returned table does not alter Neotheme state. Use configure_palette during setup when a change must affect highlights.

themes(family?)

Returns sorted theme-name copies:

local all_names = neotheme.themes()
local typeset_names = neotheme.themes("typeset")

The unfiltered result contains all 31 built-ins plus custom. A family-filtered result contains only that family's built-in members. An unknown family raises an error.

families()

Returns the nine sorted built-in family names:

local families = neotheme.families()

The returned list is a copy and can be modified without changing the registry.

switch(theme)

Applies a built-in theme for the current session and returns the Neotheme module:

neotheme.switch("typeset-paper")

switch() copies the latest setup options, replaces the theme name, resolves a fresh palette, and runs the normal highlight pipeline. It preserves typography, palette configuration, terminal colors, and enabled integrations without modifying the configured baseline. Switching to custom is rejected.

current()

Returns a defensive read-only description of session state:

local current = neotheme.current()

Field	Type	Meaning
loaded	boolean	Whether Neotheme currently owns the active colorscheme state
active_theme	string or nil	Applied theme when loaded
family	string or nil	Active built-in family; custom themes have no family
configured_theme	string	Theme from the latest successful setup baseline
background	"dark", "light", or nil	Applied background when loaded
session_override	boolean	Whether the active theme differs through a session override

The returned table can be mutated without changing internal state.

reset()

Applies the complete latest setup baseline, clears any session override, and returns the configured theme name:

local configured_theme = neotheme.reset()

Reset is session-only; it does not write configuration.

reload()

Rebuilds and reapplies the active theme, rerunning configure_palette against a fresh base, and returns the reloaded theme name:

local reloaded_theme = neotheme.reload()

If a session override is active, reload preserves it. Otherwise it reloads the configured baseline.

load()

Applies the configured baseline and clears any session override. colors/neotheme.lua calls this function, so normal use should prefer:

vim.cmd.colorscheme("neotheme")

load() checks the Neovim version, sets background and termguicolors, applies all highlight layers and terminal colors, invalidates cached Neotheme Lualine adapters, and recreates the colorscheme lifecycle and sidebar autocmds.

State lifecycle

setup options -> configured baseline -> colorscheme load -> applied baseline
                                             |
                                             +-> browser preview namespace
                                             |          |
                                             |          +-> Enter/Space confirmation
                                             |                         |
                                             +-> switch -------------->+-> session override
                                                                         |
                                                        reset <----------+

Browser row movement does not alter public state. Enter confirms and closes; Space confirms while keeping the browser open and advances its private checkpoint. Cancellation restores the latest checkpoint. Public callers should use current(), switch(), reset(), and reload(); underscore-prefixed functions are internal.

Errors and warnings

Neotheme raises errors for:

• Unsupported Neovim versions during application
• Unknown option keys or incorrect option types
• Unknown theme or family names
• Invalid switch targets, including custom
• Unknown palette categories or fields
• Invalid palette color values
• A non-nil return from configure_palette
• Opening the browser before Neotheme is loaded or below its minimum size

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 Architecture for internal ownership and flow.