github github
star 599
alert-circle 9
open issues
users 7
git-branch 9





The goal of nvim-ufo is to make Neovim's fold look modern and keep high performance.

setup foldcolumn like demo

Table of contents


  • Penetrate color for folded lines like other modern editors/IDEs
  • Never block Neovim
  • Adding folds high accuracy with Folding Range in LSP
  • Support fallback and customize strategy for fold provider
  • Peek folded line and jump the desired location with less redraw




Install with Packer.nvim:

use {'kevinhwang91/nvim-ufo', requires = 'kevinhwang91/promise-async'}

Minimal configuration

use {'kevinhwang91/nvim-ufo', requires = 'kevinhwang91/promise-async'}

vim.o.foldcolumn = '1'
vim.o.foldlevel = 99 -- Using ufo provider need a large value, feel free to decrease the value
vim.o.foldlevelstart = 99
vim.o.foldenable = true

-- Using ufo provider need remap `zR` and `zM`. If Neovim is 0.6.1, remap yourself
vim.keymap.set('n', 'zR', require('ufo').openAllFolds)
vim.keymap.set('n', 'zM', require('ufo').closeAllFolds)

-- Option 1: coc.nvim as LSP client
use {'neoclide/coc.nvim', branch = 'master', run = 'yarn install --frozen-lockfile'}

