<!doctype html>
<title>CodeMirror 5 User Manual</title>
<meta charset="utf-8"/>
<link rel=stylesheet href="docs.css">
<script src="activebookmark.js"></script>
<script src="../lib/codemirror.js"></script>
<link rel="stylesheet" href="../lib/codemirror.css">
<script src="../addon/runmode/runmode.js"></script>
<script src="../addon/runmode/colorize.js"></script>
<script src="../mode/javascript/javascript.js"></script>
<script src="../mode/xml/xml.js"></script>
<script src="../mode/css/css.js"></script>
<script src="../mode/htmlmixed/htmlmixed.js"></script>
<style>
dt { text-indent: -2em; padding-left: 2em; margin-top: 1em; }
dd { margin-left: 1.5em; margin-bottom: 1em; }
dt {margin-top: 1em;}
dd dl, dd dt, dd dd, dd ul { margin-top: 0; margin-bottom: 0; }
dt + dt { margin-top: 0; }
dt.command { position: relative; }
span.keybinding { position: absolute; right: 0; font-size: 80%; color: #555; text-indent: 0; }
</style>
<div id=nav>
<a href="https://codemirror.net/5"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
<ul>
<li><a href="../index.html">Home</a></li>
<li><a href="#overview" class=active data-default="true">Manual</a></li>
<li><a href="https://github.com/codemirror/codemirror5">Code</a></li>
</ul>
<ul>
<li><a href="#usage">Basic Usage</a></li>
<li><a href="#config">Configuration</a></li>
<li><a href="#events">Events</a></li>
<li><a href="#keymaps">Key maps</a></li>
<li><a href="#commands">Commands</a></li>
<li><a href="#styling">Customized Styling</a></li>
<li><a href="#api">Programming API</a>
<ul>
<li><a href="#api_constructor">Constructor</a></li>
<li><a href="#api_content">Content manipulation</a></li>
<li><a href="#api_selection">Selection</a></li>
<li><a href="#api_configuration">Configuration</a></li>
<li><a href="#api_doc">Document management</a></li>
<li><a href="#api_history">History</a></li>
<li><a href="#api_marker">Text-marking</a></li>
<li><a href="#api_decoration">Widget, gutter, and decoration</a></li>
<li><a href="#api_sizing">Sizing, scrolling, and positioning</a></li>
<li><a href="#api_mode">Mode, state, and tokens</a></li>
<li><a href="#api_misc">Miscellaneous methods</a></li>
<li><a href="#api_static">Static properties</a></li>
</ul>
</li>
<li><a href="#addons">Addons</a></li>
<li><a href="#modeapi">Writing CodeMirror Modes</a></li>
<li><a href="#vimapi">Vim Mode API</a>
<ul>
<li><a href="#vimapi_configuration">Configuration</a></li>
<li><a href="#vimapi_events">Events</a></li>
<li><a href="#vimapi_extending">Extending VIM</a></li>
</ul>
</li>
</ul>
</div>
<article>
<section class=first id=overview>
<h2 style="position: relative">
User manual and reference guide
<span style="color: #888; font-size: 1rem; position: absolute; right: 0; bottom: 0">version 5.65.16</span>
</h2>
<p>CodeMirror is a code-editor component that can be embedded in
Web pages. The core library provides <em>only</em> the editor
component, no accompanying buttons, auto-completion, or other IDE
functionality. It does provide a rich API on top of which such
functionality can be straightforwardly implemented. See
the <a href="#addons">addons</a> included in the distribution,
and <a href="https://npms.io/search?q=codemirror">3rd party
packages on npm</a>, for reusable implementations of extra
features.</p>
<p>CodeMirror works with language-specific modes. Modes are
JavaScript programs that help color (and optionally indent) text
written in a given language. The distribution comes with a number
of modes (see the <a href="../mode/"><code>mode/</code></a>
directory), and it isn't hard to <a href="#modeapi">write new
ones</a> for other languages.</p>
</section>
<section id=usage>
<h2>Basic Usage</h2>
<p>The easiest way to use CodeMirror is to simply load the script
and style sheet found under <code>lib/</code> in the distribution,
plus a mode script from one of the <code>mode/</code> directories.
For example:</p>
<pre data-lang="text/html"><script src="lib/codemirror.js"></script>
<link rel="stylesheet" href="lib/codemirror.css">
<script src="mode/javascript/javascript.js"></script></pre>
<p>(Alternatively, use a module loader. <a href="#modloader">More
about that later.</a>)</p>
<p>Having done this, an editor instance can be created like
this:</p>
<pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body);</pre>
<p>The editor will be appended to the document body, will start
empty, and will use the mode that we loaded. To have more control
over the new editor, a configuration object can be passed
to <a href="#CodeMirror"><code>CodeMirror</code></a> as a second
argument:</p>
<pre data-lang="javascript">var myCodeMirror = CodeMirror(document.body, {
value: "function myScript(){return 100;}\n",
mode: "javascript"
});</pre>
<p>This will initialize the editor with a piece of code already in
it, and explicitly tell it to use the JavaScript mode (which is
useful when multiple modes are loaded).
See <a href="#config">below</a> for a full discussion of the
configuration options that CodeMirror accepts.</p>
<p>In cases where you don't want to append the editor to an
element, and need more control over the way it is inserted, the
first argument to the <code>CodeMirror</code> function can also
be a function that, when given a DOM element, inserts it into the
document somewhere. This could be used to, for example, replace a
textarea with a real editor:</p>
<pre data-lang="javascript">var myCodeMirror = CodeMirror(function(elt) {
myTextArea.parentNode.replaceChild(elt, myTextArea);
}, {value: myTextArea.value});</pre>
<p>However, for this use case, which is a common way to use
CodeMirror, the library provides a much more powerful
shortcut:</p>
<pre data-lang="javascript">var myCodeMirror = CodeMirror.fromTextArea(myTextArea);</pre>
<p>This will, among other things, ensure that the textarea's value
is updated with the editor's contents when the form (if it is part
of a form) is submitted. See the <a href="#fromTextArea">API
reference</a> for a full description of this method.</p>
<h3 id=modloader>Module loaders</h3>
<p>The files in the CodeMirror distribution contain shims for
loading them (and their dependencies) in AMD or CommonJS
environments. If the variables <code>exports</code>
and <code>module</code> exist and have type object, CommonJS-style
require will be used. If not, but there is a
function <code>define</code> with an <code>amd</code> property
present, AMD-style (RequireJS) will be used.</p>
<p>It is possible to
use <a href="http://browserify.org/">Browserify</a> or similar
tools to statically build modules using CodeMirror. Alternatively,
use <a href="http://requirejs.org/">RequireJS</a> to dynamically
load dependencies at runtime. Both of these approaches have the
advantage that they don't use the global namespace and can, thus,
do things like load multiple versions of CodeMirror alongside each
other.</p>
<p>Here's a simple example of using RequireJS to load CodeMirror:</p>
<pre data-lang="javascript">require([
"cm/lib/codemirror", "cm/mode/htmlmixed/htmlmixed"
], function(CodeMirror) {
CodeMirror.fromTextArea(document.getElementById("code"), {
lineNumbers: true,
mode: "htmlmixed"
});
});</pre>
<p>It will automatically load the modes that the mixed HTML mode
depends on (XML, JavaScript, and CSS). Do <em>not</em> use
RequireJS' <code>paths</code> option to configure the path to
CodeMirror, since it will break loading submodules through
relative pa