🌈 colorbox.nvim

Do you want all the most popular (Neo)Vim colorschemes than only one? Do you want to change them from time to time?

This is it! Let's load all the ultra colorschemes into Neovim player!

https://github.com/linrongbin16/colorbox.nvim/assets/6496887/8fff55ea-749d-4064-90b8-a3799519898d

require("colorbox").setup({
  policy = { seconds = 1, implement = "shuffle" },
  timing = "interval",
})

It uses GitHub actions to weekly collect/update the colorscheme dataset.

[!NOTE]

The most popular colorschemes are picked from below websites:

• vimcolorschemes.com
• www.trackawesomelist.com - awesome-neovim

With below conditions:

1. GitHub stars ≥ 500 (by default it only enable ≥ 800, see Configuration).
2. Last git commit is in last 5 years.
3. For multiple plugins that contain a same color name, it picks by following rules:
   1. The awesome-neovim wins the vimcolorschemes (they usually support modern Neovim features).
   2. More github stars.
   3. Newer git commits.

Please check COLORSCHEMES.md for full colorscheme dataset.

It installs colorschemes via git submodule instead of copy-paste source code, so you get continuously updates from original authors.

It allows you to 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.

📖 Table of Contents

• Requirements
• Install
• How it Works
• Usage
• Configuration
  • Filter
  • Timing
  • Policy
  • Background
  • Hook
• Receipts
  • Choose fixed color on nvim start
  • Choose random color on nvim start
  • Change random color per second
  • Choose color by file type
  • Enable all colors
  • Enable only top stars (≥ 1000) & primary colors
  • Disable by name
  • Disable by plugin
• Development
• Contribute

✅ Requirements

• Neovim ≥ 0.9.
• Git.

📦 Install

[!IMPORTANT]

If this plugin provides the main colorscheme (i.e. the color show right after nvim start), then make sure:

1. Don't lazy load it.
2. Load it before all other plugins.

[!IMPORTANT]

Some colorschemes have specific requirements:

• termguicolors
• nvim-treesitter
• lush.nvim

Please manually add these dependencies if you enable them.

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,
  }
})

require('pckr').add({
  {
    'linrongbin16/colorbox.nvim',

    run = function() require("colorbox").update() end,
    config = function() require("colorbox").setup() end,
  };
})

🎬 How it Works

When loading this plugin, it does below steps:

1. Runs the filters, only enables the colors you choose from the dataset (see Filter).
2. Registers the triggers to invoke related policies at a proper timing (see Timing).

When a timing is triggered, it does below steps:

1. Runs the registered policy and pick a colorscheme (see Policy).
2. Refreshes the background option (see Background).
3. Runs the colorscheme command to actually apply the colorscheme.

🚀 Usage

You can use the Colorbox command with below subcommands:

• update: Update 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 is scale=0.7.

• shuffle: Change to a random color.

[!NOTE]

You can still use the colorscheme command to change a colorscheme.

🔧 Configuration

To configure options, please use:

require("colorbox").setup(opts)

The opts is an optional lua table that override the default options. Here we only introduce some of the most options.

For complete default options, please see configs.lua.

Filter

The filter option is to help user filter some colorschemes from the dataset, thus they will never show up.

There're 3 kinds of filters:

• Builtin filter: A lua string that presents the name of a builtin filter. For now we only have the "primary" builtin filter, it only enables the primary color in a plugin, filters all other color variants (when there're multiple colors in one plugin).

• Function filter: A lua function that decides whether to enable/disable a color. It uses the function signature:

  function(color:string, spec:colorbox.ColorSpec):boolean
  

  The function has two parameters:

  • color: The colorscheme name.
  • spec: The colorscheme's meta info, please see @class colorbox.ColorSpec for more details.

  It returns true to enable a color, false to disable a color.

• List filter: A lua list that contains multiple function filters and builtin filters. A colorscheme will only be enabled if all these filters returns true.

Timing

The timing option is to configure when to change to next colorscheme.

There're 3 kinds of timings:

• startup: On nvim start. It works exactly like manually adding the script colorscheme xxx in nvim's init config file.
• interval: On fixed interval timeout. It registers a background job to schedule on a fixed interval timeout (i.e. every X seconds), and triggers the next colorscheme.
• filetype: On file type change. It listens to current buffer's file type, and triggers the next colorscheme if the file type changed.

Policy

The policy option is to configure how to pick the next colorscheme.

There're 3 kinds of policies (they work with the corresponding timings):

• Builtin policy: A lua string that presents the name of a builtin policy. For now we have 4 builtin policies (see below). It can works directly with the startup timing (see: Choose random color on nvim start).

  • shuffle: Pick a random color.
  • in_order: Pick next color in order, color names are ordered from 'A' to 'Z'.
  • reverse_order: Pick next color in reversed order, color names are ordered from 'Z' to 'A'.
  • single: Always pick the same color, i.e. next color is still the current color.

• Fixed interval timeout policy: A lua table that contains seconds and implement fields. It works with the interval timing (see: Change random color per second).

  • seconds: Choose next colorscheme on every X seconds.
  • implement: The name of the builtin policy that choose how to pick the next colorscheme.

• File type policy: A lua table that contains mapping and (optional) empty and (optional) fallback fields. It works with the filetype timing (see: Choose color by file type).

  • mapping: A lua table that maps from file type to color name. When current buffer's file type is hitted, it changes to the mapped color.
  • (Optional) empty: The color name when the file type is empty lua string. When set to nil, it does nothing.
  • (Optional) fallback: The color name when the file type is not found in mapping field. When set to nil, it does nothing.

Background

The background option runs set background=dark/light every time before running the colorscheme command (to change a colorscheme).

require("colorbox").setup({
  background = "dark",
})

Some colors (tokyonight-day, rose-pine-dawn, etc) are forced to be light, i.e. they forced the background option to light inside their internal implementations.

This is no problem, except some user may want all those following colorschemes (after tokyonight-day and rose-pine-dawn) go back to dark background if they're dark-able.

Hook

To execute a hook function after policy is triggered and new colorscheme is applied, please use:

require("colorbox").setup({
  post_hook = function(color, spec)
    vim.notify(string.format("Colorscheme changed to: %s", vim.inspect(color)))
  end,
})

The hook accepts a lua function with below signature:

function(color:string, spec:colorbox.ColorSpec):nil

📝 Receipts

Choose fixed color on nvim start

require("colorbox").setup({
  policy = "single",
  timing = "startup",
})

Choose random color on nvim start

require("colorbox").setup({
  policy = "shuffle",
  timing = "startup",
})

Change random color per second

require("colorbox").setup({
  policy = { seconds = 1, implement = "shuffle" },
  timing = "interval",
})

Choose color by file type

require("colorbox").setup({
  timing = "filetype",
  policy = {
    mapping = {
      lua = "PaperColor",
      yaml = "everforest",
      markdown = "kanagawa",
      python = "iceberg",
    },
    empty = "tokyonight",
    fallback = "solarized8",
  },
})

Enable all colors

require("colorbox").setup({
  filter = false,
})

Enable only top stars (≥ 1000) & primary colors

require("colorbox").setup({
  filter = {
    "primary",
    function(color, spec)
      return spec.github_stars >= 1000
    end
  },
})

Disable by name

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
})

Disable by plugin

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
})

✏️ Development

To develop the project and make PR, please setup with:

• lua_ls.
• stylua.
• selene.

To run unit tests, please install below dependencies:

• vusted.

Then test with vusted ./spec.

🎁 Contribute

Please open issue/PR for anything about colorbox.nvim.

Like colorbox.nvim? Consider