Overview

Nightfox is a highly customizable theme for vim and neovim with support for lsp, treesitter and a variety of plugins. It comes with multiple different styles to suite your preference. These are:

Nightfox
Dayfox
Dawnfox
Duskfox
Nordfox
Terafox
Carbonfox

Usage

At it's core nightfox is simply a colorscheme just like any other. If you just want to use the theme out of the box simply set the colorscheme with the :colorscheme command

:colorscheme nightfox

Nightfox is built to be customizable. There are four main components that can be customized. These are option, palette, spec, and group.

Configuration

Nightfox allows you to set individual components separately as apposed to using the default setup function.

Init

The init() function set nightfox's config options.

require('nightfox').init({
  dim_inactive = true,
})

Overrides

The individual components: palettes, specs and groups can be set separately.

local override = require('nightfox').override
override.palettes({
  nightfox = {
    red = "#c94f6d",
  },
  nordfox = {
    comment = "#60728a",
  },
})
override.specs({
  nightfox = {
    syntax = {
      keyword = "magenta"
    }
  }
})
override.groups({
  all = {
    IncSearch = { bg = "palette.cyan" },
  },
})

Overrides for palettes and specs are defined per style. The purpose of overriding these components is to change colors. Colors are only relevant to a specific style. Groups on the other hand are not defined per style. These mainly use the color defined in the palette and spec objects in order to set values using templates.

Setup

The setup function is a convince wrapper for the above components. It takes each component as seperate keys and calls the correct init/override function.

local options = {
  dim_inactive = true,
}
local palettes = {
  nightfox = {
    red = "#c94f6d",
  },
  nordfox = {
    comment = "#60728a",
  },
}
local specs = {
  nightfox = {
    syntax = {
      keyword = "magenta"
    }
  }
}
local groups = {
  all = {
    IncSearch = { bg = "palette.cyan" },
  },
}
require('nightfox').setup({
  options = options,
  palettes = palettes,
  specs = specs,
  groups = groups,
})

Templates

Templates allow for referencing of other lower level objects in nightfox's config. For example instead of setting an absolute color value, you can refer to a lower object's value instead. The base of nightfox is a palette. A palette does not use a template as it is the base that others built off of. Palettes are used as the template source for spec objects. Specs objects are used as template source for group objects.

If a value does not start with # symbol it will be treated as the template path. Everything in lua is a table. This means that palettes and specs are just lua tables. A template path is the keys to index into the table separated by . characters.

Note: If the resulting value of a template is a [shade] then the base value will be used.

Example:

-- Specs use palettes as the template source
local specs = {
  nightfox = {
    syntax = {
      -- Value does not start with `#` so is treated as a template.
      -- Since `magenta` is a `shade` object the `base` value will be used.
      keyword = "magenta",

      -- Adding either `.bright` or `.dim` will change the value
      conditional = "magenta.bright",
      number = "orange.dim",
    },
    git = {
      -- A color define can also be used
      changed = "#f4a261",
    }
  }
}

-- Groups use specs as the template source
local groups = {
  all = {
    -- The template path is parsed to [`syntax`, `string`]. This is like calling into a lua table like:
    -- `spec.syntax.string`.
    String = { fg = "syntax.string" },

    -- If `link` is defined it will be applied over any other values defined
    Whitespace = { link = "Comment" }

    -- Specs are used for the template. Specs have their palette's as a field that can be accessed
    IncSearch = { bg = "palette.cyan" },
  },
}

require('nightfox').setup({ specs = specs, groups = groups })

Option

options.compile_path {path}

The output directory {path} where the compiled results will be written to. Default: vim.fn.stdpath("cache")/nightfox.

options.compile_file_suffix {suffix}

The string appended to the compiled file. Each style outputs to its own file. These files will append the {suffix} to the end of the file. Default: _compiled

options.transparent {bool}

A boolean value that if set will disable setting the background of Normal, NormalNC and other highlight groups. This lets you use the colors of the colorscheme but use the background of your terminal. Default: false.

options.terminal_colors {bool}

A boolean value that if set will define the terminal colors for the builtin terminal (vim.g.terminalcolor*). Default: true.

options.dim_inactive {bool}

A boolean value that if set will set the background of Non current windows to be darker. See :h hl-NormalNC.

options.module_default {bool}

The default value of a module that has not been overridden in the modules table.

options.styles {table}

