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.

float-windows.mddocs/ui/

Floating Windows [Intermediate]

Complexity: Intermediate | Category: UI

Common Tasks: Scroll floats | Hide floats | Jump to float | Manage float windows

Manage floating windows, popups, scrolling, and notifications.

Table of Contents

  • Common Tasks
  • Key Mappings
  • Float Functions
  • Advanced Float Functions
  • Global Variables
  • Configuration
  • Highlight Groups
  • Autocmd Events
  • Usage Examples
  • Error Handling
  • Troubleshooting
  • See Also

Common Tasks

Scroll Float Window Down

call coc#float#scroll(1)

Scroll floating window content downward.

Hide All Float Windows

call coc#float#close_all()

Close all open floating windows.

Jump to Float Window

call coc#float#jump()

Move cursor focus to first floating window.

Check if Float Exists

if coc#float#has_float()
  " Do something with float
endif

Key Mappings

<Plug>(coc-float-hide)

<Plug>(coc-float-hide)

Hide all floating windows.

Example:

nmap <silent> <C-c> <Plug>(coc-float-hide)

<Plug>(coc-float-jump)

<Plug>(coc-float-jump)

Jump to first floating window.

Example:

nmap <silent> <leader>fj <Plug>(coc-float-jump)

Float Functions

coc#float#has_float()

coc#float#has_float([...])
" Returns: boolean

Check if any floating window exists.

Returns: 1 if float window exists, 0 otherwise.

Example:

if coc#float#has_float()
  echo "Float window is open"
endif

coc#float#has_scroll()

coc#float#has_scroll()
" Returns: boolean

Check if a scrollable floating window exists.

Returns: 1 if scrollable float exists, 0 otherwise.

Example:

if coc#float#has_scroll()
  call coc#float#scroll(1)
endif

coc#float#scroll()

coc#float#scroll(forward, [amount])

Scroll floating windows.

Parameters:

  • forward: Direction - 1 for down, 0 for up
  • amount: Optional number of lines to scroll (default: proportional to window height)

Example:

" Scroll down
call coc#float#scroll(1)

" Scroll up
call coc#float#scroll(0)

" Scroll down 5 lines
call coc#float#scroll(1, 5)

" Mappings
nnoremap <silent><nowait><expr> <C-f> coc#float#has_scroll() ? coc#float#scroll(1) : "\<C-f>"
nnoremap <silent><nowait><expr> <C-b> coc#float#has_scroll() ? coc#float#scroll(0) : "\<C-b>"

coc#float#scrollable()

coc#float#scrollable(winid)
" Returns: boolean

Check if specific float window is scrollable.

Parameters:

  • winid: Window ID

Returns: 1 if scrollable, 0 otherwise.

Example:

let winid = coc#float#get_float_win_list()[0]
if coc#float#scrollable(winid)
  echo "Window is scrollable"
endif

coc#float#close_all()

coc#float#close_all([...])

Close all floating windows.

Example:

call coc#float#close_all()

" Close on ESC
nnoremap <silent> <Esc> :call coc#float#close_all()<CR>

coc#float#close()

coc#float#close(winid)

Close specific floating window.

Parameters:

  • winid: Window ID to close

Example:

let winid = coc#float#get_float_win_list()[0]
call coc#float#close(winid)

coc#float#jump()

coc#float#jump()

Jump to first floating window.

Example:

nnoremap <silent> <leader>fj :call coc#float#jump()<CR>

coc#float#valid()

coc#float#valid(winid)
" Returns: boolean

Check if floating window is valid.

Parameters:

  • winid: Window ID

Returns: 1 if valid, 0 otherwise.

Example:

if coc#float#valid(g:coc_last_float_win)
  echo "Float window is still valid"
endif

coc#float#get_float_win_list()

coc#float#get_float_win_list([list_all])
" Returns: list

Get list of all visible float window IDs (Neovim) or popup IDs (Vim). Can optionally include all float windows regardless of the 'float' flag.

