11. Completions

Sublime Text Completions provide a multi-faceted way to save typing and time by finishing words or inserting boilerplate text. You use completions by typing something while Sublime Text pays attention to the similarities of what you are typing, and what has already been typed.

There are 2 main kinds of Completions.

• Snippets are activated by typing a “key” prefix and then hitting [Tab]. When:

  • the choice is unambiguous (i.e. resolves to only one, or you supplied the exact key for a certain Snippet), and

  • the context of the cursor(s) is (are) a match for a Scope specified in the .sublime-snippet file,

  the content of the Snippet is drawn from that Snippet file and inserted into the text where the cursor is. Snippets are covered more thoroughly in the Snippets section.

  Snippets are the preferred type of Completion when the boilerplate text they provide is be extensive (more than can be easily maintained in a Completions file).

  Snippets can also be inserted programmatically. This is an extremely powerful feature, allowing any number of Snippet variables to be computed on the fly, based on the current context.

  See Snippets for more details.

• All other Completion types involved a popup list just below the cursor that offers one or more choices, often including additional information about each item in the list, like what kind of Completion it is (function, variable, Snippet, etc.), annotations giving helpful hints about it, and sometimes even a link to more information about it. The source of these types of Completions may be drawn from a number of sources (in priority order):

  • Snippet files (when the exact “tab trigger key” was not supplied, or [Ctrl+Space] was used instead of [Tab])

  • Plugins (via on_query_completions event hooks)

  • Completion files

  • Context-aware suggestions (words from the current file, as of build 4050)

A large number settings exist to customize the behavior of Completions. Like most everything else in Sublime Text, Completions can be extensively customized, and users can create their own. Many third-party Packages exist to provide Completions for specific editing contexts (e.g. with a programming or formatting/layout language).

11.1. Using Completions

When Completions are active, there is a popup list just below the cursor enabling you to select from the list with the mouse or [UpArrow] and [DownArrow] keys, and hit [Tab] or [Enter] to accept the current entry (the auto_complete_commit_on_tab setting’s Boolean value controls which one), or [Esc] to close the Completions popup list and continue typing.

If the Completions popup list is not visible and you want it to be, you can open it in one of 2 ways:

[Ctrl+Space]:

opens the Completions popup list

[Tab]:

completes the string left of the cursor with a Completion or Snippet if there is only one choice, or opens the Completions popup if there is more than one choice. (If the tab_completion setting is false, [Tab] will only work to trigger Snippets, not Completions.)

The Completions popup list items can be adorned (on the right) with annotations that indicate the meaning of each item, and the end of the list can sometimes display a clickable link about the selected item, or other information provided via the details key of a Completion object in a Completions file.

Note

1. The Completions popup list may be opened when there are multiple cursors, but this will only happen if each cursor shares identical trigger context (text and scope).

2. If your cursor is after some trigger text and you instead want to insert an actual \t character, hold the [Shift] key while hitting [Tab]. [1]

[1]

As of 10-Jun-2025, the sublime-rst-completions Package had a bug in handling the [shift+tab] Key Binding. This was fixed in its pull request #108. Specifically it was failing to honor the conditions under which [shift+tab] should perform an “unindent” rather than insert a “\t” character when any of the following are true: A) multiple lines are selected, B) the cursor is at the beginning of the line possibly preceded by tabs and/or spaces, or C) the “shift_tab_unindent” setting is true. If your sublime-rst-completions Package is causing problematic behavior with the [shift+tab] key binding, simply install the fix submitted in pull request #108.

11.2. Creating Your Own Completions

Sublime text uses the following to supply the Completions popup with a list of likely candidates:

• any Snippet files whose scope applies to the current editing context,

• any Completion files whose scope applies to the current editing context,

• the content of the current file.

If you want to supplement that list, you can do so in any of 3 ways:

• create a Snippet file (see Snippets for details),

• create a Completions file (see below for details), and/or

• manage Completions from a Plugin (see Implementing Completions in a Plugin for details).

Using the latter has the most flexibility and even allows you to suppress automatically-supplied Completion-list items (source from words the buffer) if desired.

11.3. Completions File Format

.sublime-completions files use this Sublime-relaxed-JSON format:

{
    "scope": "selector_defining_when_this_list_is_active",
    "completions": [
        { completion_object },
        { completion_object },
        { completion_object },
        { completion_object },
        { completion_object },
        { completion_object },
        ...
    ]
}

See Scope, Selectors and Context for details about the syntax for the “scope” entry.

completion_object is a dictionary object with these entries:

Key	Value
“trigger”	required, trigger string
“contents”	required, Smart-Template Syntax described with Snippets
“kind”	optional, string or 3-element array of strings described below
“annotation”	optional, annotation described below
“details”	optional, single-line description; may contain basic formatting HTML tags

11.3.1. Trigger

The trigger string (or an approximation of it) must immediately precede the cursor. This string provides the first “filter” as to what is placed in the Completions list. If the string in the text is only the beginning (or a partial string), fuzzy matches are done to build the Completions list with likely candidates.

11.3.2. Contents