styles is a table that contains a list of syntax components and their corresponding style. These styles can be any combination of |highlight-args|. The list of syntax components are:

comments
conditionals
constants
functions
keywords
numbers
operators
preprocs
strings
types
variables

Example:

local options = {
  styles = {
    comments = "italic",
    functions = "italic,bold",
  }
}

options.inverse {table}

inverse is a table that contains a list of highlight types. If a highlight type is enabled it will inverse the foreground and background colors instead of applying the normal highlight group. Thees highlight types are: match_paren, visual, search. For an example if search is enabled instead of highlighting a search term with the default search color it will inverse the foreground and background colors.

options.colorblind {table}

colorblind stores configuration information for nightfox's color vision deficiency (cdv) mode. This contains the following table:

colorblind = {
  enable = false,        -- Enable colorblind support
  simulate_only = false, -- Only show simulated colorblind colors and not diff shifted
  severity = {
    protan = 0,          -- Severity [0,1] for protan (red)
    deutan = 0,          -- Severity [0,1] for deutan (green)
    tritan = 0,          -- Severity [0,1] for tritan (blue)
  },
},

options.modules {table}

modules store configuration information for various plugins and other neovim modules. A module can either be a boolean or a table that contains additional configuration for that module. If the value is a table it also has a field called enable that will tell nightfox to load it. See modules for more information.

By default modules will be enabled. To change this behaviour change options.module_default to false.

Shade

A shade is a way to group a base color with a bright and dim version. This is the base struct/object that palette colors will be defined from. For example:

local Shade = require("nightfox.lib.shade")
local red = Shade.new("#bf616a", "#d06f79", "#a54e56"),
print(vim.inspect(red))
-- {
--   base = "#bf616a",
--   bright = "#d06f79",
--   dim = "#a54e56",
-- }

This is just a convience structure for building palette for nightfox and should not be used outside of it. This is noted here to help understand the structure of a palette.

Palette

A palette is the base color definitions of a style. Each style defines its own palette to be used by the other components. A palette defines base colors, as well as foreground and background shades. Along with the foreground and background colors a palette also defines other colors such as selection and comment colors.

The base colors are [shade] objects that define a base, bright, and dim color. These base colors are: black, red, green, yellow, blue, magenta, cyan, white, orange, pink.

Key	Description
black	Shade Color (Base, Bright, Dim)
red	Shade Color (Base, Bright, Dim)
green	Shade Color (Base, Bright, Dim)
yellow	Shade Color (Base, Bright, Dim)
blue	Shade Color (Base, Bright, Dim)
magenta	Shade Color (Base, Bright, Dim)
cyan	Shade Color (Base, Bright, Dim)
white	Shade Color (Base, Bright, Dim)
orange	Shade Color (Base, Bright, Dim)
pink	Shade Color (Base, Bright, Dim)
comment	Comment color
bg0	Darker bg (status line and float)
bg1	Default bg
bg2	Lighter bg (colorcolumn folds)
bg3	Lighter bg (cursor line)
bg4	Lighter bg (Conceal, border fg)
fg0	Lighter fg
fg1	Default fg
fg2	Darker fg (status line)
fg3	Darker fg (line numbers, fold columns)
sel0	Popup bg, visual selection bg
sel1	Popup sel bg, search bg

Spec

A spec or specification is a mapping of a palette values to a logical group that is used by the group.

The base of a spec is a re-export of the palette's fg bg and sel. The values that are re-exported are: bg0, bg1, bg2, bg3, bg4, fg0, fg1, fg2, fg3, sel0, sel1.

spec.syntax

The syntax table maps palette color values to syntax values to be used by the group.

Key	Description
bracket	Brackets and Punctuation
builtin0	Builtin variable
builtin1	Builtin type
builtin2	Builtin const
comment	Comment
conditional	Conditional and loop
const	Constants, imports and booleans
dep	Deprecated
field	Field
func	Functions and Titles
ident	Identifiers
keyword	Keywords
number	Numbers
operator	Operators
preproc	PreProc
regex	Regex
statement	Statements
string	Strings
type	Types
variable	Variables

spec.diag

The diag table maps palette colors to vim diagnostic colors values. These values are: error, warn, info, hint, and ok.

spec.diag_bg

The diag_bg table maps palette colors to vim diagnostic background colors. These values are: error, warn, info, hint, and ok.

spec.diff

The diff table maps palette colors to vimdiff highlight colors. These values are: add, delete, change and text.