Parameters:

  • list_all: Optional flag (0 or 1). If 1, includes all float windows (default: 0)

Returns: Array of window IDs.

Example:

" Get visible float windows
let floats = coc#float#get_float_win_list()
echo 'Open float windows: ' . len(floats)
for winid in floats
  echo 'Window ID: ' . winid
endfor

" Get all float windows (including hidden)
let all_floats = coc#float#get_float_win_list(1)
echo 'Total float windows: ' . len(all_floats)

coc#float#get_float_by_kind()

coc#float#get_float_by_kind(kind)
" Returns: number

Get floating window by kind.

Parameters:

  • kind: Float window kind

Returns: Window ID or 0 if not found.

Example:

let winid = coc#float#get_float_by_kind('hover')

coc#float#get_height()

coc#float#get_height(winid)
" Returns: number

Get floating window height.

Parameters:

  • winid: Window ID

Returns: Window height in lines.

Example:

let height = coc#float#get_height(winid)
echo 'Float window height: ' . height

coc#float#change_height()

coc#float#change_height(winid, delta)

Change floating window height.

Parameters:

  • winid: Window ID
  • delta: Height change (positive to increase, negative to decrease)

Example:

" Increase height by 5 lines
call coc#float#change_height(winid, 5)

" Decrease height by 3 lines
call coc#float#change_height(winid, -3)

Advanced Float Functions

coc#float#create_float_win()

coc#float#create_float_win(winid, bufnr, config)
" Returns: list

Create or update a floating window with specified configuration. Handles border rendering, button creation, scrollbars, and related windows. Supports both Vim8 popups and Neovim floating windows. This is a low-level API primarily for extensions.

Parameters:

  • winid: Existing window ID (0 for new window)
  • bufnr: Buffer number (0 to create new)
  • config: Configuration dictionary with keys:
    • relative: 'editor' or 'cursor'
    • row, col: Position
    • width, height: Dimensions
    • lines: Optional initial lines
    • title: Window title
    • border: Border configuration [top, right, bottom, left]
    • highlight: Highlight group
    • borderhighlight: Border highlight
    • buttons: Array of button labels
    • close: Show close button (1/0)
    • winblend: Blend value
    • shadow: Use shadow effect
    • focusable: Window focusability
    • scrollinside: Scrollbar position
    • rounded: Use rounded borders
    • nopad: No padding

Returns: [winid, bufnr] on success, empty list on failure.

Example:

" Create simple float window
let config = {
  \ 'relative': 'cursor',
  \ 'row': 1,
  \ 'col': 0,
  \ 'width': 50,
  \ 'height': 10,
  \ 'border': [1, 1, 1, 1],
  \ 'highlight': 'CocFloating'
  \ }
let bufnr = nvim_create_buf(v:false, v:true)
let result = coc#float#create_float_win(0, bufnr, config)
if len(result) > 0
  echo "Created float window: " . result[0]
endif

coc#float#create_buf()

coc#float#create_buf(bufnr, [lines], [mode])
" Returns: number

Create or reuse a temporary buffer with optional content. Used for float window content buffers and related windows.

Parameters:

  • bufnr: Buffer number (positive = reuse, 0 = create new)
  • lines: Optional lines to populate buffer (default: [])
  • mode: Optional buffer hidden mode (default: 'wipe')

Returns: Buffer number

Example:

" Create new buffer with content
let bufnr = coc#float#create_buf(0, ['Line 1', 'Line 2', 'Line 3'])

" Reuse existing buffer
let bufnr = coc#float#create_buf(existing_bufnr, ['Updated content'])

Global Variables

g:coc_last_float_win

g:coc_last_float_win

Window ID of last created floating window.

Type: Number (read-only)

Example:

if exists('g:coc_last_float_win') && g:coc_last_float_win > 0
  call coc#float#close(g:coc_last_float_win)
endif

Configuration

Float window settings in coc-settings.json:

