Emmet 2 extension for CodeMirror editor
CodeMirror extension that adds Emmet support to text editor.
Extension development is sponsored by CodePen.
How to use
This extension can be installed as a regular npm module:
npm install --save @emmetio/codemirror-plugin
The package itself follows CodeMirror extension convention and simply registers new commands and some extension methods. In order to use Emmet, you should create CodeMirror instance and provide keymap with Emmet actions. Currently, this extension registers only 2 actions:
emmetExpandAbbreviation
– expand abbreviation from current cursor position.emmetInsertLineBreak
– inserts formatted line break if cursor is between tags.
The package comes in to flavors: a stand-alone browser bundle and ES2015/CommonJS modules that you can use in your app.
If you’re building an app, you can use extension like this:
;; // Register extension on CodeMirror constructor; // Create editor instance and provide keymap for Emmet actionsconst editor = CodeMirror;
For a stand-alone, basic usage, simply add dist/emmet-codemirror-plugin.js
file into your page:
Autocomplete provider
The new Emmet 2 concept suggests that Emmet should be used as autocomplete provider: it gives user full control over Tab key, editors’ native snippets and provides real-time preview of expanded abbreviation.
CodeMirror doesn’t have native autocomplete support but provides fully optional show-hint module. To add autocomplete support into your CodeMirror instance, call .getEmmetCompletions()
extension method in editor instance and use its result as a provider for autocomplete extension. This method returns object with the following properties:
from
andto
properties describe range of matched Emmet abbreviation in editor.list
contains list of completions with the following properties:type
: type of completion item, eitherexpanded-abbreviation
orsnippet
.range
: object withfrom
andto
properties that describe range of editor content to be replaced with current completion item. Note that forexpanded-abbreviation
item type this range matches full abbreviation, while forsnippet
type it matches only a part of abbreviation.label
: completion display label.preview
: preview of expanded completion item.insert()
: a method that applies current completion item to editor.
For a complete example of how to use Emmet completions with show-hint
module, see example.html
file.
Tag pair marking and renaming
Pass markTagPairs: true
option to enable automatic HTML tag pair marking in editor: open and close tags will be marked with .emmet-open-tag
and .emmet-close-tag
classes respectively. If this option enabled (off by default), changing either open or close tag will automatically update the opposite part. To disable automatic renaming, pass autoRenameTags: false
option:
const editor = CodeMirror;
Adding custom snippets
You can add custom Emmet snippets via emmet
option when creating CodeMirror editor instance:
const editor = CodeMirror;
Note that markup and stylesheet snippet definitions are different. Markup snippets are written as Emmet abbreviations (e.g. you simply describe element name and its default attributes) while stylesheet snippets are aliases to CSS properties with optional keywords list, separated by |
character. These keywords are used in abbreviation resolving process. For more examples, see @emmetio/snippets repo.
How it works
In order to provide a predictable completions list, this extension automatically marks Emmet abbreviation as a text marker when user types text in editor. This marker is automatically re-validated on change and destroyed when user edits different part of code. The marker has .emmet-abbreviation
class and can be styled via CSS to give users a clue what part of text will be expanded as abbreviation. Also, this marker contains .model
property with extracted and parsed abbreviation.
The main reason to use text marker is to allow user to edit entered abbreviation and maintain proper autocomplete and abbreviation expansion context. You can use .findEmmetMarker()
extension method in editor instance to get abbreviation marker. It’s mostly used to automatically display autocomplete popup when cursor enters abbreviation: if there’s marker for given cursor position then there’s valid abbreviation to expand.
If you experience issues with abbreviation marker, you can disable it by passing markEmmetAbbreviation: false
option when creating editor instance or by setting this option to false
with editor.setOption()
method.