nvim-ufo

Use require('ufo').setup() to customize plugin behavior. Key configuration options include:

• open_fold_hl_timeout: Timeout for fold highlight.
• close_fold_kinds_for_ft: Define which fold kinds (e.g., 'imports', 'comment', 'array') should be closed by default for specific filetypes.
• close_fold_current_line_for_ft: Boolean or table to determine if the current line should be closed for specific filetypes.
• preview: Configuration for the fold preview window, including win_config (borders, highlights, blend) and mappings (scroll and jump keys).
• provider_selector: A function to select the fold provider (e.g., 'lsp', 'indent', or 'treesitter') based on bufnr, filetype, and buftype.
• fold_virt_text_handler: A function to customize how folded text is displayed.

To use a custom provider selection logic, implement a function that returns the desired provider string or table.

local ftMap = {
    vim = 'indent',
    python = {'indent'},
    git = ''
}
require('ufo').setup({
    open_fold_hl_timeout = 150,
    close_fold_kinds_for_ft = {
        default = {'imports', 'comment'},
        json = {'array'},
        c = {'comment', 'region'}
    },
    close_fold_current_line_for_ft = {
        default = true,
        c = false
    },
    preview = {
        win_config = {
            border = {'', '─', '', '', '', '─', '', ''},
            winhighlight = 'Normal:Folded',
            winblend = 0
        },
        mappings = {
            scrollU = '<C-u>',
            scrollD = '<C-d>',
            jumpTop = '[',
            jumpBot = ']'
        }
    },
    provider_selector = function(bufnr, filetype, buftype)
        return ftMap[filetype]
    end
})

The require('ufo').setup() function accepts a configuration table. Key options include:

• open_fold_hl_timeout: Time in ms between highlighting and clearing the range when opening a folded line (default: 400).
• provider_selector: A function to select fold providers (e.g., {'lsp', 'treesitter', 'indent'}).
• close_fold_kinds_for_ft: A table mapping filetypes to fold kind values (like 'comment', 'imports', or 'region') to be closed on buffer display.
• close_fold_current_line_for_ft: A table mapping filetypes to booleans to determine if folds on the current line should be closed on display.
• fold_virt_text_handler: A function to customize fold virtual text.
• enable_get_fold_virt_text: Enables capturing virtual text for folded lines.
• override_foldtext: Whether to override foldtext with a custom virtual text handler (default: true).
• preview: Configuration for the preview window, including win_config (border, winblend, winhighlight, maxheight) and mappings.

You can customize the text displayed for folded lines by providing a handler function to fold_virt_text_handler in the setup() call.

The handler function receives the following arguments:

• virtText: The virtual text chunks.
• lnum: The starting line number of the fold.
• endLnum: The ending line number of the fold.
• width: The available width for the text.
• truncate: A function to truncate text.

You can apply this globally via require('ufo').setup() or per-buffer using require('ufo').setFoldVirtTextHandler(bufnr, handler).

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)
        else
            chunkText = truncate(chunkText, targetWidth - curWidth)
            local hlGroup = chunk[2]
            table.insert(newVirtText, {chunkText, hlGroup})
            chunkWidth = vim.fn.strdisplaywidth(chunkText)
            if curWidth + chunkWidth < targetWidth then
                suffix = suffix .. (' '):rep(targetWidth - curWidth - chunkWidth)
            end
            break
        end
        curWidth = curWidth + chunkWidth
    end
    table.insert(newVirtText, {suffix, 'MoreMsg'})
    return newVirtText
end

require('ufo').setup({
    fold_virt_text_handler = handler
})

The following functions are available for managing folds and previewing content:

• require('ufo').openAllFolds(): Opens all folds.
• require('ufo').closeAllFolds(): Closes all folds.
• require('ufo').openFoldsExceptKinds(kinds): Opens all folds except those matching the specified kinds.
• require('ufo').closeFoldsWith(kinds): Closes folds matching the specified kinds (passing 0 is equivalent to closeAllFolds).
• require('ufo').peekFoldedLinesUnderCursor(): Peeks at the folded lines under the cursor. Returns a window ID if successful.

Example keybindings:

-- Open/Close all folds
vim.keymap.set('n', 'zR', require('ufo').openAllFolds)
vim.keymap.set('n', 'zM', require('ufo').closeAllFolds)

-- Open/Close specific kinds
vim.keymap.set('n', 'zr', require('ufo').openFoldsExceptKinds)
vim.keymap.set('n', 'zm', require('ufo').closeFoldsWith)

-- Peek folded lines and fallback to LSP/CoC hover
vim.keymap.set('n', 'K', function()
    local winid = require('ufo').peekFoldedLinesUnderCursor()
    if not winid then
        -- choose one of coc.nvim and nvim lsp
        vim.fn.CocActionAsync('definitionHover') -- coc.nvim
        vim.lsp.buf.hover()
    end
end)

-- Example keybindings
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)

vim.keymap.set('n', 'K', function()
    local winid = require('ufo').peekFoldedLinesUnderCursor()
    if not winid then
        vim.lsp.buf.hover()
    end
end)