{
  "hover.floatConfig": {
    "border": true,
    "rounded": true,
    "maxWidth": 80,
    "maxHeight": 20,
    "highlight": "CocFloating",
    "borderhighlight": "CocFloating"
  },
  "diagnostic.floatConfig": {
    "border": true
  },
  "signature.floatConfig": {
    "border": true
  }
}

Highlight Groups

CocFloating

CocFloating

Default floating window background.

Example:

highlight CocFloating ctermbg=235 guibg=#1e1e1e

CocErrorFloat

CocErrorFloat

Error text in floating windows.

CocWarningFloat

CocWarningFloat

Warning text in floating windows.

CocInfoFloat

CocInfoFloat

Info text in floating windows.

CocHintFloat

CocHintFloat

Hint text in floating windows.

Autocmd Events

User CocOpenFloat

autocmd User CocOpenFloat {command}

Triggered when a floating window is opened.

Example:

autocmd User CocOpenFloat echo "Float window opened"

User CocOpenFloatPrompt

autocmd User CocOpenFloatPrompt {command}

Triggered when a prompt floating window is opened.

Example:

autocmd User CocOpenFloatPrompt echo "Prompt opened"

Usage Examples

Basic Float Scrolling

" Scroll float windows with Ctrl-f/b
nnoremap <silent><nowait><expr> <C-f> coc#float#has_scroll() ? coc#float#scroll(1) : "\<C-f>"
nnoremap <silent><nowait><expr> <C-b> coc#float#has_scroll() ? coc#float#scroll(0) : "\<C-b>"

" Scroll with j/k in float
nnoremap <silent><nowait><expr> <C-d> coc#float#has_scroll() ? coc#float#scroll(1, 10) : "\<C-d>"
nnoremap <silent><nowait><expr> <C-u> coc#float#has_scroll() ? coc#float#scroll(0, 10) : "\<C-u>"

Close Float on Events

" Close floats on cursor move
autocmd CursorMoved * call coc#float#close_all()

" Close floats on mode change
autocmd InsertEnter * call coc#float#close_all()

" Close floats on buffer change
autocmd BufLeave * call coc#float#close_all()

Float Window Management

function! ManageFloatWindows() abort
  let floats = coc#float#get_float_win_list()

  if len(floats) == 0
    echo "No float windows open"
    return
  endif

  echo "Open float windows: " . len(floats)

  for i in range(len(floats))
    let winid = floats[i]
    let height = coc#float#get_height(winid)
    echo (i + 1) . ". Window " . winid . " (height: " . height . ")"
  endfor
endfunction

command! FloatInfo call ManageFloatWindows()

Smart Float Close

" Close float or quit if no float
function! SmartFloatClose() abort
  if coc#float#has_float()
    call coc#float#close_all()
  else
    quit
  endif
endfunction

nnoremap <silent> q :call SmartFloatClose()<CR>

Jump to Float

" Jump to float and navigate
function! JumpToFloat() abort
  if !coc#float#has_float()
    echo "No float window"
    return
  endif

  call coc#float#jump()
  echo "Jumped to float window"
endfunction

nnoremap <silent> <leader>jf :call JumpToFloat()<CR>

Scroll with Mouse

" Enable mouse scrolling in floats
if has('mouse')
  " Scroll with mouse wheel
  nnoremap <silent><expr> <ScrollWheelDown> coc#float#has_scroll() ? coc#float#scroll(1, 3) : "\<ScrollWheelDown>"
  nnoremap <silent><expr> <ScrollWheelUp> coc#float#has_scroll() ? coc#float#scroll(0, 3) : "\<ScrollWheelUp>"
endif

Resize Float Windows

function! ResizeFloat(delta) abort
  let floats = coc#float#get_float_win_list()

  if len(floats) == 0
    echo "No float windows"
    return
  endif

  for winid in floats
    call coc#float#change_height(winid, a:delta)
  endfor

  echo "Resized " . len(floats) . " float(s) by " . a:delta
endfunction

nnoremap <silent> <leader>f+ :call ResizeFloat(5)<CR>
nnoremap <silent> <leader>f- :call ResizeFloat(-5)<CR>