spec.git

The git table maps palette colors to git colors. These values are: add, removed, changed, conflict, and ignored.

Group

A group is the definition of a highlight-group. The key of the group table is the highlight-group that will be defined, and the table value is the arguments to the |:highlight| command.

Key	Help	Description
fg	\|highlight-guifg\|	The color value of the foreground of the highlight group
bg	\|highlight-guibg\|	The color value of the background of the highlight group
sp	\|highlight-guisp\|	The color for underlines and undercurls
style	\|highlight-gui\|	The style of the highlight group. Ex `italic`, `bold`, etc
link	\|highlight-link\|	Link one `highlight-group` to another

If the value of link is present and is not empty, nightfox will link the group to the corresponding value.

Modules

Modules are a way to adding extra information for various plugins or features. This also allows them to be enabled or disabled. There are two types of modules, base modules and extended modules. A base modules do not have any other information and are just a boolean denoting if it is enabled. An extended module is a module that has extra customization information. It is a table that contains the additional configuration as well as a field called enable to determine if the module is applied.

Current list of modules are:

alpha
aerial
barbar
cmp
coc
dap-ui
dashboard
diagnostic
fern
fidget
gitgutter
gitsigns
glyph_palette
hop
illuminate
indent_blanklines
lazy.nvim
leap
lightspeed
lsp_saga
lsp_trouble
mini
modes
native_lsp
navic
neogit
neotest
neotree
notify
nvimtree
pounce
signify
sneak
symbol_outline
telescope
treesitter
tsrainbow
tsrainbow2
whichkey

Neovim specific modules

The following modules are enabled by default only when on neovim, diagnostic, native_lsp, treesitter. These modules are part of the core neovim experience and are liked to by other modules. This also means that they will still be enabled when setting module_default to false.

Extended modules

modules.coc

This module sets highlight groups from neoclide/coc.nvim.

key	type	default	description
enable	boolean	`true`	Enable the module to be included
background	boolean	`true`	Set virtual text background color

modules.diagnostic

This module sets highlight groups from vim.diagnostic.

key	type	default	description
enable	boolean	`true`	Enable the module to be included
background	boolean	`true`	Set virtual text background color

modules.native_lsp

This module sets highlight groups from neovim's builtin lsp.

key	type	default	description
enable	boolean	`true`	Enable the module to be included
background	boolean	`true`	Set virtual text background color

modules.leap

key	type	default	description
enable	boolean	`true`	Enable the module to be included
background	boolean	`true`	Sets the label color to the background
harsh	boolean	`false`	Sets label's contrast to be harsher

Color

Nightfox exposes a color utility library to help with manipulating colors. This library can be required using the following module:

local Color = require('nightfox.lib.color')

color.from_hex({hex})

Create a Color object from either a {hex} number or a css-style hex string ("#RRGGBB[AA]").

color.from_rgba({red}, {green}, {blue}, {alpha})

Create a Color object from a RGBA value. The {red}, {green} and {blue} components ranging from [0,255]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color.from_hsv({hue}, {sat}, {value}, {alpha})

Create a Color object from a HSV value. The {hue} is a float ranging [0,360]. {sat} and {value} are floats ranging from [0,100]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color.from_hsl({hue}, {sat}, {lightness}, {alpha})

Create a Color object from a HSL value. The {hue} is a float ranging [0,360]. {sat} and {lightness} are floats ranging from [0,100]. {alpha} is optional and defaults to 1. The {alpha} value's is from [0,1].

color:to_hex({with_alpha})

Convert a Color object to a integer number. If {with_alpha} is true the hex value will be returned with the alpha value added. This is defaulted to false.

color:to_css({with_alpha})

Convert a Color object to a css_style string ("#RRGGBB[AA]"). If {with_alpha} is true the hex value will be returned with the alpha value added. This is defaulted to false.

color:to_rgba()

Convert a Color object to a RGBA table. The resulting table will have red, green, blue and alpha components as keys of the table.

color:to_hsv()

Convert a Color object to a HSV table. The resulting table will have hue, saturation and value components as keys of the table.

color:to_hsl()

Convert a Color object to a HSL table. The resulting table will have hue, saturation and lightness components as keys of the table.

color:blend({other}, {factor})

Returns a new Color that is a linear blend between two colors. {other} is the other color to blend. {factor} is the percentage of the {other} color that will be blended. This percentage is represented [0,1] where 0 is no color blending and 1 is entirely the {other} color.

