Home

Awesome

Emmet extension for CodeMirror editor

CodeMirror extension that adds Emmet support to text editor.

How to use

This extension can be installed as a regular npm module:

npm i @emmetio/codemirror-plugin

The package comes in two flavors: a stand-alone browser bundle and ES/CommonJS modules that you can use in your app.

If you’re building an app, you can use extension like this:

import CodeMirror from 'codemirror';
import emmet from '@emmetio/codemirror-plugin';

// Register extension on CodeMirror object
emmet(CodeMirror);

// Create editor instance and provide keymap for Emmet actions
const editor = CodeMirror.fromTextArea(document.getElementById('code'), {
    mode : "text/html",
    extraKeys: {
        'Tab': 'emmetExpandAbbreviation',
        'Esc': 'emmetResetAbbreviation',
        'Enter': 'emmetInsertLineBreak'
    }
});

For a stand-alone, basic usage, simply add dist/browser.js file into your page:

<script src="./node_modules/codemirror/lib/codemirror.js"></script>
<script src="./node_modules/@emmetio/codemirror-plugin/dist/browser.js"></script>

<form>
    <textarea id="code" name="code"></textarea>
</form>

<script>
var editor = CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    extraKeys: {
        'Tab': 'emmetExpandAbbreviation',
        'Esc': 'emmetResetAbbreviation',
        'Enter': 'emmetInsertLineBreak'
    }
});
</script>

Expanding abbreviations

Emmet extension can track abbreviations that user enters in some known syntaxes like HTML and CSS. When user enters something that looks like Emmet abbreviation, extension starts abbreviation tracking (adds emmet-abbreviation class to a text fragment). WHen abbreviation becomes complex (expands to more that one element), it displays abbreviation preview:

Emmet abbreviation example

Run emmetExpandAbbreviation command to expand tracked abbreviation or emmetResetAbbreviation to reset it. Suggested key bindings are <kbd>Tab</kbd> for emmetExpandAbbreviation and <kbd>Esc</kbd> for emmetResetAbbreviation.

Abbreviation tracker is context-aware: it detect current syntax context and works only where abbreviation expected. For example, in HTML syntax it works in plain text context only and doesn’t work, for example, in attribute value or tag name.

If you already have abbreviation in editor, you can capture it to continue editing: run emmetCaptureAbbreviation action (<kbd>Ctrl-Space</kbd> by default):

Emmet abbreviation capturing

Abbreviation mode

In case if abbreviation tracking is unavailable or you want to give user an opportunity to enter and expand abbreviation with interactive preview, a special abbreviation mode is available. Run emmetEnterAbbreviationMode command to enter this mode: everything user types will be tracked as abbreviation with preview and validation. Use emmetExpandAbbreviation command to expand it or emmetResetAbbreviation to quit abbreviation mode.

JSX abbreviation

In order to not distract user with unexpected abbreviation tracking, in JSX syntax Emmet requires to prefix abbreviation with < to provide more natural context where JSX markup is required.

Emmet JSX example

Tag pair marking and renaming

Extension is able to mark paired open and close HTML tags in editor: it adds emmet-class-tag and emmet-close-tag name to matched tag names. Optionally, extension can display preview of matching open tag when cursor is inside close tag.

When tag pair tag marking is enabled, it’s possible to automatically rename tag pair when you update open or close tag:

Emmet tag pair example

Commands

The package itself follows CodeMirror extension convention and registers new commands in CodeMirror namespace. In order to use Emmet, you should create CodeMirror instance and provide keymap with the following Emmet actions:

Options

You can pass emmet object when creating CodeMirror editor instance to modify extension behavior:

CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    lineNumbers : true,

    // Pass Emmet extension options
    emmet: {
        mark: true,
        markTagPairs: true,
        previewOpenTag: false,
    }
});

Extension supports the following options:

Emmet config

With config option (see above) you can add custom abbreviation snippets and fine-tune Emmet behavior.

Snippets are grouped by syntax (like html, css, pug etc.) and syntaxes are grouped by type: markup or stylesheet. You can specify snippets that should be available for all syntaxes in group or specific syntax only.

Snippets are just short aliases for Emmet abbreviations: you either specify shorthand for a larger abbreviation or define shape for a specific element:

CodeMirror.fromTextArea(document.getElementById("code"), {
    mode : "text/html",
    lineNumbers : true,

    // Pass Emmet extension options
    emmet: {
        config: {
            // Specify snippets for all markup syntaxes: HTML, XML, Pug etc.
            markup: {
                // Shorthand for larger abbreviation
                foo: 'div.foo>section.bar*3',

                // Define shape of element, looks like recursive abbreviation
                a: 'a[href title]',
                br: 'br/'
            },

            // Specify snippets for specific syntax only
            html: {
                nav: 'ul.nav>.nav-item*4>a'
            }
        }
    }
});

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 check out default Emmet snippets.

See all available config params in GlobalConfig type.