When should item.word be used for a completion item?

[smjonas]

I understand what label and insertText are but when should item.word be used in a completion item? What does it do?

nvim-cmp/lua/cmp/types/lsp.lua

Lines 192 to 197 in a58712b

	---
	---TODO: Should send the issue for upstream?
	---@field public word string|nil
	---@field public dup boolean|nil
	return lsp

[dmitmel]

(Not a definitive answer) So, the only places where this field is read are:

nvim-cmp/lua/cmp/entry.lua

Lines 105 to 107 in b11f8bb

	if misc.safe(self.completion_item.word) then
	return self.completion_item.word
	end

nvim-cmp/lua/cmp/core.lua

Line 377 in b11f8bb

completion_item.textEdit.newText = misc.safe(completion_item.insertText) or completion_item.word or completion_item.label

which leads me to believe that it is just a nvim-cmp-specific override of the label field (remember that the value of label is used as a fallback value if insertText, or filterText etc are not present, so the value of word will also propagate to those fields). As for when you should use it and not label - no idea. It has been there since the initial commit.

[smjonas]

Thank you, I also treated it the same as label. I saw that it is now used in cmp-path since the last commit and was not sure if it should be set for my source as well. Maybe @hrsh7th will have some additional clarification on this :)

[hrsh7th]

First, I would like to remove the word and dup properties if possible.

But at the moment they are implemented.
First, the dup property is needed because LSP doesn't have the ability to" remove the candidate if there is another high-priority identical word "in vim.

And the reason the word property exists is that LSP and VSCode don't define" text to insert at selection ".

google translated

[hrsh7th]

This implementation and hacky solutions should be removed, I think. But I don't have solution at the moment...

[hrsh7th]

Purpose	LSP	Vim	nvim-cmp
Text for selection	N/A	word	Use word if provieded. if no, should calculate it by hacky implementation (like coc)
Filtering text	filterText or label	word or abbr	Use suitable property as defined in LSP
Text for confirmation	textEdit or insertText or label	N/A	Use suitable property as defined in LSP