Float Window Status

function! FloatWindowStatus() abort
  let floats = coc#float#get_float_win_list()
  let scrollable = 0

  for winid in floats
    if coc#float#scrollable(winid)
      let scrollable += 1
    endif
  endfor

  echo "Floats: " . len(floats) . " (scrollable: " . scrollable . ")"
endfunction

command! FloatStatus call FloatWindowStatus()

Close Invalid Floats

function! CloseInvalidFloats() abort
  let floats = coc#float#get_float_win_list()
  let closed = 0

  for winid in floats
    if !coc#float#valid(winid)
      call coc#float#close(winid)
      let closed += 1
    endif
  endfor

  if closed > 0
    echo "Closed " . closed . " invalid float(s)"
  endif
endfunction

command! CleanFloats call CloseInvalidFloats()

Toggle Float Visibility

let g:float_windows_hidden = 0
let g:float_windows_list = []

function! ToggleFloatVisibility() abort
  if g:float_windows_hidden
    " Restore floats (not directly possible, they need to be recreated)
    echo "Float windows need to be reopened"
    let g:float_windows_hidden = 0
  else
    " Hide floats
    call coc#float#close_all()
    let g:float_windows_hidden = 1
    echo "Float windows hidden"
  endif
endfunction

nnoremap <silent> <leader>tf :call ToggleFloatVisibility()<CR>

Auto-Close Float Timer

function! AutoCloseFloat(timeout) abort
  if !coc#float#has_float()
    return
  endif

  call timer_start(a:timeout, {-> coc#float#close_all()})
endfunction

" Auto-close after 5 seconds
autocmd User CocOpenFloat call AutoCloseFloat(5000)

Float with Border

" Configure borders in coc-settings.json
{
  "hover.floatConfig": {
    "border": true,
    "rounded": true,
    "borderhighlight": ["InfoFloat"]
  }
}

" Custom border highlight
highlight InfoFloat ctermfg=109 guifg=#87afaf

Scroll to Position

function! ScrollFloatToTop() abort
  if !coc#float#has_scroll()
    return
  endif

  " Scroll up maximum amount to reach top
  for i in range(100)
    call coc#float#scroll(0, 10)
  endfor
endfunction

function! ScrollFloatToBottom() abort
  if !coc#float#has_scroll()
    return
  endif

  " Scroll down maximum amount to reach bottom
  for i in range(100)
    call coc#float#scroll(1, 10)
  endfor
endfunction

nnoremap <silent> <leader>ft :call ScrollFloatToTop()<CR>
nnoremap <silent> <leader>fb :call ScrollFloatToBottom()<CR>

Error Handling

Float Not Found

If a float window operation fails:

let winid = coc#float#get_float_by_kind('hover')
if winid == 0
  echo "No hover float window found"
else
  call coc#float#close(winid)
endif

Invalid Window ID

Always check if window is valid before operations:

if coc#float#valid(winid)
  call coc#float#scroll(1)
endif

Create Float Failure

Check return value when creating floats:

let result = coc#float#create_float_win(0, bufnr, config)
if len(result) == 0
  echohl Error
  echo "Failed to create float window"
  echohl None
endif

Troubleshooting

Float Windows Not Scrolling

  • Check if float is scrollable with coc#float#scrollable(winid)
  • Verify content exceeds window height
  • Use coc#float#has_scroll() before scrolling

Float Windows Not Closing

  • Use coc#float#close_all() to force close all
  • Check for autocmds that may recreate floats
  • Verify window IDs are still valid

Float Content Not Visible

  • Check highlight groups (CocFloating, etc.)
  • Verify float window configuration
  • Ensure buffer has content

Float Position Issues

  • Check relative setting ('editor' vs 'cursor')
  • Verify row/col coordinates are valid
  • Consider screen boundaries and window size

See Also

  • Window Management - Window control utilities
  • UI Functions - UI utility functions
  • Highlights Colors - Float highlight customization
  • Configuration - Float window settings