Features

• Extensive support for TreeSitter syntax highlighting, and many popular plugins
• Compilation to lua byte code for super fast startup times

Installation

Download with your favorite package manager.

use "rebelot/kanagawa.nvim"

Requirements

• neovim latest
• truecolor terminal support
• undercurl terminal support (optional)

Usage

As simple as writing (pasting)

colorscheme kanagawa

vim.cmd("colorscheme kanagawa")

Configuration

There is no need to call setup if you are ok with the defaults.

-- Default options:
require('kanagawa').setup({
    compile = false,             -- enable compiling the colorscheme
    undercurl = true,            -- enable undercurls
    commentStyle = { italic = true },
    functionStyle = {},
    keywordStyle = { italic = true},
    statementStyle = { bold = true },
    typeStyle = {},
    transparent = false,         -- do not set background color
    dimInactive = false,         -- dim inactive window `:h hl-NormalNC`
    terminalColors = true,       -- define vim.g.terminal_color_{0,17}
    colors = {                   -- add/modify theme and palette colors
        palette = {},
        theme = { wave = {}, lotus = {}, dragon = {}, all = {} },
    },
    overrides = function(colors) -- add/modify highlights
        return {}
    end,
    theme = "wave",              -- Load "wave" theme when 'background' option is not set
    background = {               -- map the value of 'background' option to a theme
        dark = "wave",           -- try "dragon" !
        light = "lotus"
    },
})

-- setup must be called before loading
vim.cmd("colorscheme kanagawa")

NOTE 1: If you enable compilation, make sure to run :KanagawaCompile command every time you make changes to your config.

" 1. Modify your config
" 2. Restart nvim
" 3. Run this command:
:KanagawaCompile

NOTE 2: Kanagawa adjusts to the value of some options. Make sure that the options 'laststatus' and 'cmdheight' are set before calling setup.

Themes

Kanagawa comes in three variants:

• wave the default heart-warming theme,
• dragon for those late-night sessions
• lotus for when you're out in the open.

Themes can be changed in three ways:

• Setting config.theme to the desired theme. Note that vim.o.background must be unset.
• Using the background option: Any change to the value of vim.o.background will select the theme mapped by config.background. Use vim.o.background = "" to unset this option.
• Loading the colorscheme directly with:

  vim.cmd("colorscheme kanagawa-wave")
  vim.cmd("colorscheme kanagawa-dragon")
  vim.cmd("colorscheme kanagawa-lotus")
  

  or

  require("kanagawa").load("wave")
  

Customization

In kanagawa, 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').setup({
    ...,
    colors = {
        palette = {
            -- change all usages of these colors
            sumiInk0 = "#000000",
            fujiWhite = "#FFFFFF",
        },
        theme = {
            -- change specific usages for a certain theme, or for all of them
            wave = {
                ui = {
                    float = {
                        bg = "none",
                    },
                },
            },
            dragon = {
                syn = {
                    parameter = "yellow",
                },
            },
            all = {
                ui = {
                    bg_gutter = "none"
                }
            }
        }
    },
    ...
})

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

Common customizations

Remove gutter background

Remove the background of LineNr, {Sign,Fold}Column and friends

colors = {
    theme = {
        all = {
            ui = {
                bg_gutter = "none"
            }
        }
    }
}

Transparent Floating Windows

This will make floating windows look nicer with default borders.

overrides = function(colors)
    local theme = colors.theme
    return {
        NormalFloat = { bg = "none" },
        FloatBorder = { bg = "none" },
        FloatTitle = { bg = "none" },

        -- Save an hlgroup with dark background and dimmed foreground
        -- so that you can use it where your still want darker windows.
        -- E.g.: autocmd TermOpen * setlocal winhighlight=Normal:NormalDark
        NormalDark = { fg = theme.ui.fg_dim, bg = theme.ui.bg_m3 },

        -- Popular plugins that open floats will link to NormalFloat by default;
        -- set their background accordingly if you wish to keep them dark and borderless
        LazyNormal = { bg = theme.ui.bg_m3, fg = theme.ui.fg_dim },
        MasonNormal = { bg = theme.ui.bg_m3, fg = theme.ui.fg_dim },
    }
end,

If you'd like to keep the floating windows darker, but you're unhappy with how borders are rendered, consider using characters that are drawn at the edges of the box:

{ "🭽", "▔", "🭾", "▕", "🭿", "▁", "🭼", "▏" }

Borderless Telescope

Block-like modern Telescope UI

