🌊 kanagawa-paper.nvim

Remixed light and dark Kanagawa color scheme with muted colors. For Neovim.

Ink	Canvas

💡 Motivation

I love the original kanagawa.nvim color scheme, but I found some of the colors a bit too bright and distracting. What I wanted was a more muted theme overall, using less saturated colors inspired by the original theme.

Both a light theme and a dark theme are provided.

I have also ported the color scheme to VSCode, which you can find here: kanagawa-paper.vscode

⚡️ Requirements

• Neovim >= 0.8.0
• truecolor terminal support
• undercurl terminal support (optional)

📦 Installation

Install the theme with your preferred package manager, such as lazy.nvim:

{
  "thesimonho/kanagawa-paper.nvim",
  lazy = false,
  priority = 1000,
  opts = {},
}

🚀 Usage

Kanagawa Paper comes in a few variants:

• kanagawa-paper-ink for late nights
• kanagawa-paper-canvas for sunny days
• kanagawa-paper for automatic theme switching based on vim.o.background

Themes can be changed in a couple of ways:

• Using the background option: Any change to the value of vim.o.background will select the corresponding light or dark theme. If this is unset, the theme will default to the dark theme ink.
• Loading the color scheme directly with:

Vim:

colorscheme kanagawa-paper
colorscheme kanagawa-paper-ink
colorscheme kanagawa-paper-canvas

Neovim:

vim.cmd.colorscheme("kanagawa-paper")
vim.cmd.colorscheme("kanagawa-paper-ink")
vim.cmd.colorscheme("kanagawa-paper-canvas")

🛠️ Configuration

[!NOTE] Config options have changed between v1 and v2 of the color scheme.

[!IMPORTANT] Set the configuration BEFORE loading the color scheme to ensure the settings are applied, otherwise defaults will be used.

The default configuration can be found here

require("kanagawa-paper").setup({
 -- enable undercurls for underlined text
 undercurl = true,
 -- transparent background
 transparent = false,
 -- highlight background for the left gutter
 gutter = false,
 -- background for diagnostic virtual text
 diag_background = true,
 -- dim inactive windows. Disabled when transparent
 dim_inactive = true,
 -- set colors for terminal buffers
 terminal_colors = true,
 -- cache highlights and colors for faster startup.
 -- see Cache section for more details.
 cache = false,

 styles = {
  -- style for comments
  comment = { italic = true },
  -- style for functions
  functions = { italic = false },
  -- style for keywords
  keyword = { italic = false, bold = false },
  -- style for statements
  statement = { italic = false, bold = false },
  -- style for types
  type = { italic = false },
 },
 -- override default palette and theme colors
 colors = {
  palette = {},
  theme = {
   ink = {},
   canvas = {},
  },
 },
 -- adjust overall color balance for each theme [-1, 1]
 color_offset = {
  ink = { brightness = 0, saturation = 0 },
  canvas = { brightness = 0, saturation = 0 },
 },
 -- override highlight groups
 overrides = function(colors)
  return {}
 end,

 -- uses lazy.nvim, if installed, to automatically enable needed plugins
 auto_plugins = true,
 -- enable highlights for all plugins (disabled if using lazy.nvim)
 all_plugins = package.loaded.lazy == nil,
 -- manually enable/disable individual plugins.
 -- check the `groups/plugins` directory for the exact names
 plugins = {
  -- examples:
  -- rainbow_delimiters = true
  -- which_key = false
 },

 -- enable integrations with other applications
 integrations = {
  -- automatically set wezterm theme to match the current neovim theme
  wezterm = {
   enabled = false,
   -- neovim will write the theme name to this file
   -- wezterm will read from this file to know which theme to use
   path = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme",
  },
 },
})

If you want to switch between canvas and ink themes within a Neovim session, you can change vim.o.background to light or dark.

This can also be mapped to the time of day via an autocommand or dynamically setting vim.o.background at startup. For example:

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

Cache

The color scheme comes with a cache option that can be used to speed up startup time.

