Completions

Completions provide an IDE-like functionality to insert dynamic content through the completions list or by pressing Tab.

File Format

Completions are JSON files with the .sublime-completions extension.

Structure of a Completions List

scope

Determines whether the completions are to be sourced from this file. See Scopes for more information.

completions

Array of completions.

Here’s an excerpt from the html completions:

{
        "scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

        "completions":
        [
                { "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
                { "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
                { "trigger": "acronym", "contents": "<acronym>$0</acronym>" }

        ]
}

Types of Completions

Plain Strings

Plain strings are equivalent to an entry where the trigger is identical to the contents:

"foo"

# is equivalent to:

{ "trigger": "foo", "contents": "foo" }

Trigger-based Completions

trigger

Text that will be displayed in the completions list and will cause the contents to be inserted when validated.

contents

Text to be inserted in the buffer. Can use snippet features.

Sources for Completions

These are the sources for completions the user can control:

• .sublime-completions
• EventListener.on_query_completions()

Additionally, other completions are folded into the final list:

• Snippets
• Words in the buffer

Priority of Sources for Completions

• Snippets
• API-injected completions
• .sublime-completions files
• Words in buffer

Snippets will only be automatically completed against an exact match of their tab trigger. Other sources for completions are filtered with a case insensitve fuzzy search instead.

The Completions List

To use the completions list:

• Press Ctrl+spacebar to open
• Optionally, press Ctrl+spacebar again to select next entry
• Press Enter or Tab to validate selection

Note

The current selection in the completions list can actually be validated with any punctuation sign that isn’t itself bound to a snippet.

Snippets show up in the completions list following the pattern: <tab_trigger> : <name>. For the other completions, you will just see the text to be inserted.

If the list of completions can be narrowed down to one choice, the autocomplete dialog will be bypassed and the corresponding content will be inserted straight away according to the priority rules stated above.

Enabling and Disabling Tab Completion for Completions

The tab_completion setting is true by default. Set it to false if you want Tab to stop sourcing the most likely completion. This setting has no effect on triggers defined in .sublime-snippet files, so snippets will always be inserted after a Tab.

With tab_completion on, The same order of priority as stated above applies, but, unlike in the case of the completions list, Sublime Text will always insert a completion, even if faced with an ambiguous choice.

Inserting a Literal Tab

If tab_completion is true, you can press Shift+Tab after a prefix to insert a literal tab character.