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 + Spacebar), or
- by pressing
The Completions List¶
To use the completions list:
Ctrl + Spacebaror just type something.
- Optionally, press
Ctrl + Spacebaragain to select the next entry or use up and down arrow keys.
Tabto validate selection (depending on the
- Optionally, press
Tabrepeatedly 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.
array_map from the PHP completions
will result in
You may notice in the animation
that the cursor automatically selected
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
. 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.
e|[-some selection] example,
| as the cursor and
[...] as the current selection,
example|[-some selection] example.
If you want to be able to tab-complete completions,
tab_completion must be set to
Snippet tab-completion is unaffected by this setting:
They will always be completed
according to their tab trigger.
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
Tab key multiple times
to walk through other available options.
Inserting a Literal Tab Character¶
tab_completion is enabled,
you can press
Shift + Tab 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
on_query_completions event hook.