Skip to content
Simon Ho edited this page Oct 17, 2026 · 10 revisions

Where can I see the full color palette?

The visual palette is here, and is automatically updated whenever colors are added/changed.

Customizing colors

There are two kinds of colors: PaletteColors and ThemeColors.

PaletteColors are defined directly as RGB Hex strings, and have arbitrary names that recall their actual color. Conversely, ThemeColors are named and grouped semantically on the basis of their actual function.

In short, a palette defines all the available colors, while a theme maps the PaletteColors to specific ThemeColors and the same palette color may be assigned to multiple theme colors.

You can change both theme or palette colors using config.colors. All the palette color names can be found here, while their shared semantic roles can be found here. The Neovim adapter maps those roles to the Lua ThemeColors names used in overrides.

You can see a visual preview of the entire color palette here.

require('kanagawa-paper').setup({
  colors = {
    palette = {
      -- change all usages of these color names
      sumiInk0 = "#000000",
      fujiWhite = "#FFFFFF",
    },
    theme = {
      -- change specific usages for a specific theme
      ink = {
        ui = {
          float = {
            fg = "#ff0000",
          },
        },
      },
      canvas = {
      -- ...
      }
    },
  }
})

You can also conveniently add/modify hlgroups using the config.overrides option. Supported keywords are the same for :h nvim_set_hl {val} parameter.

require("kanagawa-paper").setup({
 overrides = function(colors)
  return {
   -- Assign a static color to strings
   String = { fg = colors.palette.carpYellow, italic = true },
   -- theme colors will update dynamically when you change theme!
   SomePluginHl = { fg = colors.theme.syn.type, bold = true },
  }
 end,
})

You can find a more detailed explanation of color customization here.

Extracting colors

You can get the palette and theme colors from the colors module like this:

-- Get the colors for the current theme
local colors = require("kanagawa-paper.colors").setup()
local palette_colors = colors.palette
local theme_colors = colors.theme

and use them in your opts function. Example:

{
  "thesimonho/kanagawa-paper",
  branch = "neovim",
  lazy = false,
  priority = 1000,
  opts = function()
    local colors = require("kanagawa-paper.colors")
    local palette_colors = colors.palette
    return {
      colors = {
        theme = {
          ink = {
            ui = {
              bg_dim = palette_colors.boatYellow2,
            },
          },
        },
      },
    }
  end
}

Customizations aren't being applied

Are you using the cache option? If so, try forcing a cache rebuild with :KanagawaPaperCache

Theme reloading

If you're making tweaks to the theme colors and want to see your changes without restarting neovim every time, you can simply unload and reload the package. For example, I have this function bound to a keymap:

function reload()
  for k in pairs(package.loaded) do
    if k:match("^kanagawa%-paper") then
      package.loaded[k] = nil
    end
  end
  require("kanagawa-paper").setup(opts)  -- reload with whatever `opts` table you want
  vim.cmd.colorscheme("kanagawa-paper")
end

Switch theme by time of day

This theme relies on vim.o.background to determine whether the light or dark variant should be used. Because of that, you can use something like this to switch themes depending on the current time of day:

local hour = os.date("*t").hour
vim.o.background = (hour >= 7 and hour < 19) and "light" or "dark"

If you're feeling adventurous you can also map that to an autocmd so you don't need to restart neovim to see the change.