OneDarkPro.nvim

Highly customisable Neovim colorscheme. With support for custom colors, styles and highlights by filetype
Inspired by VS Code's One Dark Pro

onedark

onelight

onedark_vivid

onedark_dark

:book: Table of Contents

• Features
• Requirements
• Installation
• Usage
• Configuration
  • Default configuration
  • Configuring themes
  • Configuring colors
  • Configuring highlight groups
  • Configuring filetype highlighting
  • Configuring plugins
  • Configuring styles
  • Configuring options
  • Configuring caching
• Supported Plugins
• Screenshots
• Extras
• FAQs
• Credits

:sparkles: Features

• Override default styles, colors and highlight groups
• Create custom highlight groups and even highlight groups by filetypes
• Cache your configuration to improve startup times
• Treesitter support
• Support for many popular plugins

:zap: Requirements

• Neovim 0.5+ (0.8+ for filetype highlights)
• termguicolors enabled for true color support
• treesitter for full syntax highlighting

:package: Installation

Install with your package manager:

use "olimorris/onedarkpro.nvim"    -- Packer

Plug 'olimorris/onedarkpro.nvim'   " Vim-Plug

:rocket: Usage

Use the built-in :colorscheme command to load:

vim.cmd("colorscheme onedarkpro")  -- Lua

colorscheme onedarkpro             " Vimscript

Other useful commands:

• :OnedarkproCache generates a fresh cache file for the current colorscheme
• :OnedarkproClean will remove the cache file from disk for the current colorscheme
• :OnedarkproColors will output all of the colors in the current colorscheme to a scratch buffer

:wrench: Configuration

Default configuration

A call to the setup function is only required if you wish to change the default values listed below:

require("onedarkpro").setup({
  dark_theme = "onedark", -- The default dark theme
  light_theme = "onelight", -- The default light theme
  caching = false, -- Use caching for the theme?
  cache_path = vim.fn.expand(vim.fn.stdpath("cache") .. "/onedarkpro/"), -- The path to the cache directory
  colors = {}, -- Override default colors by specifying colors for 'onelight' or 'onedark' themes
  highlights = {}, -- Override default highlight and/or filetype groups
  filetypes = { -- Override which filetype highlight groups are loaded
    javascript = true,
    lua = true,
    markdown = true,
    php = true,
    python = true,
    ruby = true,
    rust = true,
    toml = true,
    yaml = true,
  },
  plugins = { -- Override which plugin highlight groups are loaded
    -- See the Supported Plugins section for a list of available plugins
  },
  styles = { -- Choose from "bold,italic,underline"
    types = "NONE", -- Style that is applied to types
    numbers = "NONE", -- Style that is applied to numbers
    strings = "NONE", -- Style that is applied to strings
    comments = "NONE", -- Style that is applied to comments
    keywords = "NONE", -- Style that is applied to keywords
    constants = "NONE", -- Style that is applied to constants
    functions = "NONE", -- Style that is applied to functions
    operators = "NONE", -- Style that is applied to operators
    variables = "NONE", -- Style that is applied to variables
    conditionals = "NONE", -- Style that is applied to conditionals
    virtual_text = "NONE", -- Style that is applied to virtual text
  },
  options = {
    bold = true, -- Use bold styles?
    italic = true, -- Use italic styles?
    underline = true, -- Use underline styles?
    undercurl = true, -- Use undercurl styles?

    cursorline = false, -- Use cursorline highlighting?
    transparency = false, -- Use a transparent background?
    terminal_colors = false, -- Use the theme's colors for Neovim's :terminal?
    window_unfocused_color = false, -- When the window is out of focus, change the normal background?
  }
})

Note: You only need to include values that you wish to change from the defaults!

Configuring themes

Currently, there are four themes available:

• onedark
• onelight
• onedark_vivid
• onedark_dark

A default theme can be set with:

theme = "onedark_vivid",

If no value is specified, the colorscheme will use the value of the dark_theme and/or light_theme config option; with vim.o.background being used to determine whether to use the dark or light theme:

dark_theme = "onedark_dark",
light_theme = "onelight",

For users who wish to have a light theme during daylight hours and a dark theme during the night, it is recommended to not set a value for theme and instead use the dark_theme and light_theme options.

Configuring colors

The colorscheme has a palette of 13 core colors alongside many additional ones which are used for menus and git diffs. These colors can be found in the themes.

The default colors can be changed by specifying the name of the color and a new hex code:

colors = {
  red = "#FF0000"
}

Specifying new colors

