:icecream: Themes

[!NOTE] All bolds and italics in the screenshots below are completely customisable. Additional screenshots of more languages can be found here.

:sparkles: Features

• :envelope_with_arrow: Automatic caching for faster load times
• :evergreen_tree: Full Tree-sitter support and bespoke queries
• :tickets: Support for LSP semantic tokens
• :electric_plug: Support for many popular plugins
• :flashlight: Filetype highlighting to allow for greater customisation across different languages
• :memo: Override everything - styles, colors, tokens, highlight groups and filetype groups
• :paintbrush: Create custom highlight groups and even highlight groups by filetypes

:zap: Requirements

• Neovim 0.9.2+
• termguicolors enabled for true color support
• tree-sitter for full syntax highlighting
• For semantic tokens, an LSP server that supports them

:package: Installation and usage

Install with your package manager of choice:

-- Lazy
{
  "olimorris/onedarkpro.nvim",
  priority = 1000, -- Ensure it loads first
}

-- somewhere in your config:
vim.cmd("colorscheme onedark")

-- Packer
use "olimorris/onedarkpro.nvim"

-- somewhere in your config:
vim.cmd("colorscheme onedark")

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

" somewhere in your config:
colorscheme onedark

:rocket: Commands

The colorscheme comes with some useful commands:

