Do you want all the most popular (Neo)vim colorschemes than only one? Do you want to change colorscheme from time to time?
This is it! Let's load all the ultra colorschemes into the Neovim player!
shuffle-per-sec-v2.mp4
Click here to see how to configure
require("colorbox").setup({
policy = { seconds = 1, implement = "shuffle" },
timing = "interval",
})
It use offline github actions to weekly collect/update the colorscheme list.
Note
The most popular colorschemes are picked from below websites:
with below conditions:
- Github stars β₯ 500 (default config only enable β₯ 800, see Configuration).
- Last git commit in 5 years.
- For multiple plugins that contain the same color name, pick by following rules:
- Awesome-neovim wins vimcolorsheme (they usually support modern Neovim features).
- More github stars.
- Newer git commits.
Please check COLORSCHEMES.md for full colorschemes list.
It install via git submodules instead of copy-paste source code, so you get continuously updates from original authors.
It allow you play them with multiple playback settings (policies):
- Suffle playback.
- Play in order.
- Play in reverse order.
- Single cycle.
And multiple trigger timings:
- On startup.
- Fixed interval.
- Date time (todo).
- By filetype.
Click here to see how to install `rm` command on Windows
There're many ways to install portable linux shell and builtin commands on Windows, but personally I would recommend below two methods.
Install with the below 3 options:
-
In Select Components, select Associate .sh files to be run with Bash.
-
In Adjusting your PATH environment, select Use Git and optional Unix tools from the Command Prompt.
-
In Configuring the terminal emulator to use with Git Bash, select Use Windows's default console window.
After this step, git.exe and builtin linux commands(such as rm.exe) will be available in %PATH%
.
Run below powershell commands:
# scoop
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install uutils-coreutils # rm
Important
If this plugin provides the main colorscheme (e.g. the color show right after nvim start), then make sure:
- Don't lazy load it.
- Load it before all other plugins.
Important
Some colorschemes have specific requirements:
Please manually add these dependencies if you enable them.
With lazy.nvim
require('lazy').setup({
{
'linrongbin16/colorbox.nvim',
-- don't lazy load
lazy = false,
-- load with highest priority
priority = 1000,
build = function() require("colorbox").update() end,
config = function() require("colorbox").setup() end,
}
})
With pckr.nvim
require('pckr').add({
{
'linrongbin16/colorbox.nvim',
run = function() require("colorbox").update() end,
config = function() require("colorbox").setup() end,
};
})
When loading plugin, it will run following steps:
- Run the filters, only enable the colors you choose from candidate list. See Filter.
- Register triggers to invoke related policies at a proper timing. See Timing & Policy.
When a timing is triggered, it will run following steps:
- Run registered policy and choose a colorscheme. See Timing & Policy.
- Refresh the
background
option. See Background. - Run
colorscheme
command to actually apply the colorscheme.
You can also use command Colorbox
to control the player with below subcommands:
update
: Update all git submodules.reinstall
: Clean & re-install all git submodules.info
: Show detailed information and configured status.- Note: use
scale=0.7
to specify popup window's size in range(0, 1]
, by default isscale=0.7
.
- Note: use
Note
You can still use colorscheme
command to change colorscheme.
To configure options, please use:
require("colorbox").setup(opts)
The opts
is an optional lua table that override the default options.
For complete default options, please see configs.lua.
There're 3 types of filter configs:
"primary"
: Only enables the main color (if there are multiple colors in one plugin).
Lua function that decide whether to enable/disable a color. It has below signature:
function(color:string, spec:colorbox.ColorSpec):boolean
Parameters:
color
: Color name.spec
: Colorscheme meta info, which is thecolorbox.ColorSpec
type, see below.
Returns:
- To enable a color, returns
true
. - To disable a color, returns
false
.
The colorbox.ColorSpec
type is a lua table that has below fields:
handle
: Unique plugin name,string
type, for example:"folke/tokyonight.nvim"
url
: GitHub url,string
type, for example:"https://github.com/folke/tokyonight.nvim"
github_stars
: Github stars,integer
type, for example:4300
last_git_commit
: Last git commit date and time,string
type, for example:"2023-10-25T18:20:36"
priority
: Plugin priority,integer
type, for example:- awesome-neovim is
100
- vimcolorschemes is
0
- awesome-neovim is
source
: Data source,string
type, for example:- awesome-neovim is
"https://www.trackawesomelist.com/rockerBOO/awesome-neovim/readme/#colorscheme"
- awesome-neovim is
git_path
: Git submodule file path,string
type, for example:"folke-tokyonight.nvim"
git_branch
: Optional git branch of plugin (most plugins use default main/master branch, while some have specific branch),string?
type, for example:"neovim"
color_names
: Color names that plugin contains,string[]
type, for example:["tokyonight","tokyonight-day","tokyonight-moon","tokyonight-night","tokyonight-storm"]
A lua list that contains multiple other filters. A color will only be enabled if all filters returns true
.
To choose a color on nvim start, please use:
require("colorbox").setup({
timing = "startup",
policy = "shuffle",
})
There're 4 builtin policies to work with startup
timing:
shuffle
: Choose a random color.in_order
: Choose next color in order, color names are ordered from 'A' to 'Z'.reverse_order
: Choose next color in reversed order, color names are ordered from 'Z' to 'A'.single
: Choose a fixed color.
To choose a color on a fixed interval time, please use:
require("colorbox").setup({
timing = "interval",
policy = { seconds = 60, implement = "in_order" },
})
The fixed interval timing needs to specify below 2 fields in its policy:
seconds
: Change to next color every X seconds.implement
: The builtin policies (mentioned above) to decide which color to choose.
To choose a color on buffer's file type change, please use:
require("colorbox").setup({
timing = "filetype",
policy = {
mapping = {
lua = "PaperColor",
yaml = "everforest",
markdown = "kanagawa",
python = "iceberg",
},
empty = "tokyonight",
fallback = "solarized8",
},
})
The filetype timing needs to specify below 2 fields in its policy:
mapping
: Lua table that map from buffer's file type to color name.empty
: Optional color name if file type is empty (and surely not found inmapping
), do nothing ifnil
.fallback
: Optional color name if file type is not found inmapping
, do nothing ifnil
.
There're some colors (tokyonight-day
, rose-pine-dawn
) are forced to be light, e.g. they forced set background=light
on loading. Thus the other following colors will continue use light
background.
If you want to bring the dark-able colors back to dark
, please use:
require("colorbox").setup({
background = "dark",
})
It automatically set background=dark
before run a colorscheme
command.
require("colorbox").setup({
policy = "single",
timing = "startup",
})
require("colorbox").setup({
policy = { seconds = 1, implement = "shuffle" },
timing = "interval",
})
require("colorbox").setup({
filter = false,
})
require("colorbox").setup({
filter = {
"primary",
function(color, spec)
return spec.github_stars >= 1000
end
},
})
local function colorname_disabled(colorname)
for _, c in ipairs({
"iceberg",
"ayu",
"edge",
"nord",
}) do
if string.lower(c) == string.lower(colorname) then
return true
end
end
return false
end
require("colorbox").setup({
filter = function(color, spec)
for _, c in ipairs(spec.color_names) do
if colorname_disabled(c) then
return false
end
end
return true
end
})
local function plugin_disabled(spec)
for _, p in ipairs({
"cocopon/iceberg.vim",
"folke/tokyonight.nvim",
"ayu-theme/ayu-vim",
"shaunsingh/nord.nvim",
}) do
if string.lower(p) == string.lower(spec.handle) then
return true
end
end
return false
end
require("colorbox").setup({
filter = function(color, spec)
return not plugin_disabled(spec)
end
})
To develop the project and make PR, please setup with:
To run unit tests, please install below dependencies:
Then test with vusted ./spec
.
Please open issue/PR for anything about colorbox.nvim.
Like colorbox.nvim? Consider