overrides = function(colors)
    local theme = colors.theme
    return {
        TelescopeTitle = { fg = theme.ui.special, bold = true },
        TelescopePromptNormal = { bg = theme.ui.bg_p1 },
        TelescopePromptBorder = { fg = theme.ui.bg_p1, bg = theme.ui.bg_p1 },
        TelescopeResultsNormal = { fg = theme.ui.fg_dim, bg = theme.ui.bg_m1 },
        TelescopeResultsBorder = { fg = theme.ui.bg_m1, bg = theme.ui.bg_m1 },
        TelescopePreviewNormal = { bg = theme.ui.bg_dim },
        TelescopePreviewBorder = { bg = theme.ui.bg_dim, fg = theme.ui.bg_dim },
    }
end,

Dark completion (popup) menu

More uniform colors for the popup menu.

overrides = function(colors)
    local theme = colors.theme
    return {
        Pmenu = { fg = theme.ui.shade0, bg = theme.ui.bg_p1 },  -- add `blend = vim.o.pumblend` to enable transparency
        PmenuSel = { fg = "NONE", bg = theme.ui.bg_p2 },
        PmenuSbar = { bg = theme.ui.bg_m1 },
        PmenuThumb = { bg = theme.ui.bg_p2 },
    }
end,

Integration

Get palette and theme colors

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

-- Get the colors for a specific theme
local wave_colors = require("kanagawa.colors").setup({ theme = 'wave' })

Terminal integration

The following example provides a snippet to automatically change the theme for the Kitty terminal emulator.

vim.api.nvim_create_autocmd("ColorScheme", {
    pattern = "kanagawa",
    callback = function()
        if vim.o.background == "light" then
            vim.fn.system("kitty +kitten themes Kanagawa_light")
        elseif vim.o.background == "dark" then
            vim.fn.system("kitty +kitten themes Kanagawa_dragon")
        else
            vim.fn.system("kitty +kitten themes Kanagawa")
        end
    end,
})

	Name	Hex	Usage
	fujiWhite	#DCD7BA	Default foreground
	oldWhite	#C8C093	Dark foreground (statuslines)
	sumiInk0	#16161D	Dark background (statuslines and floating windows)
	sumiInk1	#1F1F28	Default background
	sumiInk2	#2A2A37	Lighter background (colorcolumn, folds)
	sumiInk3	#363646	Lighter background (cursorline)
	sumiInk4	#54546D	Darker foreground (line numbers, fold column, non-text characters), float borders
	waveBlue1	#223249	Popup background, visual selection background
	waveBlue2	#2D4F67	Popup selection background, search background
	winterGreen	#2B3328	Diff Add (background)
	winterYellow	#49443C	Diff Change (background)
	winterRed	#43242B	Diff Deleted (background)
	winterBlue	#252535	Diff Line (background)
	autumnGreen	#76946A	Git Add
	autumnRed	#C34043	Git Delete
	autumnYellow	#DCA561	Git Change
	samuraiRed	#E82424	Diagnostic Error
	roninYellow	#FF9E3B	Diagnostic Warning
	waveAqua1	#6A9589	Diagnostic Info
	dragonBlue	#658594	Diagnostic Hint
	fujiGray	#727169	Comments
	springViolet1	#938AA9	Light foreground
	oniViolet	#957FB8	Statements and Keywords
	crystalBlue	#7E9CD8	Functions and Titles
	springViolet2	#9CABCA	Brackets and punctuation
	springBlue	#7FB4CA	Specials and builtin functions
	lightBlue	#A3D4D5	Not used
	waveAqua2	#7AA89F	Types
	springGreen	#98BB6C	Strings
	boatYellow1	#938056	Not used
	boatYellow2	#C0A36E	Operators, RegEx
	carpYellow	#E6C384	Identifiers
	sakuraPink	#D27E99	Numbers
	waveRed	#E46876	Standout specials 1 (builtin variables)
	peachRed	#FF5D62	Standout specials 2 (exception handling, return)
	surimiOrange	#FFA066	Constants, imports, booleans
	katanaGray	#717C7C	Deprecated

Accessibility

The colors maintain a 4.5:1 contrast ratio, complying with WCAG 2.1 | Level AA.

Extras

• alacritty
• Alfred
• base16
• broot
• emacs, doom emacs
• fish
• foot
• iTerm
• kitty
• mintty
• pywal
• sway
• wezterm
• Windows Terminal
• Xresources
• tmTheme (bat, delta and lazygit)
• JSON compatible with many terminals Check Gogh for the list of supported terminals.
• 🎉 Bonus! You win a tiny python script🐍 to extract color palettes 🎨 from any image! 🥳

Acknowledgements

• Tokyonight
• Gruvbox
• Catppuccin
• Affinity Designer

Donate

Buy me coffee and support my work ;)