The syntax of the “contents” value is described fully in the Smart-Template Syntax section. The only difference is that it must be entirely contained in a JSON string (in the Completions file) rather than as free-form text inside an XML CDATA tag, as it is for a Snippets file. Line endings are added by including newline characters in the string like this: “line1nline2nline3”.

11.3.3. Kind

If “kind” is a single string, it must be one of these:

• “ambiguous”

• “function”

• “keyword”

• “markup”

• “namespace”

• “navigation”

• “snippet”

• “type”

• “variable”

If “kind” is a 3-element array of strings, they must be:

1. a string from the list above, which is used by the theme to select the color of the “kind” metadata,

2. a single Unicode character to be shown to the left of the trigger,

3. a description of the kind, viewable in the “kind” letter tool tip (opened by hovering the mouse over the “kind” letter), and the detail pane at the bottom of the list (when visible).

Example: “kind”: [“function”, “m”, “Method”]

11.3.4. Annotation

If provided, the “annotation” entry contains a short textual “hint”, shown to right of the completions popup list item, giving the end user a reminder about what it is, helping him to differentiate it from other similar Completion items that might also be in the list.

11.3.5. Details

If provided, the “details” entry contains at most one line of text with a very brief description (beyond the annotation) to help the user understand the purpose of that Completion item in the list. That line of text will appear at the bottom of the list in the “detail pane” when it is visible. That text may contain any of the following HTML tags

• <a href=\”\”> — miniHTML Protocols

• <b>

• <strong>

• <i>

• <em>

• <u>

• <tt>

• <code>

If an anchor tag is included, remember that the quotation marks containing the href value must be escaped since they will be inside of a JSON string (the Completions file contains JSON data). The link text will be shown in the Completion list’s “detail pane” when it is visible.

11.3.6. Example

Here is a .sublime-completions file with examples of each field:

{
    "scope": "source.python",
    "completions": [
        {
            "trigger": "def",
            "contents": "def",
            "kind": "keyword"
        },
        {
            "trigger": "fun",
            "annotation": "basic function",
            "contents": "def ${1:name}($2):\n    $0\n",
            "kind": "snippet",
            "details": "A simple, non-<code>async</code> function definition"
        }
    ]
}

11.4. Implementing Completions in a Plugin

Plugins provide the widest flexibility in implementing and managing Completions.

Special handling for the end user clicking links in the detail pane can be provided via a Plugin: a callback can be specified via the API to handle clicks on anchor tags. See the following API elements for how this is done:

• sublime.add_regions() on_navigate argument

• sublime.show_popup() on_navigate argument

• sublime.Phantom() on_navigate argument

Study this Python code presented in OdatNurd video [P101-14] about implementing Completions in a Plugin. Remember that your class’ needs to inherit from one of the following:

• sublime_plugin.EventListener (instantiated once [for whole ST application])

• sublime_plugin.ViewEventListener (instantiated once per VIEW object)

• sublime_plugin.TextChangeListener (instantiated ONCE per BUFFER object)

And note that it will need to be filtered by using the is_applicable() and other event callback functions. See OdatNurd P101 lessons 11-16 on safely harnessing Sublime Text events:

def on_query_completions(self, view, prefix, locations):
    # We get called in every view we apply to; if it matters, we should
    # make sure our completions are relevant for the current location
    # or file type.
    # if not view.match_selector(0, "source.python"):
    #     return None

    # if not view.match_selector(locations[0], "source.python"):
    #     return None

    if not all(view.match_selector(pt, "source.python") for pt in locations):
        return None

    print(f'prefix=[{prefix}] locations=[{locations}]')

    #return [["something"], ["otherthing"]]

    # return [
    #     ["something", "something()"],
    #     ["otherthing", "otherthing()"]
    # ]

    # return [
    #     ["something\thelper function", "something()"],
    #     ["otherthing\thelper function", "otherthing()"]
    # ]

    # $0 is where cursor is placed after completion, and
    # ${TM_FILENAME} is the name of the file being edited (stem + ext).
    # These "variables" work the same way as they do for Snippets.
    # return [
    #     ["something\thelper function", "something($0)"],
    #     ["otherthing\thelper function", "otherthing('${TM_FILENAME}')"]
    # ]

    # NONE = 0
    # INHIBIT_WORD_COMPLETIONS = 8
    #     Prevent Sublime |nbsp| Text from showing completions based on
    #     the contents of the view.
    # INHIBIT_EXPLICIT_COMPLETIONS = 16
    #     Prevent Sublime |nbsp| Text from showing completions based on
    #     :path:`.sublime-completions` files.
    # DYNAMIC_COMPLETIONS = 32
    #     If completions should be re-queried as the user types.
    #     .. since:: 4057
    # INHIBIT_REORDER = 128
    #     Prevent Sublime |nbsp| Text from changing the completion order.
    return ([
            ["something\thelper function", "something($0)"],
            ["otherthing\thelper function", "otherthing('${TM_FILENAME}')"]
        ],
        sublime.AutoCompleteFlags.INHIBIT_WORD_COMPLETIONS \
            | sublime.AutoCompleteFlags.INHIBIT_EXPLICIT_COMPLETIONS
        )

11.5. Further Reading

There are a large number of Sublime Text’s settings that control behavior of Completions. These are well documented here:

https://www.sublimetext.com/docs/completions.html#settings