Skip to content
AstroNvim Documentation

Custom Colorscheme/Theme

This page goes over how to install and configure a custom color scheme or theme in your AstroNvim configuration. By default AstroNvim ships with it’s own custom color scheme, AstroTheme, but there are many others to choose from to fit your needs. When choosing a colorscheme/theme, make sure to check what plugins they support and compare that with the list of Plugins used in AstroNvim. Not every plugin requires custom highlights, but having good support for common plugins helps unify the user interface and keep things looking nice.

Using a Custom Colorscheme

  1. Add the colorscheme plugin

    You can either add a colorscheme plugin directly to your plugins as described in the Customizing Plugins Page, for example if you wanted to add Catppuccin you would add the following to your plugins:

    lua/plugins/catppuccin.lua
    return {
      "catppuccin/nvim",
      name = "catppuccin",
      opts = {
        -- configuration options...
      },
    }

    Or you can install it using AstroCommunity. Navigate to the folder listing the available community colorscheme plugins and pick a colorscheme that you would like to install. Then make sure you have add the AstroCommunity repository to your plugins and then insert the necessary import statement as described in the AstroCommunity documentation. For example to add Catppuccin, you would add the following to your plugins:

    lua/plugins/astrocommunity.lua
    return {
      "AstroNvim/astrocommunity",
      { import = "astrocommunity.colorscheme.catppuccin" },
    }

  2. Configure AstroUI to set the colorscheme

    The default colorscheme for AstroNvim can be configured through the AstroUI plugin with the colorscheme option. This can be added to your user configuration’s plugins:

    lua/plugins/astroui.lua
    return {
      "AstroNvim/astroui",
      ---@type AstroUIOpts
      opts = {
        colorscheme = "astrodark",
      },
    }

    Then change it to the name of the theme you’ve installed in the step 1:

    lua/plugins/astroui.lua
    return {
      "AstroNvim/astroui",
      ---@type AstroUIOpts
      opts = {
        colorscheme = "catppuccin",
      },
    }

Using a Custom Colorscheme Configured with Global Variables

Some colorscheme plugins are configured through global variables rather than Lua functions like setup() so they require a slightly different setup to get them working correctly. For example if we want to use Sonokai:

lua/plugins/sonokai.lua
return {
  {
    "AstroNvim/astroui",
    ---@type AstroUIOpts
    opts = {
      colorscheme = "sonokai",
    },
  },
  {
    "sainnhe/sonokai",
    init = function() -- init function runs before the plugin is loaded
      vim.g.sonokai_style = "shusia"
    end,
  },
}