• :OnedarkproCache force generate new cache files for the themes (you won't often need this)
• :OnedarkproClean removes existing cache files for the themes
• :OnedarkproColors output all of the current themes colors to a scratch buffer

The theme comes with the ability to export colors to Alacritty, Kitty, Foot, Wezterm, Rio, Windows Terminal and Zellij using the following commands:

• :OnedarkproExportToAlacritty
• :OnedarkproExportToFoot
• :OnedarkproExportToKitty
• :OnedarkproExportToWezterm
• :OnedarkproExportToWindowsTerminal
• :OnedarkproExportToRio
• :OnedarkproExportToZellij

The templates for these themes can be found in the extra folder.

:wrench: Configuration

Default configuration

[!NOTE] You only need to the call the setup function if you wish to change any of the defaults.

require("onedarkpro").setup({
  colors = {}, -- Override default colors or create your own
  highlights = {}, -- Override default highlight groups or create your own
  styles = { -- For example, to apply bold and italic, use "bold,italic"
    types = "NONE", -- Style that is applied to types
    methods = "NONE", -- Style that is applied to methods
    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
    parameters = "NONE", -- Style that is applied to parameters
    conditionals = "NONE", -- Style that is applied to conditionals
    virtual_text = "NONE", -- Style that is applied to virtual text
  },
  filetypes = { -- Override which filetype highlight groups are loaded
    c = true,
    comment = true,
    go = true,
    html = true,
    java = true,
    javascript = true,
    json = true,
    lua = true,
    markdown = true,
    php = true,
    python = true,
    ruby = true,
    rust = true,
    scss = true,
    toml = true,
    typescript = true,
    typescriptreact = true,
    vue = true,
    xml = true,
    yaml = true,
  },
  plugins = { -- Override which plugin highlight groups are loaded
    aerial = true,
    barbar = true,
    copilot = true,
    dashboard = true,
    flash_nvim = true,
    gitsigns = true,
    hop = true,
    indentline = true,
    leap = true,
    lsp_saga = true,
    lsp_semantic_tokens = true,
    marks = true,
    mini_indentscope = true,
    neotest = true,
    neo_tree = true,
    nvim_cmp = true,
    nvim_bqf = true,
    nvim_dap = true,
    nvim_dap_ui = true,
    nvim_hlslens = true,
    nvim_lsp = true,
    nvim_navic = true,
    nvim_notify = true,
    nvim_tree = true,
    nvim_ts_rainbow = true,
    op_nvim = true,
    packer = true,
    polygot = true,
    rainbow_delimiters = true,
    startify = true,
    telescope = true,
    toggleterm = true,
    treesitter = true,
    trouble = true,
    vim_ultest = true,
    which_key = true,
  },

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

Setting a theme

Currently, there are four themes in the colorscheme:

• onedark
• onelight
• onedark_vivid
• onedark_dark

A theme can be set with:

vim.cmd("colorscheme onedark")

Configuring 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:

require("onedarkpro").setup({
  colors = {
    red = "#FF0000"
  }
})

Specifying new colors

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

require("onedarkpro").setup({
  colors = {
    my_new_red = "#f44336",
    my_new_green = "require('onedarkpro.helpers').darken('green', 10, 'onedark')"
  }
})

[!NOTE] See the helpers section to understand how to use the color helpers.

These can then be used for custom highlight groups if desired:

require("onedarkpro").setup({
  highlights = {
    Error = {
      fg = "${my_new_red}",
      bg = "${my_new_green}"
    },
  }
})

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:

require("onedarkpro").setup({
  colors = {
    onedark = { bg = "#FFFF00" }, -- yellow
    onelight = { bg = "#00FF00" }, -- green
  }
})

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

require("onedarkpro").setup({
  colors = {
    dark = { bg = "#FFFF00" }, -- yellow
    light = { bg = "#00FF00" }, -- green
  }
})

Configuring highlight groups

The editor, syntax, filetype and plugin files use a large array of highlight groups. Some examples of how you can customize or override them:

1. Using specific hex colors and styles:

require("onedarkpro").setup({
  highlights = {
    Comment = { fg = "#FF0000", bg = "#FFFF00", italic = true }
  }
})

2. Referencing the name of colors:

require("onedarkpro").setup({
  highlights = {
    Comment = { fg = "${my_new_red}", bg = "${yellow}", italic = true }
  }
})

3. Linking to other highlight groups:

require("onedarkpro").setup({
  highlights = {
    Comment = { link = "Substitute" }
  }
})

4. Extending existing highlight groups:

require("onedarkpro").setup({
  highlights = {
    Comment = { underline = true, extend = true }
  }
})

[!NOTE] In the example above, an underline style has been applied to the existing Comment highlight group.

Creating highlight groups

You can also create your own highlight groups:

require("onedarkpro").setup({
  highlights = {
    MyNewHighlightGroup = { fg = "${red}" }
  }
})

or, if you'd like to disable certain highlight groups:

require("onedarkpro").setup({
  highlights = {
    ["@lsp.type.comment"] = {}
  }
})

[!NOTE] This can be useful to prevent LSP servers from applying semantic highlights

Specifying highlight attributes by theme or background

As with colors, highlight attributes may be specified by using the theme name or the background color. For example:

require("onedarkpro").setup({
  highlights = {
    Comment = {
      fg = { onedark = "${yellow}", onelight = "${my_new_red}" }
    }
  }
})

Alternatively, by background color:

require("onedarkpro").setup({
  highlights = {
    Comment = {
      fg = { dark = "${yellow}", light = "${my_new_red}" }
    }
  }
})

Namespacing highlight groups

Neovim supports the application of highlights to specific buffers via namespaces. To apply highlight groups to a specific namespace, use the ns_id key:

require("onedarkpro").setup({
  highlights = {
    Comment = { ns_id = 1, fg = "${light_gray}" }
  }
})

Configuring styles

[!NOTE] For a list of available styles, please refer to the Neovim documentation

Styles can be applied to highlight groups:

require("onedarkpro").setup({
  highlights = {
    Comment = { italic = true },
    Directory = { bold = true },
    ErrorMsg = { italic = true, bold = true }
  }
})

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 with minimal effort. These styles may be configured as shown in the example below:

require("onedarkpro").setup({
  styles = {
    types = "NONE",
    methods = "NONE",
    numbers = "NONE",
    strings = "NONE",
    comments = "italic",
    keywords = "bold,italic",
    constants = "NONE",
    functions = "italic",
    operators = "NONE",
    variables = "NONE",
    parameters = "NONE",
    conditionals = "italic",
    virtual_text = "NONE",
  }
})

Configuring filetype highlighting

[!NOTE] Please see the Contributing guide if you would like add support for new filetypes.

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

• comment
• go
• html
• java
• javascript
• json
• lua
• markdown
• php
• python
• ruby
• rust
• scss
• toml
• typescript
• typescriptreact
• vue
• xml
• yaml

Specific filetypes can be disabled as follows:

require("onedarkpro").setup({
  filetypes = {
    markdown = false,
    ruby = false,
  }
})

Alternatively, all of the filetypes can be disabled:

require("onedarkpro").setup({
  filetypes = {
    all = false
  }
})

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

require("onedarkpro").setup({
  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:

require("onedarkpro").setup({
  highlights = {
    ["@field.yaml"] = { fg = "${blue}", italic = true }
  }
})

In the example above, we have set the field tree-sitter 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 is being applied in Neovim, see the FAQ section.

Configuring LSP semantic tokens

[!NOTE] Semantic tokens are only available in Neovim 0.9+ and with selected LSP servers.

In Neovim, some LSP servers may send tokens to the editor to allow for more intelligent highlighting such as variable scope; a feature which is impossible with tree-sitter alone.

Semantic highlighting in Neovim sees highlight groups set which have a priority greater than those of tree-sitter and the base vim highlight groups (see :h lsp-semantic_tokens for more information). A full list of available semantic tokens can be found here.

The colorscheme has defined some semantic tokens (to match the Visual Studio Code theme as closely as possible) and applies them as part of the filetype highlighting. To determine what tokens are available to set or override, use the :Inspect command.

Finally, the colorscheme has defined some non-filetype tokens as a plugin, named lsp_semantic_tokens. See the section below for how to disable this.

Configuring plugins

[!NOTE] Please see the Contributing guide if you would like add support for new plugins.

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

require("onedarkpro").setup({
  plugins = {
    nvim_lsp = false,
    polygot = false,
    treesitter = false
  }
})

Alternatively, all of the plugins can be disabled:

require("onedarkpro").setup({
  plugins = {
    all = false
  }
})

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

require("onedarkpro").setup({
  plugins = {
    all = false,
    nvim_lsp = true,
    treesitter = true
  }
})

Configuring options

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:

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

Transparency

The theme supports transparent backgrounds:

require("onedarkpro").setup({
  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.

require("onedarkpro").setup({
  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:

require("onedarkpro").setup({
  options = {
    highlight_inactive_windows = true
  }
})

:rainbow: Helpers

The theme comes with a set of helpers which enable you to interact with and modify colors. The helper file can be accessed via require("onedarkpro.helpers").

Using colors from a theme

It can be useful to access a theme's colors for use within other plugins (such as your statusline) after its loaded. For this, the get_colors helper can be used:

local color = require("onedarkpro.helpers")

local colors = color.get_colors()
print(colors.purple) -- #c678dd (if using the Onedark theme)

Without specifying a theme name, the helper will get the colors for the currently loaded theme. Alternatively, specify a theme name, such as get_colors("onelight").

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.

[!NOTE] Please ensure that the colorscheme loads ahead of any plugins which may wish to use the theme's colors.

Using colors before a theme loads

Whilst the get_colors method is useful in most cases, it may be necessary to get a theme's colors before it has fully loaded. The common use case is for creating custom colors which are based on the theme's own palette and incorporating them back into the theme. For this, the get_preloaded_colors method can be used:

local color = require("onedarkpro.helpers")

local colors = color.get_preloaded_colors()
print(colors.purple) -- #c678dd (if using the Onedark theme)

[!NOTE] This will only output the theme's core color palette and not any generated colors.

Darken/Lighten/Brighten colors

The theme also contain helpers darken, lighten and brighten, to allow you to modify custom colors or the theme's own. All three helpers follow the same format and take three parameters:

• color (string) - The name of the color to load (if specifying a theme) or a hex value
• amount (number) - The amount to darken/lighten/brighten the color by (range from -100 to 100)
• theme (string) (optional) - The name of the theme to load a color from

To use this in practice:

local color = require("onedarkpro.helpers")

-- Load the red color from the onedark theme and lighten it by an amount of 7
print(color.lighten("red", 7, "onedark")) -- #e68991

Alternatively:

local color = require("onedarkpro.helpers")

-- Darken Red1 by an amount of 10
print(color.darken("#FF0000", 10)) -- #cc0000

A common use case is to modify colors and incorporate them into theme. There are a number of ways to accomplish this and the most efficient is to pass a function (as a string) to the colors table in the theme's configuration:

require("onedarkpro").setup({
  colors = {
    dark_red = "require('onedarkpro.helpers').darken('red', 10, 'onedark')",
  },
  highlights = {
    CustomRedHighlight = {
      fg = "${dark_red}",
    },
  }
})

This prevents the theme from trying to resolve the color before the whole of the configuration has been parsed. This also ensures that the startup time for the theme remains small.

:electric_plug: Supported Plugins

The theme supports the following plugins:

• aerial.nvim (aerial)
• barbar.nvim (barbar)
• Copilot.vim (copilot)
• Dashboard (dashboard)
• diffview.nvim (diffview)
• flash.nvim (flash.nvim)
• gitsigns.nvim (gitsigns)
• Hop.nvim (hop)
• Indent Blankline (indentline)
• leap.nvim (leap)
• lspsaga.nvim (lsp_saga)
• LSP Semantic tokens (lsp_semantic_tokens)
• marks.nvim (marks)
• mini.indentscope (mini_indentscope)
• 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 (nvim_lsp)
• nvim-navic (nvim_navic)
• nvim-notify (nvim_notify)
• nvim-tree (nvim_tree)
• nvim-ts-rainbow (nvim_ts_rainbow)
• nvim-ts-rainbow2 (nvim_ts_rainbow2)
• 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)

:gift: Extras

Lualine

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

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 == "dark" then
    vim.cmd("colorscheme onelight")
  else
    vim.cmd("colorscheme onedark")
  end
end

:question: FAQs

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

If you're using Neovim 0.9+, the :Inspect command is available.

If you're on an earlier version of Neovim and are using Tree-sitter, install Playground as this gives you access to the powerful :TSHighlightCapturesUnderCursor command. This shows any Tree-sitter or syntax highlight groups under the cursor.

I think the theme would look better if we changed the highlight group of X. Would you accept a PR?

As mentioned at the top of this readme, the theme is based on the One Dark Pro theme for Visual Studio Code. Where possible, I will always reconcile back to that. Unless something looks terrible or the readability can be signficantly improved, I'll nearly always default to what the original theme has done. Remember that you can apply your own customisations to the theme by configuring highlight groups.

Ok then, but I've noticed some differences between the theme and the original Visual Studio Code theme. Why is this?

I've tried to ensure that the theme resembles the original Visual Studio Code theme as much as possible. To that end we have carefully applied custom Tree-sitter queries to certain filetypes as well as mapped LSP semantic token colors. If you notice any differences, please raise a discussion with supporting screenshots.

:clap: Credits

The following colorschemes serve as inspiration:

• One Dark Pro - The inspiration for this colorscheme
• Catppuccin/nvim - For the genius idea of hashing and caching and pushing the envelope of Neovim colorschemes and the kind PRs
• Nightfox - For the original code structure
• GitHub nvim theme - For the logo inspiration