In the spirit of IDEs, Sublime Text suggests completions that aggregate code or content while writing by catching everything that you have written, like variable names.
There are however several ways to extend the list of completions (for example, depending on the current syntax).
This topic deals with how completions are used and where they come from.
How to Use Completions
There are two methods for using completions. Even though, when screening them, the priority given to completions always stays the same, the two methods produce different results.
Completions can be inserted in two ways:
- through the completions list (Ctrl ␣), or
- by pressing ⭾.
The Completions List
To use the completions list:
- Press Ctrl ␣ or just type something.
- Optionally, press Ctrl ␣ again to select the next entry or use up and down arrow keys.
- Press ⏎ or ⭾ to validate selection (depending on the
- Optionally, press ⭾ repeatedly to insert the next available completion.
If the completions list was opened explicitly, the current selection in the completions list can also be validated with any punctuation sign that isn't itself bound to a snippet (e.g.
When the list of completion candidates can be narrowed down to one unambiguous choice given the current prefix, this one completion will be validated automatically the moment you trigger the completion list.
Additionally, you may see a trigger hint on the right side of a completion's trigger in the completions list. This can be used as a preview of the completion's content.
The above is in fact a snippet and expands to
$arrayName = array('' => , );.
Triggers and Contents
Completions not sourced from the text in the current file may provide a trigger that is different to the content they will insert if selected. This is commonly used for function completions where the content also includes the function's signature.
For example, completing
array_map from the PHP completions will result in
You may notice in the animation that the cursor automatically selected
callback. This is because completions support the same features as snippets with fields and placeholders. For more details, refer to Snippet Features.
Completions with multiple cursors
Sublime Text can also handle completions with multiple cursors but will only open the completion list when all cursors share the same text between the current cursor positions and the last word separator character (e.g.
. or a line break).
Working example (
| represents one cursor):
l| some text with l| l| and.l|
Not working example:
l| some text with la| l| andl|
Selections are essentially ignored, only the position of the cursor matters. Thus,
e|[-some selection] example, with
| as the cursor and
[...] as the current selection, completes to
example|[-some selection] example.
If you want to be able to tab-complete completions, the setting
tab_completion must be set to
true (default). Snippet tab-completion is unaffected by this setting: They will always be completed according to their tab trigger.
tab_completion enabled, completion of items is always automatic. This means, unlike the case of the completions list, that Sublime Text will always make the decision for you. The rules for selecting the best completion are the same as described above, but in case of ambiguity, Sublime Text will insert the item it deems most suitable. You can press the ⭾ key multiple times to walk through other available options.
Inserting a Literal tab Character
tab_completion is enabled, you can press ⇧ ⭾ to insert a literal tab character.
Sources for Completions and their Priorities
These are the sources for completions the user can control, in the order they are prioritized:
Additionally, the following completions are folded into the final list:
- Words in the buffer
Snippets will always win when the current prefix matches their tab trigger exactly. For the rest of the completion sources, a fuzzy match is performed. Furthermore, snippets always lose in a fuzzy match.
When a list of completions is shown, snippets will still be listed alongside the other items, even if the prefix only partially matches the snippets' tab triggers.
Completions sourced from words in the buffer can be suppressed explicitly from an
on_query_completions event hook.
Auto Completion Triggers and Selector
Sublime Text provides two settings for users and package authors to tweak their auto completion behavior. Both settings work independently of each other and either of them can trigger the auto-completion popup.
auto_complete_selectorexpects a scope selector that when matched causes the auto-completion popup to open for any non-punctuation character, i.e. for identifiers. The default configuration disables this for syntaxes with a focus on plain text, comments and strings.
Before 4070, the selector was applied to the position after the just-typed character.
auto_complete_triggersexpects a list of mappings that may specify
charactersthat should trigger the auto-completion popup and/or a scope
selector. If both are provided, both are required to match.
rhs_emptyboolean may be provided that states whether the right-hand side of the caret must be empty or a whitespace character. It defaults to
Package authors may be interested in configuring triggers and/or the selector in a syntax-specific settings file.