or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/coc.nvim@0.0.x

docs

ui

float-windows.mdhighlights-colors.mdlist-interface.mdui-functions.mdwindow-management.md
index.md
tile.json

tessl/npm-coc-nvim

tessl install tessl/npm-coc-nvim@0.0.0

LSP based intellisense engine for neovim & vim8.

ui-functions.mddocs/ui/

UI Functions [Advanced]

Complexity: Advanced | Category: UI

Common Tasks: Run terminal commands | Display messages | Manage files | Update signs

Comprehensive UI utilities for terminal management, message display, file operations, and sign management in Vim/Neovim.

Table of Contents

  • Common Tasks
  • Terminal Management
  • Task Management
  • Message Display
  • Preview Window
  • File Management
  • URL Opening
  • iTerm Integration
  • Buffer Line Manipulation
  • Sign Management
  • Related Variables
  • Common Patterns
  • Error Handling
  • Troubleshooting
  • See Also

Common Tasks

Run Command in Terminal

call coc#ui#run_terminal({'cmd': 'npm test'}, function('s:OnComplete'))

Execute command and get result via callback.

Display Message

call coc#ui#echo_hover('Function: doSomething()')

Show message in hover highlight.

Open Files

let buffers = coc#ui#open_files(['file1.js', 'file2.js'])

Load multiple files into buffers.

Update Signs

let signs = [{'name': 'CocErrorSign', 'lnum': 5, 'priority': 10}]
call coc#ui#update_signs(bufnr('%'), 'coc-diagnostic', signs)

Terminal Management

coc#ui#open_terminal()

coc#ui#open_terminal(opts)
" Returns: number

Open terminal window with command.

Parameters:

  • opts: Dictionary with keys:
    • cmd: Command to run (required)
    • cwd: Working directory (default: getcwd())
    • position: 'bottom' or 'right' (default: 'bottom')
    • keepfocus: Keep focus on current window (default: 0)
    • autoclose: Close terminal on success (default: 1)
    • Callback: Function(status, bufnr, content) called on exit

Returns: Terminal buffer number

Example:

" Open terminal with build command
let bufnr = coc#ui#open_terminal({
  \ 'cmd': 'npm run build',
  \ 'cwd': getcwd(),
  \ 'Callback': {status, bufnr, content -> s:OnBuildComplete(status, content)}
  \ })

function! s:OnBuildComplete(status, content) abort
  if a:status == 0
    echo 'Build succeeded!'
  else
    echohl Error | echo 'Build failed' | echohl None
  endif
endfunction

coc#ui#run_terminal()

coc#ui#run_terminal(opts, cb)

Run command in terminal and return result via callback.

Parameters:

  • opts: Dictionary with cmd, cwd, keepfocus keys
  • cb: Callback function(err, result) where result has:
    • success: boolean
    • bufnr: terminal buffer number
    • content: terminal output as string

Example:

" Run command and get result
call coc#ui#run_terminal({'cmd': 'git status'}, function('s:HandleGitStatus'))

function! s:HandleGitStatus(err, result) abort
  if a:err isnot v:null
    echo 'Error:' a:err
    return
  endif
  if a:result.success
    echo a:result.content
  endif
endfunction

Low-Level Terminal Functions

coc#terminal#start()

coc#terminal#start(cmd, cwd, env, strict)
" Returns: list

Start terminal in new split window.

Parameters:

  • cmd: Command to execute (array or string)
  • cwd: Working directory (empty = current)
  • env: Environment variables (dictionary)
  • strict: Boolean for strict environment (clear existing on Neovim)

Returns: [bufnr, pid] - Buffer number and process ID

Example:

" Start interactive terminal
let [bufnr, pid] = coc#terminal#start('bash', getcwd(), {}, 0)
echo 'Terminal started with PID: ' . pid

" Start with custom environment
let env = {'PATH': '/custom/path:' . $PATH, 'NODE_ENV': 'development'}
let [bufnr, pid] = coc#terminal#start(['node', 'server.js'], getcwd(), env, 0)

coc#terminal#send()

coc#terminal#send(bufnr, text, add_new_line)

Send text to running terminal.

Parameters:

  • bufnr: Terminal buffer number
  • text: Text to send
  • add_new_line: Boolean (add newline if true)

Example:

" Send commands to terminal
call coc#terminal#send(bufnr, 'echo "Hello"', 1)
call coc#terminal#send(bufnr, 'ls -la', 1)

