Fork me on GitHub

The high performance code editor for the web.

Built for Code

ACE is an embeddable code editor written in JavaScript. It matches the features and performance of native editors such as Sublime, Vim and TextMate. It can be easily embedded in any web page and JavaScript application. ACE is maintained as the primary editor for Cloud9 IDE and is the successor of the Mozilla Skywriter (Bespin) project.

/** * In fact, you're looking at ACE right now. Go ahead and play with it! * * We are currently showing off the JavaScript mode. ACE has support for 45 * language modes and 24 color themes! */ function add(x, y) { var resultString = "Hello, ACE! The result of your math is: "; var result = x + y; return resultString + result; } var addResult = add(3, 2); console.log(addResult);

Looking for a more full-featured demo? Check out the kitchen sink.

Features

  • Syntax highlighting for over 40 languages (TextMate/Sublime/.tmlanguage files can be imported)
  • Over 20 themes (TextMate/Sublime/.tmtheme files can be imported)
  • Automatic indent and outdent
  • An optional command line
  • Handles huge documents (at last check, 4,000,000 lines is the upper limit)
  • Fully customizable key bindings including vim and Emacs modes
  • Search and replace with regular expressions
  • Highlight matching parentheses
  • Toggle between soft tabs and real tabs
  • Displays hidden characters
  • Drag and drop text using the mouse
  • Line wrapping
  • Code folding
  • Multiple cursors and selections
  • Live syntax checker (currently JavaScript/CoffeeScript/CSS/XQuery)
  • Cut, copy, and paste functionality

Get the Open-Source Code

ACE is a community project. We actively encourage and support contributions! The ACE source code is hosted on GitHub and released under the BSD license ‐ very simple and friendly to all kinds of projects, whether open-source or not. Take charge of your editor and add your favorite language highlighting and keybindings!

git clone git://github.com/ajaxorg/ace.git

History

Skywriter/Bespin and ACE started as two independent projects both aiming to build a no compromise code editor component for the web. Bespin started as part of Mozilla Labs and was based on the <canvas> tag, while ACE is the editor component of Cloud9 IDE and uses the DOM for rendering. After the release of ACE at JSConf.eu 2010 in Berlin the Skywriter team decided to merge ACE with a simplified version of Skywriter's plugin system and some of Skywriter's extensibility points. All these changes have been merged back to ACE now, which supersedes Skywriter. Both Cloud9 IDE and Mozilla are actively developing and maintaining ACE.

Related Projects

Embedding ACE in Your Site

ACE can be easily embedded into a web page. Just copy the code below:

<!DOCTYPE html> <html lang="en"> <head> <title>ACE in Action</title> <style type="text/css" media="screen"> #editor { position: absolute; top: 0; right: 0; bottom: 0; left: 0; } </style> </head> <body> <div id="editor">function foo(items) { var x = "All this is syntax highlighted"; return x; }</div> <script src="http://d1n0x3qji82z53.cloudfront.net/src-min-noconflict/ace.js" type="text/javascript" charset="utf-8"></script> <script> var editor = ace.edit("editor"); editor.setTheme("ace/theme/monokai"); editor.getSession().setMode("ace/mode/javascript"); </script> </body> </html>

Now check out the How-To Guide for instructions on common operations, such as setting a different language mode or getting the contents from the editor.

Loading ACE from a Local URL

The above code is all you need to embed ACE in your site (including setting language modes and themes). Plus it's super fast because it's on Amazon's distributed content network.

But, if you want to clone host ACE locally you can use one of the pre-packaged versions. Just copy one of src* subdirectories somewhere into your project, or use RequireJS to load the contents of lib/ace as ace:

var ace = require("lib/ace");

Working with ACE

In all of these examples ACE has been invoked as shown in the embedding guide.

Setting Themes

Themes are loaded on demand; all you have to do is pass the string name:

editor.setTheme("ace/theme/twilight");

> See all themes

Setting the Programming Language Mode

By default, the editor supports plain text mode. All other language modes are available as separate modules, loaded on demand like this:

editor.getSession().setMode("ace/mode/javascript");

Common Operations

Set and get content:

editor.setValue("the new text here"); // or session.setValue
editor.getValue(); // or session.getValue

Get selected text:

editor.session.getTextRange(editor.getSelectionRange());

Insert at cursor:

editor.insert("Something cool");

Get the current cursor line and column:

editor.selection.getCursor();

Go to a line:

editor.gotoLine(lineNumber);

Get total number of lines:

editor.session.getLength();

Set the default tab size:

editor.getSession().setTabSize(4);

