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

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" },
}
```
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:

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

Cache colorscheme

Some users may want to persist the last chosen colorscheme rather than always using the value set in their user configuration on startup. This can be easily implemented within your plugin configuration with the following code:

-- pick a location to cache colorscheme
local colorscheme_cache = vim.fs.joinpath(vim.fn.stdpath "state" --[[@as string]], "last_colorscheme")

--- Execute function with open file
---@param file string path to file to interact with
---@param mode openmode the mode in which to open the file
---@param callback fun(fd:file*) the callback to execute with the opened file
---@param on_error? fun(err:string) the callback to execute if unable to open the file
local function with_file(file, mode, callback, on_error)
  local fd, errmsg = io.open(file, mode)
  if fd then
    callback(fd)
    fd:close()
  elseif errmsg and on_error then
    on_error(errmsg)
  end
end

return {
  {
    "AstroNvim/astroui",
    --@param opts AstroUIOpts
    opts = function(_, opts)
      -- read colorscheme cache on open
      with_file(colorscheme_cache, "r", function(file)
        opts.colorscheme = file:read "*a"
      end)
    end,
  },
  {
    "AstroNvim/astrocore",
    ---@type AstroCoreOpts
    opts = {
      autocmds = {
        -- save colorscheme to cache on change
        cache_colorscheme = {
          {
            event = "ColorScheme",
            callback = function(args)
              if args.match then
                with_file(colorscheme_cache, "w+", function(file)
                  file:write(args.match)
                end)
              end
            end,
          },
        },
      },
    },
  },
}