Task Management

coc#task#start()

coc#task#start(id, opts)
" Returns: boolean

Start background task.

Parameters:

  • id: Task identifier
  • opts: Options dictionary:
    • cmd: Command to execute (required)
    • args: Command arguments (optional)
    • cwd: Working directory (optional)
    • env: Environment variables (optional)
    • pty: Use pseudo-terminal (optional)
    • detach: Detach process on Neovim (optional)

Returns: boolean - success/failure

Example:

" Start background build task
let success = coc#task#start('build-task', {
  \ 'cmd': 'npm',
  \ 'args': ['run', 'build'],
  \ 'cwd': getcwd()
  \ })

if success
  echo 'Build task started'
else
  echohl Error | echo 'Failed to start build task' | echohl None
endif

" Start task with custom environment
let success = coc#task#start('dev-server', {
  \ 'cmd': 'npm',
  \ 'args': ['run', 'dev'],
  \ 'cwd': getcwd(),
  \ 'env': {'PORT': '3000', 'NODE_ENV': 'development'}
  \ })

" Start detached task
let success = coc#task#start('watch-task', {
  \ 'cmd': 'npm',
  \ 'args': ['run', 'watch'],
  \ 'detach': 1
  \ })

Message Display

coc#ui#echo_hover()

coc#ui#echo_hover(msg)

Display hover message in MoreMsg highlight.

Parameters:

  • msg: Message string to display

Example:

call coc#ui#echo_hover('Function: doSomething(param: string)')

coc#ui#echo_messages()

coc#ui#echo_messages(hl, msgs)

Display multiple messages with highlight.

Parameters:

  • hl: Highlight group name
  • msgs: Array of message strings

Example:

call coc#ui#echo_messages('Error', ['Line 1 error', 'Line 2 error'])

coc#ui#echo_lines()

coc#ui#echo_lines(lines)

Display array of lines.

Parameters:

  • lines: Array of line strings to display

Example:

call coc#ui#echo_lines(['Output line 1', 'Output line 2'])

coc#ui#echo_signatures()

coc#ui#echo_signatures(signatures)

Display signature help information.

Parameters:

  • signatures: Array of signature parts with type and text keys

Example:

let sigs = [
  \ [{'type': 'Normal', 'text': 'function '},
  \  {'type': 'Function', 'text': 'calculate'},
  \  {'type': 'Normal', 'text': '('},
  \  {'type': 'Parameter', 'text': 'value: number'},
  \  {'type': 'Normal', 'text': ')'}]
  \ ]
call coc#ui#echo_signatures(sigs)

coc#ui#quickpick()

coc#ui#quickpick(title, items, cb)

Display quick pick menu for user selection.

Parameters:

  • title: Menu title string
  • items: Array of menu items
  • cb: Callback function(err, result) where result is selected index

Example:

call coc#ui#quickpick('Select action:', ['Install', 'Update', 'Remove'], function('s:OnSelect'))

function! s:OnSelect(err, result) abort
  if a:err isnot v:null
    echohl Error | echo a:err | echohl None
    return
  endif
  echo 'Selected:' a:result
endfunction

Preview Window

coc#ui#preview_info()

coc#ui#preview_info(lines, filetype, ...)

Open preview window with content.

Parameters:

  • lines: Array of content lines
  • filetype: Filetype for syntax highlighting
  • ...: Optional Ex commands to execute in preview window

Example:

let code = ['function hello() {', '  console.log("Hello");', '}']
call coc#ui#preview_info(code, 'javascript', 'setl number')

File Management

coc#ui#open_files()

coc#ui#open_files(files)
" Returns: list

Load multiple files into buffers.

Parameters:

  • files: Array of file paths

Returns: Array of buffer numbers

Example:

let buffers = coc#ui#open_files(['src/index.js', 'src/utils.js'])

coc#ui#rename_file()

coc#ui#rename_file(oldPath, newPath, write)
" Returns: number

Rename file buffer and optionally write to disk.

Parameters:

  • oldPath: Current file path
  • newPath: New file path
  • write: 1 to write to disk and delete old file, 0 to just rename buffer

Returns: New buffer number

Example:

let new_bufnr = coc#ui#rename_file('old-name.js', 'new-name.js', 1)

coc#ui#safe_rename()

coc#ui#safe_rename(bufnr, oldPath, newPath, write)
" Returns: number