When you set cache = true in your config, the theme colors and all of your edits/adjustments will be saved to a cache file. This is loaded at startup so colors don't need to be recomputed every time.

Any changes you make to your config (e.g. overriding colors or highlight groups) should automatically invalidate the cache and build a new one.

In rare cases where this doesn't happen and you notice your changes aren't being applied, you can manually rebuild the cache by running :KanagawaPaperCache.

👥 Integrations

Lualine

This color scheme comes with matching Lualine themes for both ink and canvas variants.

This will set the theme at startup:

local kanagawa_paper = require("lualine.themes.kanagawa-paper-ink")
-- local kanagawa_paper = require("lualine.themes.kanagawa-paper-canvas")

require("lualine").setup({
 options = {
  theme = kanagawa_paper,
  -- ... your lualine config
 },
})

For a more advanced use case you can make use of the background color to set the Lualine theme dynamically. This switches Lualine between light and dark themes based on background color:

require("lualine").setup({
 options = {
  theme = function()
    -- pcall and fallback theme is to handle the case of theme switching/previewing
    local ok, t = pcall(
      require,
      "lualine.themes." .. (vim.o.background == "light" and "kanagawa-paper-canvas" or "kanagawa-paper-ink")
    )
    if ok then
      theme = t
    else
      theme = require("some other fallback theme")
    end
    return theme
  end,
  -- ... your lualine config
 },
})

Examples of situations where this might be useful:

• You want to change the theme mid-session
• You want to change background color mid-session (either by manually setting vim.o.background or with something like dark background toggle in LazyVim)
• You use a plugin for live previews of color schemes

WezTerm and WezTerm Tabline

If you use WezTerm and/or WezTerm Tabline, you can use the wezterm integration to automatically switch themes based on the current Neovim theme. This feature requires Wezterm automatic reload config to be turned on.

There are a few things to set up for this to work:

1. Enable the integration in your Neovim configuration:

require("kanagawa-paper").setup({
 integrations = {
  wezterm = {
   enabled = true,
   path = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme"
  },
 },
})

2. Place the wezterm and wezterm tabline extras in the wezterm color scheme directory. Point wezterms config to that directory:

config.color_scheme_dirs = { "~/.config/wezterm/colors" } -- or wherever you want to store the themes

3. Copy theme_switcher.lua to where your wezterm config is. Add require("theme_switcher") to your wezterm config to load the theme switcher.

Your final wezterm config directories might look something like this:

4. Update the theme_switcher.lua file with the correct paths to your files:

-- default colorscheme after neovim exits
local theme_default = "kanagawa-paper-ink"

-- this should match the path set in the neovim config
-- it's best to use a temporary directory for this
local theme_file = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme"

-- relative path to the directory containing the tabline themes
-- e.g. if I have placed the tabline extra themes in ./colors/wezterm_tabline then this would be "colors.wezterm_tabline"
-- this is treated as a relative lua module that will be required by the theme switcher
local tabline_theme_dir = "colors.wezterm_tabline"

You can see an example of this setup in my dotfiles here.

🔧 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 usage by each theme can be found 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

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

🍭 Extras

• alacritty
• ghostty
• kitty
• terminator
• termux
• tilix
• vscode (official port)
• vscode terminal (guide: Visual Studio Code Theme Color)
• fzf (guide: fzf color schemes)
• wezterm (guide: Defining a Color Scheme in a separate file)
• wezterm tabline (guide: tabline.wez)
• windows terminal (guide: Color schemes in Windows Terminal)

🔥 Contributing

Pull requests are welcome for theme fixes, new features, and new extras.

For the extras, we use a simple template system that can be used to generate styles for the different themes.

How to add a new extra template:

1. Create a new template file in lua/kanagawa-paper/extras.
2. Add the name and output file extension to the extras table in lua/kanagawa-paper/extras/init.lua.
3. To check that your template compiles properly, run ./scripts/build.sh and check the newly compiled styles in the root extras directory.

[!IMPORTANT] Please DO NOT commit the compiled files, as they are already automatically built by the CI.

👏 Acknowledgements

• Kanagawa
• Tokyo Night