/cmp-nvim-ultisnips

nvim-cmp source for ultisnips

Primary LanguageLuaApache License 2.0Apache-2.0

cmp-nvim-ultisnips

UltiSnips completion source for nvim-cmp

Screenshot

Features

  • Composable Mappings: get rid of boilerplate code in your config
  • Treesitter Integration: show snippets based on the filetype at your cursor position
  • Customization: change which and how snippets are displayed by cmp

Installation and Recommended Mappings

Check out the Mappings section if you want to define your own mappings.

use({
  "hrsh7th/nvim-cmp",
  requires = {
    "quangnguyen30192/cmp-nvim-ultisnips",
    config = function()
      -- optional call to setup (see customization section)
      require("cmp_nvim_ultisnips").setup{}
    end,
    -- If you want to enable filetype detection based on treesitter:
    -- requires = { "nvim-treesitter/nvim-treesitter" },
  },
  config = function()
    local cmp_ultisnips_mappings = require("cmp_nvim_ultisnips.mappings")
    require("cmp").setup({
      snippet = {
        expand = function(args)
          vim.fn["UltiSnips#Anon"](args.body)
        end,
      },
      sources = {
        { name = "ultisnips" },
        -- more sources
      },
      -- recommended configuration for <Tab> people:
      mapping = {
        ["<Tab>"] = cmp.mapping(
          function(fallback)
            cmp_ultisnips_mappings.expand_or_jump_forwards(fallback)
          end,
          { "i", "s", [[ "c" (to enable the mapping in command mode) ]] }
        ),
        ["<S-Tab>"] = cmp.mapping(
          function(fallback)
            cmp_ultisnips_mappings.jump_backwards(fallback)
          end,
          { "i", "s", [[ "c" (to enable the mapping in command mode) ]] }
        ),
      },
    })
  end,
})

Mappings

You can compose your own mappings that are comprised of the following actions:

  • expand: expands the current snippet if the completion window is closed
  • jump_forwards / jump_backwards: jumps to the next / previous snippet tabstop
  • select_next_item / select_prev_item: selects the next / previous completion item

The recommended mappings use the compose function under the hood:

function M.expand_or_jump_forwards(fallback)
  M.compose({ "expand", "jump_forwards", "select_next_item" })(fallback)
end

function M.jump_backwards(fallback)
  M.compose({ "jump_backwards", "select_prev_item" })(fallback)
end

For example, if you prefer a separate key for jumping between snippet tabstops you can do the following:

local cmp_ultisnips_mappings = require("cmp_nvim_ultisnips.mappings")
-- In your cmp setup:
...
mapping = {
  ["<Tab>"] = cmp.mapping(
    function(fallback)
      cmp_ultisnips_mappings.compose({ "expand", "select_next_item" })(fallback)
    end,
    ...

These actions are implemented as a table { condition = ..., command = ... }. If the condition for an action fails, the next action (in the order as the action keys are passed to compose) is tried until the first condition matches. Then the command function is run. If none match, fallback is called.

Customization

Available Options

filetype_source: "treesitter" | "ultisnips_default"

Determines how the filetype of a buffer is identified. This option affects which snippets are available by UltiSnips. If set to "treesitter" and the nvim-treesitter plugin is installed, only snippets that match the filetype at the current cursor position are shown (as well as snippets included via UltiSnips' extends directive). Otherwise, or if treesitter could not determine the filetype at the current position, the available snippets are handled entirely by UltiSnips.

Default: "treesitter"

show_snippets: "expandable" | "all"

If set to "expandable", only those snippets currently expandable by UltiSnips will be shown. The snippets will always be in sync with the currently available UltiSnips snippets.

"all" will show all snippets for the current filetype. If using this option, be aware that all snippets for the current buffer will be cached (even if the snippet definitions changed). You can then manually reload the snippets with the command :CmpUltisnipsReloadSnippets or by using an autocommand:

autocmd BufWritePost *.snippets :CmpUltisnipsReloadSnippets

Expression snippets (option r) and custom context snippets (option e) are never shown.

Default: "expandable"

documentation(snippet: {}): function

snippet is a table that contains the following keys (each value is a string):

  • trigger, description, options, value

Returns: a string that is shown by cmp in the documentation window. If an empty string ("") is returned, the documentation window will not appear for that snippet.

Default: require("cmp_nvim_ultisnips.snippets").documentation

By default, this shows the snippet description at the top of the documentation window followed by the snippet content (see screenshot at the top of the readme).

Example Configuration

Note: calling the setup function is only required if you wish to customize this plugin.

require("cmp_nvim_ultisnips").setup {
  filetype_source = "treesitter",
  show_snippets = "all",
  documentation = function(snippet)
    return snippet.description
  end
}

Credit