OneDarkPro.nvim

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

Onedark

Onelight

Onedark Vivid

Onedark Dark

📖 Table of Contents

• Features
• Requirements
• Installation
• Usage
• Configuration
  • Default configuration
  • Setting a theme
  • Overridng colors
  • Overriding highlight groups
  • Configuring filetype highlighting
  • Configuring plugins
  • Configuring styles
  • Configuring options
• Supported Plugins
• Screenshots
• Extras
• FAQs
• Credits

✨ Features

• Full Treesitter support
• Filetype highlighting to match the original VS Code theme
• Automatic caching for faster load times
• Support for many popular plugins
• Apply styles to types, keywords and function highlight groups
• Override everything! Default styles, colors, highlight groups and filetype groups
• Create custom highlight groups and even highlight groups by filetypes

⚡ Requirements

• Neovim 0.8 and above
• termguicolors enabled for true color support
• treesitter for full syntax highlighting

📦 Installation

Install with your package manager:

-- Packer
use "olimorris/onedarkpro.nvim"

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

🚀 Usage

Use the built-in :colorscheme command to load:

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

" Vimscript
colorscheme onedark

Additional commands:

• :OnedarkproCache generates new cache files for the themes
• :OnedarkproClean removes existing cache files for the themes
• :OnedarkproColors outputs all of the colors in the current theme to a scratch buffer

🔧 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({
  colors = {}, -- Override default colors or create your own
  highlights = {}, -- Override default highlight groups or create your own
  filetypes = { -- Override which filetype highlight groups are loaded
    -- See the 'Configuring filetype highlights' section for the available list
  },
  plugins = { -- Override which plugin highlight groups are loaded
    -- See the 'Supported plugins' section for the available list
  },
  styles = { -- For example, to apply bold and italic, use "bold,italic"
    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 = true, -- Use the theme's colors for Neovim's :terminal?
    highlight_inactive_windows = false, -- When the window is out of focus, change the normal background?
  }
})

vim.cmd("colorscheme onedark")

Setting a theme

Currently, there are four themes that come with the colorscheme:

• onedark
• onelight
• onedark_vivid
• onedark_dark

A theme can be set with:

vim.cmd("colorscheme onedark")

Overriding colors

A theme has a palette of 13 core colors alongside many additional ones which are used for menus and git diffs for example. 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"
}

Additional colors, based on a theme's default palette, may also be generated at runtime:

local color = require("onedarkpro.lib.color")

colors = {
  lighter_bg = color.lighten(onedarkpro.get_colors("onedark").bg, 0.85)
  darker_red = color.darken(onedarkpro.get_colors("onedark_vivid").red, 0.85)
}

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

Specifying colors by theme or background

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
  }
}

Alternatively, you can specify colors by the theme's background color:

colors = {
  dark = {
    bg = "#FFFF00" -- yellow
  },
  light = {
    bg = "#00FF00" -- green
  }
}

Overriding 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

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

• javascript
• lua
• markdown
• php
• python
• ruby
• rust
• toml
• typescript
• typescriptreact
• vue
• 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 theme:

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 theme'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 theme, 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 a theme. 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 theme 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 theme 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

By default, the colorscheme changes the colors for Neovim's :terminal to the current theme. This can be turned off if required.

options = {
  terminal_colors = false
}

Highlighting Inactive Windows

The theme 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 = {
  highlight_inactive_windows = 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 theme 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
}

🔌 Supported Plugins

The theme supports the following plugins:

• aerial.nvim (aerial)
• barbar.nvim (barbar)
• Copilot.vim (copilot)
• Dashboard (dashboard)
• gitsigns.nvim (gitsigns)
• Glance (glance)
• Hop.nvim (hop)
• Indent Blankline (indentline)
• leap.nvim (leap)
• lspsaga.nvim (lsp_saga)
• marks.nvim (marks)
• Neotest (neotest)
• neo-tree (neo_tree)
• nvim-cmp (nvim_cmp)
• nvim-bqf (nvim_bqf)
• 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)

📸 Screenshots

Lua

Python

Javascript/React

Ruby

🎁 Extras

Lualine

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

Terminal themes

The theme comes with Alacritty and Kitty colorschemes. These can be found in the extras folder.

Helpers

Using theme colors

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

local colors = require("onedarkpro").get_colors()
print(colors.purple) -- #c678dd

It is recommended that this is called after onedarkpro has been loaded. Using Packer, the after attribute can ensure the colorscheme is loaded before the plugin you're trying to configure.

If this is not possible, you can also explicitly get the colors for a specific theme:

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

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.

Lightening and darkening colors

When customising a theme, modifying a core color from the palette can help to ensure consistency. The theme allows for lightening and darkening of colors via the require("onedarkpro.lib.color") file and its lighten() and darken() methods:

local color = require("onedarkpro.lib.color")
print(color.darken("#FF0000", 0.5)) -- #800000
print(color.lighten("#FF0000", 0.5)) -- #FF8080

You can even include colors from the theme's core palette as a variable:

local color = require("onedarkpro.lib.color")
print(color.darken("${blue}", 0.9)) -- #579ED7

Note: If these methods are called before a theme is loaded, the colorscheme will use onedark colors. This can be solved by pairing this with the get_colors("theme_name") method

Toggling between themes

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

function ToggleTheme()
  if vim.o.background == "light" then
    vim.cmd("colorscheme onelight")
  else
    vim.cmd("colorscheme onedark")
  end
end

Configuring styles/colors/highlight groups based on the theme

When configuring the theme, 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}")
  }
}

❓ 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.

👏 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 initial structure of the code base
• GitHub nvim theme - For the logo inspiration