Safely rename file on case-insensitive systems. Handles case-only renames on macOS/Windows.

Parameters:

  • bufnr: Buffer number to rename
  • oldPath: Current file path
  • newPath: New file path
  • write: 1 to write to disk, 0 to just rename buffer

Returns: New buffer number

Example:

" Case-only rename on macOS
let bufnr = bufnr('MyFile.js')
call coc#ui#safe_rename(bufnr, 'MyFile.js', 'myfile.js', 1)

URL Opening

coc#ui#open_url()

coc#ui#open_url(url)

Open URL in system default browser.

Parameters:

  • url: URL string to open

Example:

call coc#ui#open_url('https://github.com/neoclide/coc.nvim')

iTerm Integration

coc#ui#iterm_open()

coc#ui#iterm_open(dir)
" Returns: boolean

Open directory in new iTerm2 tab (macOS only).

Parameters:

  • dir: Directory path to open

Returns: 1 on success, 0 on failure

Example:

if has('mac')
  call coc#ui#iterm_open(getcwd())
endif

Buffer Line Manipulation

coc#ui#set_lines()

coc#ui#set_lines(bufnr, changedtick, original, replacement, start, end, changes, cursor, col)

Set buffer lines with smart cursor preservation. Handles concurrent edits by applying diff if buffer changed.

Parameters:

  • bufnr: Buffer number
  • changedtick: Expected changedtick value
  • original: Original lines array
  • replacement: Replacement lines array
  • start: Start line (0-indexed)
  • end: End line (0-indexed, exclusive)
  • changes: Array of change tuples for nvim_buf_set_text
  • cursor: Cursor position [line, col] to restore
  • col: Original column for delta calculation

Example:

" Apply LSP text edit with change tracking
let changedtick = getbufvar(bufnr, 'changedtick')
call coc#ui#set_lines(bufnr, changedtick, original, replacement, 0, 5, [], [1, 0], 0)

coc#ui#change_lines()

coc#ui#change_lines(bufnr, list)
" Returns: v:null

Change specific lines in buffer with undo join.

Parameters:

  • bufnr: Buffer number
  • list: Array of [lnum, line] tuples (0-indexed line numbers)

Example:

call coc#ui#change_lines(bufnr('%'), [[0, 'new first line'], [5, 'new sixth line']])

Sign Management

coc#ui#sign_unplace()

coc#ui#sign_unplace()

Unplace all coc signs from all buffers.

Example:

call coc#ui#sign_unplace()

coc#ui#update_signs()

coc#ui#update_signs(bufnr, group, signs)

Update signs in buffer efficiently. Only updates changed signs, preserves unchanged ones.

Parameters:

  • bufnr: Buffer number
  • group: Sign group name
  • signs: Array of sign definitions with keys:
    • name: Sign name (must be defined)
    • lnum: Line number (1-indexed)
    • priority: Optional priority (higher = more visible)

Example:

" Update diagnostic signs
let signs = [
  \ {'name': 'CocErrorSign', 'lnum': 5, 'priority': 10},
  \ {'name': 'CocWarningSign', 'lnum': 12, 'priority': 8}
  \ ]
call coc#ui#update_signs(bufnr('%'), 'coc-diagnostic', signs)

coc#ui#check_pum_keymappings()

coc#ui#check_pum_keymappings()

Check for outdated popup menu keymappings. Shows warning if old pumvisible()-style mappings detected.

Related Variables

g:coc_last_hover_message

g:coc_last_hover_message

Contains the last hover message displayed by coc#ui#echo_hover().

Type: String (read-only)

Example:

echo g:coc_last_hover_message

Common Patterns

Terminal Command Execution

" Run build and handle result
function! s:Build() abort
  call coc#ui#run_terminal({
    \ 'cmd': 'npm run build',
    \ 'cwd': getcwd(),
    \ 'keepfocus': 1
    \ }, function('s:OnBuildDone'))
endfunction

function! s:OnBuildDone(err, result) abort
  if a:result.success
    call coc#ui#echo_hover('Build completed successfully')
  else
    call coc#ui#echo_messages('Error', ['Build failed!'])
  endif
endfunction

File Batch Operations

" Open related files for editing
function! s:OpenRelatedFiles() abort
  let files = ['src/index.js', 'src/types.ts', 'test/index.test.js']
  let buffers = coc#ui#open_files(files)
  echo 'Opened' len(buffers) 'files'