New colors may be created which will then be merged into a theme's color palette:

colors = {
  my_new_red = "#f44336"
}

Note: Custom colors can also be referenced when creating custom highlight group overrides

Specifying colors by theme

It's possible to override default colors within a theme such as the bg color. This is a common question for those who wish to have a darker background than the default. Of course it would make sense to have different bg colors for the onedark and onelight themes. This can be achieved by specifying the theme name as a table, followed by the color:

colors = {
  onedark = {
    bg = "#FFFF00" -- yellow
  },
  onelight = {
    bg = "#00FF00" -- green
  }
}

Configuring highlight groups

The editor, syntax, filetype and plugin files use a large array of highlight groups. There are three ways to customize or override them:

1. Using specific hex colors:

highlights = {
  Comment = { fg = "#FF0000", bg = "#FFFF00" }
}

2. Referencing the name of colors:

highlights = {
  Comment = { fg = "${my_new_red}" bg = "${yellow}" }
}

3. Linking to other highlight groups:

highlights = {
  Comment = { link = "Substitute" }
}

Configuring filetype highlighting

Note: Filetype highlighting only works in Neovim 0.8 and above

The colorscheme supports opinionated highlighting for filetypes, just like the original VS Code theme. By default, all of the filetypes supported are loaded at runtime. The colorscheme currently has support for:

• javascript
• lua
• markdown
• php
• python
• ruby
• rust
• toml
• yaml

Please see the Contributing guide if you would like add support for new filetypes.

Specific filetypes can be disabled as follows:

filetypes = {
  markdown = false,
  ruby = false,
}

Alternatively, all of the filetypes can be disabled:

filetypes = {
  all = false
}

Or, all of the filetypes can be disabled with a select few enabled:

filetypes = {
  all = false
  markdown = true
  ruby = true,
}

Adding or modifying filetype highlights

It's likely that you'll wish to add additional filetype highlights or even change the defaults. This can be achieved by adding them as custom highlight groups in the colorscheme:

highlights = {
  ["@field.yaml"] = { fg = "${blue}", style = "italic" }
}

In the example above, we have set the field treesitter highlight group to be blue, but only when the filetype is yaml. More information can be found via :h treesitter-highlight-groups.

To determine which highlight group to add or modify, see the FAQ section for instructions on using Treesitter Playground.

Note: The colorscheme's defaults can be found in the /lua/onedarkpro/highlights/filetypes directory

Configuring plugins

By default, all of the plugins supported by the theme are loaded at runtime. Specific plugins can be disabled as follows:

plugins = {
  native_lsp = false,
  polygot = false,
  treesitter = false
}

Alternatively, all of the plugins can be disabled:

plugins = {
  all = false
}

Or, all of the plugins can be disabled with a select few enabled:

plugins = {
  all = false
  native_lsp = true,
  treesitter = true
}

Note: For a full list of plugins supported, and their names, see the plugins section

Configuring styles

Within the colorscheme, collections of highlight groups have been grouped together into styles. For users who use monospaced fonts with nice italics, this can go someway to enhancing the aesthetic of the colorscheme. These styles may be configured as shown in the example below:

styles = {
  types = "NONE",
  numbers = "NONE",
  strings = "NONE",
  comments = "italic",
  keywords = "bold,italc",
  constants = "NONE",
  functions = "italic",
  operators = "NONE",
  variables = "NONE",
  conditionals = "italic",
  virtual_text = "NONE",
}

Note: See the Neovim help for a full list of styles

Configuring options

Formatting

Alongside styles, the colorscheme enables additional formatting options; often used in combination with filetype highlighting. These can be turned on or off:

options = {
  bold = true,
  italic = false,
  underline = false,
  undercurl = true
}

Transparency

The colorscheme supports transparent backgrounds:

options = {
  transparency = true
}

By setting the transparency option to true, the Normal, Folded, SignColumn, Statusline and Tabline groups will have NONE as the background color. Additional transparency may be achieved by overriding more highlight groups.

Terminal Colors

The colorscheme supports changing the colors for Neovim's :terminal to the current theme:

options = {
  terminal_colors = true
}

Window Focus Color

The colorscheme supports changing the color of the main window in Neovim when the focus is lost. For example, when a telescope or packer pop up appears:

options = {
  window_unfocused_color = true
}

Note: This can be seen in the screenshots above where nvim-tree is opened and out of focus

Cursorline

Cursorline highlighting is supported in the colorscheme using a cursorline color (which may of course be overridden). This can be enabled with the following:

