Configuration [Basic]

Configuration management for coc.nvim including JSON-based settings, directory locations, and programmatic configuration.

Table of Contents

• Common Tasks
• Commands
• Configuration Functions
• Global Variables
• Utility Functions
• Configuration File Structure
• Common Settings
• Examples
• Error Handling
• Troubleshooting
• See Also

Common Tasks

Open Settings File

:CocConfig

Opens user configuration in default editor.

Set Configuration Value

call coc#config('suggest.noselect', v:true)

Programmatically modify settings.

Get Configuration Value

let timeout = coc#util#get_config('suggest.timeout')

Read current configuration.

Find Config Directories

echo coc#util#get_config_home()  " Config directory
echo coc#util#get_data_home()    " Data directory

Commands

:CocConfig

:CocConfig

Open the user configuration file (coc-settings.json) in a new buffer. Located at ~/.config/nvim/coc-settings.json by default. Creates file if missing.

Example:

:CocConfig

" Or map to a key
nnoremap <silent> <leader>cc :CocConfig<CR>

:CocLocalConfig

:CocLocalConfig

Open workspace-local configuration file (.vim/coc-settings.json relative to workspace root). Workspace settings override user settings.

Example:

:CocLocalConfig

" Create workspace-specific settings

Configuration Functions

coc#config()

coc#config(section, value)

Programmatically set a configuration value. This modifies in-memory configuration without changing the JSON file.

Parameters:

• section: Configuration section path (dot-separated, e.g., 'suggest.noselect')
• value: Value to set (string, number, boolean, list, or dict)

Example:

" Disable auto-select in completion
call coc#config('suggest.noselect', v:true)

" Set completion timeout
call coc#config('suggest.timeout', 5000)

" Configure language server
call coc#config('languageserver.go', {
  \ 'command': 'gopls',
  \ 'rootPatterns': ['go.mod', '.git'],
  \ 'filetypes': ['go']
  \ })

coc#util#get_config()

coc#util#get_config(key)
" Returns: any

Get a configuration value.

Parameters:

• key: Configuration key (dot-separated path)

Returns: The configuration value, or v:null if not set.

Example:

let timeout = coc#util#get_config('suggest.timeout')
echo 'Completion timeout: ' . timeout

if coc#util#get_config('diagnostic.enable')
  echo 'Diagnostics are enabled'
endif

Global Variables

g:coc_user_config

let g:coc_user_config = {}

Dictionary of configuration overrides applied on top of coc-settings.json. Useful for setting configuration in vimrc before coc.nvim loads.

Type: Dictionary Default: {}

Example:

let g:coc_user_config = {
  \ 'suggest.noselect': v:true,
  \ 'diagnostic.errorSign': '✗',
  \ 'diagnostic.warningSign': '⚠',
  \ 'coc.preferences.formatOnSaveFiletypes': ['javascript', 'typescript']
  \ }

g:coc_config_home

let g:coc_config_home = '/path/to/config'

Override the configuration directory location. By default, coc.nvim uses the Neovim/Vim config directory.

Type: String Default: Auto-detected (~/.config/nvim for Neovim, ~/.vim for Vim)

Example:

" Use a custom config directory
let g:coc_config_home = expand('~/.config/coc')

g:coc_data_home

let g:coc_data_home = '/path/to/data'

Override the data directory location where extensions and state are stored.

Type: String Default: Auto-detected platform-specific location

Example:

" Use a custom data directory
let g:coc_data_home = expand('~/coc-data')

g:coc_filetype_map

let g:coc_filetype_map = {}

Map Vim filetypes to language identifiers used by language servers.

Type: Dictionary Default: {}

Example:

let g:coc_filetype_map = {
  \ 'yaml.ansible': 'ansible',
  \ 'javascript.jsx': 'javascriptreact',
  \ 'typescript.tsx': 'typescriptreact'
  \ }

g:coc_uri_prefix_replace_patterns

let g:coc_uri_prefix_replace_patterns = {}

Dictionary of URI prefix replacement patterns. Used to transform file URIs, useful for remote development or custom file schemes.