endfunction

Sign Updates

" Update error signs from diagnostics
function! s:UpdateDiagnosticSigns(diagnostics) abort
  let signs = []
  for diag in a:diagnostics
    let sign_name = diag.severity == 1 ? 'CocErrorSign' : 'CocWarningSign'
    call add(signs, {
      \ 'name': sign_name,
      \ 'lnum': diag.range.start.line + 1,
      \ 'priority': diag.severity == 1 ? 10 : 8
      \ })
  endfor
  call coc#ui#update_signs(bufnr('%'), 'coc-diagnostic', signs)
endfunction

Interactive Terminal Session

function! StartDevServer() abort
  " Start terminal
  let [bufnr, pid] = coc#terminal#start('bash', getcwd(), {}, 0)

  " Send initialization commands
  call coc#terminal#send(bufnr, 'npm install', 1)
  sleep 2
  call coc#terminal#send(bufnr, 'npm run dev', 1)

  echo 'Dev server started in buffer' bufnr
endfunction

Background Task with Progress

function! RunBuildTask() abort
  let success = coc#task#start('build', {
    \ 'cmd': 'npm',
    \ 'args': ['run', 'build'],
    \ 'cwd': expand('%:p:h')
    \ })

  if success
    call coc#ui#echo_hover('Build task started...')
  else
    call coc#ui#echo_messages('Error', ['Failed to start build task'])
  endif
endfunction

Safe File Rename

function! RenameCurrentFile(newname) abort
  let oldpath = expand('%:p')
  let dirname = expand('%:p:h')
  let newpath = dirname . '/' . a:newname

  let bufnr = bufnr('%')
  call coc#ui#safe_rename(bufnr, oldpath, newpath, 1)

  echo 'Renamed to' a:newname
endfunction

command! -nargs=1 Rename call RenameCurrentFile(<q-args>)

Smart Message Display

function! ShowDiagnosticMessage(diagnostic) abort
  let lines = [
    \ 'Severity: ' . a:diagnostic.severity,
    \ 'Message: ' . a:diagnostic.message,
    \ 'Source: ' . get(a:diagnostic, 'source', 'unknown')
    \ ]
  call coc#ui#echo_lines(lines)
endfunction

Error Handling

Terminal Failure

try
  let bufnr = coc#ui#open_terminal({'cmd': 'invalid-command'})
catch
  echohl Error
  echo 'Failed to open terminal:' v:exception
  echohl None
endtry

File Operation Errors

function! SafeRename(old, new) abort
  if !filereadable(a:old)
    call coc#ui#echo_messages('Error', ['File not found: ' . a:old])
    return
  endif

  if filereadable(a:new)
    call coc#ui#echo_messages('Error', ['Target file already exists'])
    return
  endif

  call coc#ui#rename_file(a:old, a:new, 1)
endfunction

Task Start Failure

let success = coc#task#start('task-id', {'cmd': 'mycmd'})
if !success
  echohl Error
  echo 'Failed to start task'
  echohl None
endif

Sign Update Validation

function! ValidateAndUpdateSigns(signs) abort
  " Validate sign names exist
  for sign in a:signs
    if !hlexists(sign.name)
      echohl WarningMsg
      echo 'Sign not defined:' sign.name
      echohl None
      return
    endif
  endfor

  call coc#ui#update_signs(bufnr('%'), 'custom', a:signs)
endfunction

Troubleshooting

Terminal Not Opening

  • Check if terminal is supported: has('terminal') or has('nvim')
  • Verify command is in PATH
  • Test command manually in shell first
  • Check for shell configuration issues

Commands Not Executing

  • Verify working directory exists
  • Check environment variables are correct
  • Test with absolute paths
  • Review terminal output for errors

Signs Not Appearing

  • Ensure sign is defined: :sign list
  • Check signcolumn is enabled: :set signcolumn=yes
  • Verify buffer is loaded
  • Check for conflicting signs

File Rename Issues

  • Verify file permissions
  • Check for open buffers with old filename
  • Use safe_rename for case-only changes
  • Ensure target directory is writable

Message Display Problems

  • Check highlight groups exist
  • Verify messages aren't being cleared too quickly
  • Use :messages to review command history
  • Check for autocmds that clear messages

See Also

  • Float Windows - Floating window management
  • Window Management - Window control utilities
  • Diagnostics - Diagnostic signs and messages
  • Configuration - UI configuration settings