-- Option 2: nvim lsp as LSP client
-- Tell the server the capability of foldingRange,
-- Neovim hasn't added foldingRange to default capabilities, users must add it manually
local capabilities = vim.lsp.protocol.make_client_capabilities()
capabilities.textDocument.foldingRange = {
    dynamicRegistration = false,
    lineFoldingOnly = true
local language_servers = {} -- like {'gopls', 'clangd'}
for _, ls in ipairs(language_servers) do
        capabilities = capabilities,
        other_fields = ...

-- Option 3: treesitter as a main provider instead
-- Only depend on `nvim-treesitter/queries/filetype/folds.scm`,
-- performance and stability are better than `foldmethod=nvim_treesitter#foldexpr()`
use {'nvim-treesitter/nvim-treesitter', run = ':TSUpdate'}
    provider_selector = function(bufnr, filetype, buftype)
        return {'treesitter', 'indent'}

-- Option 4: disable all providers for all buffers
-- Not recommend, AFAIK, the ufo's providers are the best performance in Neovim
    provider_selector = function(bufnr, filetype, buftype)
        return ''


Use fold as usual.

Using a provider of ufo, must set a large value for foldlevel, this is the limitation of foldmethod=manual. A small value may close fold automatically if the fold ranges updated.

After running zR and zM normal commands will change the foldlevel, ufo provide the APIs openAllFolds/closeAllFolds to open/close all folds but keep foldlevel value, need to remap them.

Like zR and zM, if you used zr and zm before, please use closeFoldsWith API to close folds like set foldlevel=n but keep foldlevel value.


How does nvim-ufo get the folds?

If ufo detect foldmethod option is not diff or marker, it will request the providers to get the folds, the request strategy is formed by the main and the fallback. The default value of main is lsp and the default value of fallback is indent which implemented by ufo.

For example, Changing the text in a buffer will request the providers for folds.

foldmethod option will finally become manual if ufo are working.

Setup and description

    open_fold_hl_timeout = {
        description = [[Time in millisecond between the range to be highlgihted and to be cleared
                    while opening the folded line, `0` value will disable the highlight]],
        default = 400
    provider_selector = {
        description = [[A function as a selector for fold providers. For now, there are
                    'lsp' and 'treesitter' as main provider, 'indent' as fallback provider]],
        default = nil
    close_fold_kinds = {
        description = [[After the buffer is displayed (opened for the first time), close the
                    folds whose range with `kind` field is included in this option.
                    For now, only 'lsp' provider contain 'comment', 'imports' and 'region'.]],
        default = {}
    fold_virt_text_handler = {
        description = [[A function customize fold virt text, see ### Customize fold text]],
        default = nil
    enable_fold_end_virt_text = {
        description = [[Enable to capture the virtual text for the fold end lnum and assign the
                    result to `end_virt_text` field of ctx table as 6th parameter in
        default = false
    preview = {
        description = [[Configure the options for preview window and remap the keys for current
                    buffer and preview buffer if the preview window is displayed.
                    Never worry about the users's keymaps are overridden by ufo, ufo will save
                    them and restore them if preview window is closed.]],
        win_config = {
            border = {
                description = [[The border for preview window,
                    `:h nvim_open_win() | call search('border:')`]],
                default = 'rounded',
            winblend = {
                description = [[The winblend for preview window, `:h winblend`]],
                default = 12,
            winhighlight = {
                description = [[The winhighlight for preview window, `:h winhighlight`]],
                default = 'Normal:Normal',
        mappings = {
            description = [[The table for {function = key}]],
            default = [[see ###Preview function table for detail]],

:h ufo may help you to get the all default configuration.

Preview function table

Function Action Def Key
scrollB Type CTRL-B in preview window
scrollF Type CTRL-F in preview window
scrollU Type CTRL-U in preview window
scrollD Type CTRL-D in preview window
scrollE Type CTRL-E in preview window <C-E>
scrollY Type CTRL-Y in preview window <C-Y>
close In normal window: close preview windowIn preview window: close preview window q
switch In normal window: Go to preview windowIn preview window: Go to normal window <Tab>
trace In normal window: Trace code based on toplineIn preview window: Trace code based on cursor <CR>

Additional mouse supported:

  1. <ScrollWheelUp> and <ScrollWheelDown>: Scroll preview window.
  2. <2-LeftMouse>: Same as trace action in preview window.

trace action will open all fold for the folded lines


Command Description
UfoEnable Enable ufo
UfoDisable Disable ufo
UfoInspect Inspect current buffer information
UfoAttach Attach current buffer to enable all features
UfoDetach Attach current buffer to disable all features
UfoEnableFold Enable to get folds and update them at once for current buffer
UfoDisableFold Disable to get folds for current buffer



Highlight groups

hi default link UfoPreviewSbar PmenuSbar
hi default link UfoPreviewThumb PmenuThumb
hi default link UfoFoldedEllipsis Comment
  • UfoPreviewSbar: highlight the scroll bar of preview window, only take effect if the border is missing right horizontal line, like border = 'none'.
  • UfoPreviewThumb: highlight the thumb of preview window.
  • UfoFoldedEllipsis: highlight ellipsis at the end of folded line, invalid if fold_virt_text_handler is set.

Advanced configuration

Configuration can be found at example.lua

Customize configuration

local ftMap = {
    vim = 'indent',
    python = {'indent'},
    git = ''
    open_fold_hl_timeout = 150,
    close_fold_kinds = {'imports', 'comment'},
    preview = {
        win_config = {
            border = {'', '─', '', '', '', '─', '', ''},
            winhighlight = 'Normal:Folded',
            winblend = 0
        mappings = {
            scrollU = '<C-u>',
            scrollD = '<C-d>'
    provider_selector = function(bufnr, filetype, buftype)
        -- return a string type use internal providers
        -- return a string in a table like a string type
        -- return empty string '' will disable any providers
        -- return `nil` will use default value {'lsp', 'indent'}

        -- if you prefer treesitter provider rather than lsp,
        -- return ftMap[filetype] or {'treesitter', 'indent'}
        return ftMap[filetype]
vim.keymap.set('n', 'zR', require('ufo').openAllFolds)
vim.keymap.set('n', 'zM', require('ufo').closeAllFolds)
vim.keymap.set('n', 'zr', require('ufo').openFoldsExceptKinds)
vim.keymap.set('n', 'zm', require('ufo').closeFoldsWith) -- closeAllFolds == closeFoldsWith(0)
vim.keymap.set('n', 'K', function()
    local winid = require('ufo').peekFoldedLinesUnderCursor()
    if not winid then
        -- choose one of them
        -- coc.nvim
        -- nvimlsp

Customize fold text

local handler = function(virtText, lnum, endLnum, width, truncate)
    local newVirtText = {}
    local suffix = ('  %d '):format(endLnum - lnum)
    local sufWidth = vim.fn.strdisplaywidth(suffix)
    local targetWidth = width - sufWidth
    local curWidth = 0
    for _, chunk in ipairs(virtText) do
        local chunkText = chunk[1]
        local chunkWidth = vim.fn.strdisplaywidth(chunkText)
        if targetWidth > curWidth + chunkWidth then
            table.insert(newVirtText, chunk)
            chunkText = truncate(chunkText, targetWidth - curWidth)
            local hlGroup = chunk[2]
            table.insert(newVirtText, {chunkText, hlGroup})
            chunkWidth = vim.fn.strdisplaywidth(chunkText)
            -- str width returned from truncate() may less than 2nd argument, need padding
            if curWidth + chunkWidth < targetWidth then
                suffix = suffix .. (' '):rep(targetWidth - curWidth - chunkWidth)
        curWidth = curWidth + chunkWidth
    table.insert(newVirtText, {suffix, 'MoreMsg'})
    return newVirtText

-- global handler
    fold_virt_text_handler = handler

-- buffer scope handler
-- will override global handler if it is existed
local bufnr = vim.api.nvim_get_current_buf()
require('ufo').setFoldVirtTextHandler(bufnr, handler)


  • If you get an issue or come up with an awesome idea, don't hesitate to open an issue in github.
  • If you think this plugin is useful or cool, consider rewarding it a star.


The project is licensed under a BSD-3-clause license. See LICENSE file for details.