Session Theme Controls

Session theme controls

Neotheme separates the configured baseline from the theme currently applied to the editor. The baseline comes from the latest successful setup() call. Browsing and switching can temporarily override that baseline without writing configuration.

Visual browser

Open the browser after Neotheme has loaded:

:Neotheme

The browser starts on the active theme's family. Family movement does not change the preview. Drilling into a family and moving through its themes update only the code preview window. The rest of Neovim stays on the latest confirmed theme until Enter or Space confirms a selection.

Key	Action
<CR>	Drill into the selected family, or apply the selected theme and close
<Space>	Drill into the selected family, or apply the selected theme and keep browsing
<Esc> or q	Close at the latest confirmed theme
<Tab> or <S-Tab>	Switch between Families and Themes
h or 1	Show families
l or 2	Show themes for the selected family
<BS> or <C-h>	Return to families
Normal movement keys	Select a family or update the isolated theme preview

The browser re-centers all surfaces on VimResized. Its minimum is 64 columns by 18 usable rows. If Neovim becomes smaller, the browser closes at the latest confirmed theme, cleans its windows and buffers, and reports the size requirement.

Custom themes are not listed because the browser cannot reconstruct arbitrary custom palette inputs as named alternatives. If a custom theme is active, the browser starts from the first built-in family; preview navigation remains local until a built-in theme is confirmed.

Motion policy

The top-level motion setup option controls the preview transition:

Value	Behavior
"interpolate"	Default. Interpolate semantic palette RGB values in the preview window.
"winblend"	Apply target colors immediately, then show a short preview opacity fade.
"reduced"	Apply target colors immediately with no animation.

Rapid interpolation cancels the superseded transition and restarts from the colors currently rendered in the preview. Resizing remains safe while any transition is active.

Commands

Command	Behavior
:Neotheme	Open the family-first visual browser
:NeothemeList	Print all families and their members
:NeothemeList <family>	Print one family's members
:NeothemeSwitch <theme>	Apply a built-in theme as a session override
:NeothemeCurrent	Print active, family, configured, background, and override state
:NeothemeReset	Apply the complete latest setup baseline and clear the override
:NeothemeReload	Rebuild and reapply the active configured theme or override

All command arguments support the relevant completion. :NeothemeSwitch excludes custom; custom palettes must be supplied through setup().

Lua equivalents

local neotheme = require("neotheme")

neotheme.switch("typeset-paper")
local state = neotheme.current()
neotheme.reset()
neotheme.reload()

See API for return values and the complete state shape.

Persistence and baseline behavior

Session selection is intentionally non-durable:

• switch() and browser confirmation do not edit setup tables or files.
• Restarting Neovim applies the theme from configuration.
• reset() returns to the latest successful setup baseline.
• A later setup() replaces the in-memory baseline and clears the override marker.
• Loading :colorscheme neotheme applies the configured baseline and clears any override.

If setup() is called while an older Neotheme palette remains visible, :NeothemeCurrent can show a different configured and active theme until the new baseline is applied.

Preview and confirmation boundaries

Browser previews resolve the selected theme with the latest typography and configure_palette, then apply core, Tree-sitter, LSP, and diagnostic highlights in a private preview namespace. Preview navigation does not change Neotheme session state, vim.o.background, terminal colors, Lualine caches, global highlights, or enabled integration highlights.

Enter and Space confirm through the normal session switch pipeline. Confirmation updates the whole editor, including background, terminal colors, Lualine discovery, and enabled integrations. Space also advances the cancellation checkpoint: later previews remain local, and Escape or q leaves the editor on that most recently confirmed theme.