Autocomplete

The autoComplete() extension can be used to show a list of completable options to users while they’re typing.

Adding the extension

import { 
import{
fuzzyFilter, 
autoComplete 
} from "prism-code-editor/autocomplete" 
import { cursorPosition } from "prism-code-editor/cursor" 
import "prism-code-editor/autocomplete.css" 
import "prism-code-editor/autocomplete-icons.css" 
 
editor.addExtensions( 
cursorPosition(), 
autoComplete({ 
filter: fuzzyFilter, 
closeOnBlur: true, 
explicitOnly: false, 
preferAbove: false 
}) 
) 

Configuration

autoComplete() takes a AutoCompleteConfig object as the first parameter. The only required property is the filter function to use. The optional properties configure when to open the tooltip, when to close it, and where to place it.

Filters

The job of a CompletionFilter is to filter and score the options based on the word before the cursor. They should also return which characters in the option’s label were matched so they can be highlighted. This library exports two filter functions you can use; fuzzyFilter() and strictFilter(). If you’re dissatisfied with these, you can define your own filter instead.

Registering completion sources

The extension doesn’t define any completion sources. You have to register them with registerCompletions().

CSS completion

import { registerCompletions } from "prism-code-editor/autocomplete" 
import{ registerCompletions }from"prism-code-editor/autocomplete"
import { cssCompletion } from "prism-code-editor/autocomplete/css" 
 
registerCompletions(["css"], { 
sources: [cssCompletion()] 
}) 

Try it:

.prism-code-editor { 
.prism-code-editor{
--padding-inline: 1em; 
max-height: 50em; 
line-height: 1.5; 
} 

JavaScript completion

import { 
import{
completeKeywords, 
jsDocCompletion, 
jsxTagCompletion, 
reactTags, 
globalReactAttributes, 
jsSnipets, 
jsContext, 
jsCompletion 
} from "prism-code-editor/autocomplete/javascript" 
import { 
registerCompletions, 
completeFromList 
} from "prism-code-editor/autocomplete" 
 
registerCompletions(["javascript", "js", "jsx", "tsx", "typescript", "ts"], { 
context: jsContext, 
sources: [ 
jsCompletion(window), 
completeKeywords, 
jsDocCompletion, 
jsxTagCompletion(reactTags, globalReactAttributes), 
completeFromList(jsSnipets) 
] 
}) 

completeScope() is another completion source that can be used to add completion for the window object for example, but using it as the same time as completeIdentifiers() does lead to a lot of duplicated options.

/** 
/**
 * Try writing some TSX 
 */ 
function App(props) { 
return ( 
<> 
<div /> 
<input type="number" /> 
</> 
) 
} 

HTML completion

markupCompletion() adds completion for the specified namespaces of tags.

The example below shows how markupCompletion() can be used to add autocompletion to HTML, SVG, MathML, and one custom element. Here, globalHtmlAttributes are used for HTML elements, the custom element, and unrecognized elements.

import { registerCompletions } from "prism-code-editor/autocomplete" 
import{ registerCompletions }from"prism-code-editor/autocomplete"
import { 
markupCompletion, 
globalHtmlAttributes, 
htmlTags, 
globalSvgAttributes, 
svgTags, 
globalMathMLAttributes, 
mathMLTags, 
} from "prism-code-editor/autocomplete/markup" 
 
const namespaces = [ 
{ tags: htmlTags }, 
{ 
tags: svgTags, 
globals: globalSvgAttributes 
}, 
{ 
tags: mathMLTags, 
globals: globalMathMLAttributes 
}, 
{ 
tags: { 
"my-custom-element": { 
hello: ["world"], 
foo: null, 
bar: null 
} 
} 
} 
] 
 
registerCompletions(["html", "markup"], { 
sources: [markupCompletion(namespaces, globalHtmlAttributes)] 
}) 

Autocompletion works for nested languages too. Try writing in the script/style tags:

<body> 
<body>
<style> 
 
</style> 
<div style=""></div> 
<button onclick=""></button> 
<script> 
 
</script> 
</body> 
 
<!-- Try writing some SVG code --> 
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"> 
<clipPath> 
 
</clipPath> 
<circle /> 
</svg> 

Vue completion

vueCompletion() adds completion for HTML and SVG tags to Vue. When configured, it can also provide completions for specific Vue components.

import { registerCompletions } from "prism-code-editor/autocomplete" 
import{ registerCompletions }from"prism-code-editor/autocomplete"
import { vueCompletion } from "prism-code-editor/autocomplete/vue" 
 
registerCompletions(["vue"], { 
sources: [ 
vueCompletion({ 
MyComponent: { 
hello: ["world"], 
onevent: null 
} 
}) 
] 
}) 

Try it:

<script lang="ts" setup> 
<script lang="ts" setup>
 
</script> 
 
<template> 
<div></div> 
<input type="number"> 
<MyComponent /> 
</template> 
 
<style lang="css" scoped> 
 
</style> 

Svelte completion

svelteCompletion() is very similar to vueCompletion(), but the first parameter is instead used to configure snippets for blocks like {#each}, {#if}, etc.

import { registerCompletions } from "prism-code-editor/autocomplete" 
import{ registerCompletions }from"prism-code-editor/autocomplete"
import { 
svelteCompletion, 
svelteBlockSnippets 
} from "prism-code-editor/autocomplete/svelte" 
 
registerCompletions(["svelte"], { 
sources: [ 
svelteCompletion(svelteBlockSnippets, { 
MyComponent: { 
hello: ["world"], 
onevent: null 
} 
}) 
] 
}) 

Try it:

<script lang="ts"> 
<script lang="ts">
 
</script> 
 
<div></div> 
<input type="number"> 
 
{#if 2 > 1} 
<MyComponent /> 
{/if} 
 
<style lang="css"> 
 
</style> 

Creating your own definitions

CompletionDefinition objects passed to registerCompletions() have two properties: context and sources. The optional context property is a function that’s supposed to return an object with extra properties that are added to the CompletionContext passed to the sources. This is useful to avoid repeating logic between multiple completion sources.

Completion sources

The sources are called with the completion context along with the editor and can return a CompletionResult containing the completion items and where the completions should start from. These completion items don’t need to be filtered or sorted. That’s the job done by the filter function passed to the extension. It should be noted that completion sources must be synchronous and can be called on every keystroke, so they shouldn’t do any expensive computations.

Completion items

The completion items returned have multiple properties to customize their insertion and appearance. Read the Completion API reference for more info.

Snippets

To create snippets, use the insert property along with tabStops. The indentation will be preserved if there are line feeds in insert. Tabs are replaced with spaces according to the tab size when options.insertSpaces isn’t set to false.

import { Completion } from "prism-code-editor/autocomplete" 
import{Completion}from"prism-code-editor/autocomplete"
 
const mySnippets: Completion[] = [ 
{ 
label: "function", 
insert: "function name(params) {\n\t\n}", 
tabStops: [9, 13, 14, 20, 25], 
icon: "snippet", 
detail: "Function Statement", 
}, 
] 

Helpers

findWords() can be used to find words in the editor’s tokens that can be returned as completions.

getClosestToken() is extremely useful for determining if the completion is happening inside a specific token. It’s important that you pass context.pos as the fifth parameter to ensure the search always happens in the correct position.

Example

The example below shows how completion of a listOfKeywords can be done.

import { getClosestToken } from "prism-code-editor/utils" 
import{ getClosestToken }from"prism-code-editor/utils"
import { Completion, CompletionSource, registerCompletions } from "prism-code-editor/autocomplete" 
 
const options: Completion[] = listOfKeywords.map(label => ({ label, icon: "keyword" })) 
 
const mySource: CompletionSource = (context, editor) => { 
if (getClosestToken(editor, ".string, .comment", 0, 0, context.pos)) { 
return // Disable autocomplete in comments and strings 
} 
const wordBefore = /\w*$/.exec(context.lineBefore)![0] 
 
if (wordBefore || context.explicit) { 
return { 
from: context.pos - wordBefore.length, 
options: options, 
} 
} 
} 
 
registerCompletions(["a-language"], { 
sources: [mySource] 
}) 

For the example above, completeFromList() could be used instead if we added a completion context that defined the path property. See JSContext.path for what the path property is supposed to represent.

Icons

prism-code-editor/autocomplete-icons.css adds 14 icons from VS Code. Below is a list showing all icons.

class
constant
enum
event
function
interface
keyword
namespace
parameter
property
snippet
text
unit
variable

Using your own

The class pce-ac-icon- followed by the icon’s name is added to the icon element. For icons named variable you can use the selector .pce-ac-icon-variable to style them. You can also use the CSS variable --pce-ac-icon- followed by the icon’s name to set its color. The selector .pce-ac-icon can be used to style all icons. prism-code-editor/autocomplete-icons.css uses mask images to style the icons.