https://github.com/yukimemi/lumiris.nvim
Automatically rotate Neovim colorschemes with persistent like/hate preferences
https://github.com/yukimemi/lumiris.nvim
lua neovim neovim-plugin nvim
Last synced: about 23 hours ago
JSON representation
Automatically rotate Neovim colorschemes with persistent like/hate preferences
- Host: GitHub
- URL: https://github.com/yukimemi/lumiris.nvim
- Owner: yukimemi
- License: mit
- Created: 2026-05-31T04:21:04.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-20T05:25:35.000Z (about 1 month ago)
- Last Synced: 2026-07-01T14:41:45.818Z (26 days ago)
- Topics: lua, neovim, neovim-plugin, nvim
- Language: Lua
- Homepage:
- Size: 32.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
auto-rotate your Neovim colorschemes.
[](https://github.com/yukimemi/lumiris.nvim/actions/workflows/ci.yml)
[](https://github.com/yukimemi/lumiris.nvim/blob/main/LICENSE)
[](https://neovim.io)
Automatically rotate through your installed colorschemes, with per-scheme
like/hate preferences that persist across sessions. A pure-Lua, Neovim-only
rewrite of [lumiris.vim](https://github.com/yukimemi/lumiris.vim) (no Deno /
denops dependency).
## Requirements
- Neovim >= 0.10 (`vim.uv`, `vim.health.start`)
## Install
With [rvpm](https://github.com/yukimemi/rvpm) (recommended):
```sh
rvpm add yukimemi/lumiris.nvim --on-event CursorHold --on-cmd '/^Lumiris.*$/'
```
Or in `config.toml`:
```toml
[[plugins]]
url = "https://github.com/yukimemi/lumiris.nvim"
on_event = "CursorHold"
on_cmd = ["/^Lumiris.*$/"]
```
> rvpm doesn't auto-run `setup()` — when you pass options, call `require("lumiris").setup({ ... })` from a hook file (`plugins/github.com/yukimemi/lumiris.nvim/after.lua`).
Or with [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
"yukimemi/lumiris.nvim",
event = "VeryLazy",
opts = {
interval = 3600, -- seconds between automatic switches (0 = on every event)
},
}
```
`opts` is passed straight to `require("lumiris").setup()`.
## Configuration
Defaults:
```lua
require("lumiris").setup({
notify = false, -- vim.notify for background events (gated by log_level)
log_level = "warn", -- "trace"|"debug"|"info"|"warn"|"error"
interval = 3600, -- seconds; 0 = switch on every event
events = { "FocusLost", "CursorHold" }, -- events that may trigger a switch (rate-limited by interval)
background = nil, -- "dark"|"light"|nil (force &background before applying)
include = {}, -- allowlist of colorscheme names (empty = all installed)
exclude = {}, -- denylist of colorscheme names
state_path = vim.fn.stdpath("state") .. "/lumiris/prefs.json",
})
```
`interval` rate-limits switching: events fire often (e.g. `CursorHold`) but the
colorscheme only changes once `interval` seconds have elapsed. Set `interval = 0`
to switch on *every* event instead.
`setup()` picks a colorscheme immediately when none is active yet, so a fresh
session never sits on `default` waiting for the first `interval` to elapse. If
your config already set a colorscheme, it is left untouched.
## Commands
| Command | Action |
| --- | --- |
| `:LumirisChange` | Switch to a new colorscheme now (ignores the interval) |
| `:LumirisLike` | Boost the current colorscheme (picked more often) |
| `:LumirisHate` | Exclude the current colorscheme and switch away |
| `:LumirisEnable` / `:LumirisDisable` / `:LumirisToggle` | Control automatic switching |
The commands are available without calling `setup()`; only the automatic
rotation needs `setup()`.
## Lua API
```lua
local lumiris = require("lumiris")
lumiris.change() -- == :LumirisChange
lumiris.like("habamax") -- defaults to current colorscheme
lumiris.hate("blue")
lumiris.enable()
lumiris.disable()
lumiris.candidates() -- string[] of eligible colorschemes
```
Preferences are stored as JSON at `state_path`.
## Health
```vim
:checkhealth lumiris
```
## License
MIT