color:shade({factor})

Returns a new Color that has been shaded by the {factor}. The factor is a precentage from [-1,1] where -1 is black and 1 is white.

color:brighten({value})

Returns a new Color with {value} added to the value (hsv) of the current color. This returns a lighter version of of the current color if {value} is positive and a darker color is {value} is negative. {value} is Float [-100, 100].

color:lighten({value})

Returns a new Color with {value} added to the lightness (hsl) of the current color. This returns a lighter version of of the current color if {value} is positive and a darker color is {value} is negative. {value} is Float [-100, 100].

color:saturate({value})

Returns a new Color with {value} added to the saturation (hsv) of the current color. This returns either a more or less saturated version depending of +/- v. {value} is Float [-100, 100].

color:rotate({value})

Returns a new Color with {value} added to the hue (hsv) of the current color. The resulting value of hue will be wrapped from [0,360], meaning that if the value exceeds 360 it will be wrapped back to 0.

Colorblind

For individuals with color vision deficiency (cvd), nightfox has implemented a colorblind mode to help enhance color contrast. This can be enabled with this option colorblind.enable.

There are three types of color vision deficiency (cvd)

Cone	Type	Weak (trichromacy)	Missing (Dichromacy)
L / Red	Protan	Protanomaly	Protanopia
M / Green	Deutan	Deuteranomaly	Deuteranopia
S / Blue	Tritan	Tritanomaly	Tritanopia

The severity of protan, deutan, and tritan can be set individually. Severity is a value ranging from 0 to 1. where 1 is full dichromacy (missing cone type).

Example:

require("nightfox").setup({
  options = {
    colorblind = {
      enable = true,
      severity = {
        protan = 0.3,
        deutan = 0.6,
      },
    },
  },
})

Compile

Nightfox is a highly customizable and configurable colorscheme. This does however come at the cost of complexity and execution time.

Nightfox pre-computes the result of your configuration and saves the lua bytecode in a cache to be used on next load. This significantly speeds up nightfox's execution time. Changes to your configuration will be re-computed and cached automatically.

By default nightfox writes the compiled results into the system's cache directory. On unix this is $XDG_CACHE_HOME/nvim/nightfox and on windows this is %localappdata%\\Temp\\nvim\\nightfox.

Compile commands

compile()

Compile nightfox settings for each style and write compiled file to compile_path.

:NightfoxCompile

Compile nightfox settings for each style and write compiled file to compile_path.

Interactive

Nightfox makes it easy to make changes to its config and see the results. For this nightfox exposes the command:

NightfoxInteractive

This command will attach an autocmd to the current buffer that executes on BufferWritePost. The autocmd will clear nightfox's internal state and re-source it's config from the newly saved file. It will then reset the colorscheme.

There are a few things to note:

This requires executing luafile on the current file. Any syntax errors will throw errors.
If you are using packer and have nightfox's config in a config = function() end block, this will not work as packer would require to be re-compiled and the compiled file sourced.

:NightfoxInteractive

Enable Nightfox configuration reloading on buffer save.

Files

usage.md

Latest commit

History

usage.md

File metadata and controls

Overview

Usage

Configuration

Init

Overrides

Setup

Templates

Option

options.compile_path {path}

options.compile_file_suffix {suffix}

options.transparent {bool}

options.terminal_colors {bool}

options.dim_inactive {bool}

options.module_default {bool}

options.styles {table}

options.inverse {table}

options.colorblind {table}

options.modules {table}

Shade

Palette

Spec

spec.syntax

spec.diag

spec.diag_bg

spec.diff

spec.git

Group

Modules

Neovim specific modules

Extended modules

modules.coc

modules.diagnostic

modules.native_lsp

modules.leap

Color

color.from_hex({hex})

color.from_rgba({red}, {green}, {blue}, {alpha})

color.from_hsv({hue}, {sat}, {value}, {alpha})

color.from_hsl({hue}, {sat}, {lightness}, {alpha})

color:to_hex({with_alpha})

color:to_css({with_alpha})

color:to_rgba()

color:to_hsv()

color:to_hsl()

color:blend({other}, {factor})

color:shade({factor})

color:brighten({value})

color:lighten({value})

color:saturate({value})

color:rotate({value})

Colorblind

Compile

Compile commands

compile()

:NightfoxCompile

Interactive

:NightfoxInteractive