Type: Dictionary Default: {}

Example:

" Replace remote URIs with local paths
let g:coc_uri_prefix_replace_patterns = {
  \ 'file:///remote/': 'file:///local/'
  \ }

Utility Functions

coc#util#get_config_home()

coc#util#get_config_home()
" Returns: string

Get the coc.nvim configuration directory path.

Returns: Absolute path to config directory (e.g., ~/.config/nvim or ~/.vim).

Example:

let config_dir = coc#util#get_config_home()
echo 'Config directory: ' . config_dir

coc#util#get_data_home()

coc#util#get_data_home()
" Returns: string

Get the coc.nvim data directory path where extensions and data are stored.

Returns: Absolute path to data directory (e.g., ~/.config/coc or ~/.local/share/coc).

Example:

let data_dir = coc#util#get_data_home()
echo 'Data directory: ' . data_dir

coc#util#extension_root()

coc#util#extension_root()
" Returns: string

Get the directory where coc.nvim extensions are installed.

Returns: Absolute path to extensions directory (typically {data_home}/extensions).

Example:

let ext_dir = coc#util#extension_root()
echo 'Extensions installed at: ' . ext_dir

Configuration File Structure

The coc-settings.json file uses JSON format with schema validation. Here's an example configuration:

{
  "suggest.noselect": true,
  "suggest.enablePreselect": false,
  "suggest.timeout": 5000,
  "suggest.maxCompleteItemCount": 20,

  "diagnostic.errorSign": "✗",
  "diagnostic.warningSign": "⚠",
  "diagnostic.infoSign": "ℹ",
  "diagnostic.hintSign": "➤",

  "coc.preferences.formatOnSaveFiletypes": [
    "javascript",
    "typescript",
    "json"
  ],

  "languageserver": {
    "go": {
      "command": "gopls",
      "rootPatterns": ["go.mod", ".git"],
      "filetypes": ["go"]
    }
  }
}

Common Settings

Completion (suggest)

• suggest.noselect: Don't auto-select first item (default: false)
• suggest.enablePreselect: Enable preselect from language server (default: true)
• suggest.timeout: Completion timeout in milliseconds (default: 5000)
• suggest.maxCompleteItemCount: Maximum completion items (default: 50)
• suggest.snippetIndicator: Snippet indicator text (default: "~")

Diagnostics (diagnostic)

• diagnostic.errorSign: Error sign text (default: ">>")
• diagnostic.warningSign: Warning sign text (default: ">>")
• diagnostic.infoSign: Info sign text (default: ">>")
• diagnostic.hintSign: Hint sign text (default: ">>")
• diagnostic.virtualText: Enable virtual text (default: false)
• diagnostic.virtualTextCurrentLineOnly: Show virtual text only on current line (default: true)

Formatting

• coc.preferences.formatOnSaveFiletypes: Filetypes to format on save (default: [])
• coc.preferences.formatOnType: Enable format on type (default: false)

Lists

• list.source.files.command: Command for files list (default: varies by platform)
• list.source.files.args: Arguments for files command (default: [])
• list.indicator: List indicator character (default: ">")

Examples

Open Configuration

" Open user config
:CocConfig

" Open workspace config
:CocLocalConfig

" Open config with custom command
nnoremap <silent> <leader>cc :CocConfig<CR>

Programmatic Configuration

" Set configuration values in vimrc
function! s:ConfigureCoc() abort
  " Completion settings
  call coc#config('suggest.noselect', v:true)
  call coc#config('suggest.enablePreselect', v:false)
  call coc#config('suggest.timeout', 3000)

  " Diagnostic signs
  call coc#config('diagnostic.errorSign', '✗')
  call coc#config('diagnostic.warningSign', '⚠')
  call coc#config('diagnostic.infoSign', 'ℹ')
  call coc#config('diagnostic.hintSign', '➤')

  " Enable virtual text
  call coc#config('diagnostic.virtualText', v:true)
  call coc#config('diagnostic.virtualTextCurrentLineOnly', v:true)

  " Format on save
  call coc#config('coc.preferences.formatOnSaveFiletypes', [
    \ 'javascript',
    \ 'typescript',
    \ 'json'
  \ ])