colors = {
  cursorline = "#FF0000" -- This is optional. The default cursorline color is based on the background
},
options = {
  cursorline = true
}

Configuring caching

To enable a faster load time, the colorscheme supports caching. This works by caching highlight groups to disk instead of processing them when Neovim starts. Initial testing suggests you may see a 3x improvement in the colorscheme's boot time if you have a complex configuration.

Note that with caching enabled, if you change your theme config (e.g., custom highlights), you must reload your updated config and then regenerate the cache before your change will take effect.

To enable caching:

require("onedarkpro").setup({
  caching = true
})

Note: The default path to the cache is ~/.cache/nvim/onedarkpro/. This can be changed with the cache_path config variable

Generating a cache

A cache can be generated by running :OnedarkproCache. The colorscheme will then detect if a cache is present when Neovim starts.

Note: The cache will be automatically generated if caching = true and no cache file is present; but it will not regenerate automatically

To automatically re-generate the cache, an autocommand unique to your configuration should be used.

Cleaning a cache

A cache may be cleaned by running :OnedarkproClean. This will remove the cache file from disk.

:electric_plug: Supported Plugins

The colorscheme supports the following plugins:

• aerial.nvim (aerial)
• barbar.nvim (barbar)
• Copilot.vim (copilot)
• Dashboard (dashboard)
• gitsigns.nvim (gitsigns)
• Hop.nvim (hop)
• Indent Blankline (indentline)
• leap.nvim
• lspsaga.nvim (lsp_saga)
• marks.nvim (marks)
• Neotest (neotest)
• neo-tree (neo_tree)
• nvim-cmp (nvim_cmp)
• nvim-dap (nvim_dap)
• nvim-dap-ui (nvim_dap_ui)
• nvim-hlslens (nvim_hlslens)
• nvim-lspconfig (native_lsp)
• nvim-navic (nvim_navic)
• nvim-notify (nvim_notify)
• nvim-tree (nvim_tree)
• nvim-ts-rainbow (nvim_ts_rainbow)
• op.nvim (op_nvim)
• packer.nvim (packer)
• polygot (polygot)
• startify (startify)
• telescope.nvim (telescope)
• toggleterm.nvim (toggleterm)
• Treesitter (treesitter)
• Trouble (trouble)
• Vim Ultest (vim_ultest)
• Which Key (which_key)

:camera_flash: Screenshots

Lua

Python

Javascript/React

Ruby

:gift: Extras

Lualine

The colorscheme has Lualine support out of the box for all of its themes. This can be found in the Lualine folder.

Terminal themes

The colorscheme comes with Alacritty and Kitty themes. These can be found in the extras folder.

Helpers

Theme color tables

To enable the theme's colors to be extracted and used elsewhere in the Neovim config, a helper function, get_colors(), has been included. This returns a table of the theme's current colors.

local colors = require("onedarkpro").get_colors(vim.g.onedarkpro_theme)
print(colors.purple) -- #9a77cf

Note: The global variable vim.g.onedarkpro_theme represents the currently loaded theme

You can also use the command :OnedarkproColors to open a scratch buffer with the colors from the currently loaded theme. This then allows a colorizer plugin to highlight the colors.

Toggling between themes

To enable the easy switching between dark and light themes, the following helper function could be used:

function ToggleTheme()
  if vim.o.background == "dark" then
    vim.o.background = "light"
  else
    vim.o.background = "dark"
  end
end

Configuring styles/colors/highlight groups based on the theme

When configuring the colorscheme, it may be useful to apply different colors or styles depending on whether onedark or onelight is active. This can be achieved by applying a conditional in the configuration:

highlights = {
  TSField = {
    fg = (vim.o.background == "dark" and "${red}" or "${green}")
  }
}

:question: FAQs

I want to change X highlight group but I don't know what it is. How do I find out?

If you're using Treesitter then install Playground as this gives you access to the powerful :TSHighlightCapturesUnderCursor command. This shows any treesitter or syntax highlight groups under the cursor.

I want to automatically generate the cache file. How do I do it?

This can be achieved by creating a ColorScheme autocommand that runs the :OnedarkproCache command. The author uses this to automatically generate a new cache file when a new theme is toggled.

:clap: Credits

Contributors

Thanks to the following contributors for their work on the colorscheme:

• mmirus - contributions
• mrjones2014 - contributions

Inspiration

The following colorschemes were used as an inspiration:

• One Dark Pro - The inspiration for this colorscheme
• Nightfox - For the beautiful code base and structure
• GitHub nvim theme - For the logo inspiration