Use soft tabs:

editor.getSession().setUseSoftTabs(true);

Set the font size:

document.getElementById('editor').style.fontSize='12px';

Toggle word wrapping:

editor.getSession().setUseWrapMode(true);

Set line highlighting:

editor.setHighlightActiveLine(false);

Set the print margin visibility:

editor.setShowPrintMargin(false);

Set the editor to read-only:

editor.setReadOnly(true);  // false to make it editable

Triggering Resizes

ACE only resizes itself on window events. If you resize the editor div in another manner, and need ACE to resize, use the following:

editor.resize()

Searching

editor.find('needle',{
    backwards: false,
    wrap: false,
    caseSensitive: false,
    wholeWord: false,
    regExp: false
});
editor.findNext();
editor.findPrevious();

The following options are available to you for your search parameters:

  • needle: The string or regular expression you're looking for
  • backwards: Whether to search backwards from where cursor currently is. Defaults to false.
  • wrap: Whether to wrap the search back to the beginning when it hits the end. Defaults to false.
  • caseSensitive: Whether the search ought to be case-sensitive. Defaults to false.
  • wholeWord: Whether the search matches only on whole words. Defaults to false.
  • range: The Range to search within. Set this to null for the whole document
  • regExp: Whether the search is a regular expression or not. Defaults to false.
  • start: The starting Range or cursor position to begin the search
  • skipCurrent: Whether or not to include the current line in the search. Default to false.

Here's how you can perform a replace:

editor.find('foo');
editor.replace('bar');

And here's a replace all: 

editor.replaceAll('bar');

(editor.replaceAll uses the needle set earlier by editor.find('needle', ...)

Listening to Events

To listen for an onchange:

editor.getSession().on('change', function(e) {
    // e.type, etc
});

To listen for an selection change:

editor.getSession().selection.on('changeSelection', function(e) {
});

To listen for a cursor change:

editor.getSession().selection.on('changeCursor', function(e) {
});

Adding New Commands and Keybindings

To assign key bindings to a custom function:

editor.commands.addCommand({
    name: 'myCommand',
    bindKey: {win: 'Ctrl-M',  mac: 'Command-M'},
    exec: function(editor) {
        //...
    }
});

Importing Themes and Languages

ACE supports the importing of .tmtheme and .tmlanguage files for use in the editor. The task is accomplished by two simple node scripts.

Importing Textmate/Sublime Themes

To import a .tmtheme file into ACE:

  1. Go to the tool folder, and run npm install to install required dependencies.
  2. Drop your .tmtheme file into the tmthemes folder.
  3. Update the tmtheme.js file to include your new theme.
  4. Run node tmtheme.js

Your .tmtheme will be converted and placed into lib/ace/theme alongside other themes. Note that there’s one more class we’ve added that isn’t available in regular Textmate themes, and that’s for .ace_indent-guide. This class adds indentation guides for your theme, using a base64-encoded png. In general, the dark themes and light themes each have their own strings, so you can just copy the class from an equivalent theme.

Importing Textmate/Sublime Languages

If you’re interested in porting over an existing .tmlanguage file into Ace’s mode syntax highlighting, there’s a tool to accomplish that, too.

  1. Go to the tool folder. Run npm install to install required dependencies.
  2. Drop your .tmlanguage file into the tools folder.
  3. Run node tmlanguage.js <path_to_tmlanguage_file>, such as node tmlanguage.js MyGreatLanguage.tmlanguage.

Your .tmlanguage file will be converted to the best of the converter’s ability. It is an understatement to say that the tool is imperfect. Probably, this will never be able to be fully autogenerated. In .tmlanguage files, for instance, one sees the use of lookbehinds/negative lookbehinds, which JavaScript regexps simply do not have. There’s a list of other non-determinable items, too:

  • Deciding which state to transition to
    While the tool does create new states correctly, it labels them with generic terms like state_2, state_10 e.t.c.
  • Extending modes
    Many modes say something like include source.c, to mean, “add all the rules in C highlighting.” That syntax does not make sense to Ace or this tool
  • Rule preference order
  • Gathering keywords
    Most likely, you’ll need to take keywords from your language file and run them through createKeywordMapper()

Two files are created and placed in lib/ace/mode: one for the language mode, and one for the set of highlight rules. You will still need to add the code into kitchen_sink.html and demo.js, as well as write any tests for the highlighting.

Ace API Reference

Welcome to the Ace API Reference!

On the left, you'll find a list of all of our currently documented classes. There are plenty more to do, but these represent the "core" set. For more information on how to work with Ace, check out the embedding guide.