endfunction

autocmd User CocNvimInit call s:ConfigureCoc()

Custom Language Server

" Configure a custom language server via vimrc
let g:coc_user_config = {
  \ 'languageserver': {
  \   'lua': {
  \     'command': 'lua-language-server',
  \     'filetypes': ['lua'],
  \     'rootPatterns': ['.git', '.luarc.json'],
  \     'settings': {
  \       'Lua': {
  \         'diagnostics': {
  \           'globals': ['vim']
  \         }
  \       }
  \     }
  \   }
  \ }
  \ }

Query Configuration

" Check configuration values
function! ShowCocConfig() abort
  echo 'Config home: ' . coc#util#get_config_home()
  echo 'Data home: ' . coc#util#get_data_home()
  echo 'Extensions: ' . coc#util#extension_root()
  echo 'Timeout: ' . coc#util#get_config('suggest.timeout')
endfunction

command! ShowCocConfig call ShowCocConfig()

Per-Project Configuration

" Auto-load project-specific settings
function! s:LoadProjectConfig() abort
  let config_file = getcwd() . '/.vim/coc-settings.json'
  if filereadable(config_file)
    echom 'Loading project config: ' . config_file
  endif
endfunction

autocmd DirChanged * call s:LoadProjectConfig()

Filetype-Specific Root Patterns

" Set custom root patterns per filetype
autocmd FileType rust let b:coc_root_patterns = ['Cargo.toml', '.git']
autocmd FileType go let b:coc_root_patterns = ['go.mod', '.git']
autocmd FileType javascript,typescript let b:coc_root_patterns = ['package.json', 'tsconfig.json', '.git']

Configuration Backup

" Backup configuration before editing
function! BackupCocConfig() abort
  let config = coc#util#get_config_home() . '/coc-settings.json'
  if filereadable(config)
    let backup = config . '.backup'
    call writefile(readfile(config), backup)
    echo 'Config backed up to: ' . backup
  endif
endfunction

command! CocConfigBackup call BackupCocConfig()

Error Handling

Invalid Configuration Values

If you set an invalid configuration value, coc.nvim will log an error. Check :CocOpenLog for details.

" This will fail - wrong type
call coc#config('suggest.timeout', 'not-a-number')

" Check logs
:CocOpenLog

Missing Configuration Files

If coc-settings.json doesn't exist, :CocConfig will create it automatically with an empty JSON object {}.

Schema Validation

Coc.nvim validates settings against a JSON schema. Invalid keys or value types will be reported in logs.

Troubleshooting

Configuration Not Taking Effect

Problem: Changed settings but no visible effect.

Solutions:

1. Restart coc.nvim: :CocRestart
2. Check if setting requires restart: Some settings only apply on startup
3. Verify JSON syntax: Use :CocConfig and check for syntax errors
4. Check priority: Workspace config overrides user config

Cannot Find Config File

Problem: :CocConfig opens empty buffer or wrong location.

Solutions:

1. Check config home: echo coc#util#get_config_home()
2. Set explicit path: let g:coc_config_home = '/path/to/config'
3. Create directory if missing: mkdir -p ~/.config/nvim

Settings Ignored

Problem: Settings in coc-settings.json are ignored.

Solutions:

1. Validate JSON: Use a JSON validator to check syntax
2. Check for typos: Setting names are case-sensitive
3. Review logs: :CocOpenLog shows validation errors
4. Test programmatically: Use coc#config() to confirm setting works

Conflicting Configurations

Problem: Unexpected behavior due to multiple config sources.

Solutions:

1. Check priority order: g:coc_user_config > workspace config > user config
2. Use :CocCommand workspace.showOutput to see effective config
3. Remove conflicting sources: Simplify to single config location

See Also

• Extensions - Installing and managing extensions
• Service Management - Starting and controlling the service
• Variables - All configuration variables
• Diagnostics - Diagnostic configuration options
• Completion - Completion configuration options