Newbie looking for whether Atom can do this rich text decoration


Hi Folks. I’m excited to discover Atom, and I’m thinking of applying it to a text annotation application that requires markup including:

  • set text background color
  • draw lines over and under text
  • draw borders around text
  • decorate content by overlaying lines and shapes (e.g., filled circles)
  • indicate items in a gutter

To give you an idea, it might look something like the middle pane here:

Please tell me, is this possible in Atom? Is it straightforward? I found a blog post on decorations, and the question “How to draw a box in the editor” asking about drawing a rectangle, with an answer saying to use the Decoration object, so I’m guessing the answers are both yes.

Thanks in advance!

Confused about the line between Electron and Atom
How to draw a box in the editor

You can do all of those things using Atom, yes. The background color, borders and indicating items in the gutter aspects are easiest (see the Decorations API). Drawing lines or other shapes over and under text is a bit harder, but still doable (see the pigments package for an example).


Some of what you show can be done with decorations, the old kind, not the block ones in the blog post. Some you will have to do in a transparent window over the editor. Some might be impossible.

How are you going to store the metadata? How will you edit the markup? Those are the things that seem hard to me.


Thanks very much for your replies.

@leedohm Re: pigments, I think I see what you mean: Under the ‘Marker Type’ section they have: colored background text, rects around text, underlines under (but hopefully overlines are possible too), gutter colors, and dots (though I can’t tell whether their implementation can place them arbitrarily vs. in-line). Q: Do you have a sense re: how much work it might be to do this myself?

@mark_hahn If you have time, would you please elaborate re:

  • Which features might be impossible? How does that jibe with what the pigments package has done?
  • How might these features be implemented using a transparent window? Is that a standard Atom API feature? Are there any examples?
  • Why would the ‘old kind’ of decorators be needed vs. new?
  • Re: metadata, if you mean data structures, I actually think that’s the more straightforward bit. I’m thinking lists of two kinds of Annotation objects: TextSpanAnnotation (start and end offsets, annotation type, and a list of key-value property pairs) and EntityAnnotation (sourceTextSpanAnnotation and destinationTextSpanAnnotation, and annotation type). ?
  • Editing markup: if you mean the UI mechanics of highlighting, creating a relation (line), etc, I think the UI activities I’ve come up with are not complex. They involve selecting text, popping up windows, clicking and looking up entity spans, and left and right clicks to define relations. Plus key-value properties panes on the side to edit properties. ?

Thanks again!


I must be wrong. It used to be that things like text color required using CSS on a DOM element. But when your region didn’t match an existing div, span, etc. then that wasn’t possible. But I see now that there is a type of decoration called highlight that let’s you create divs in any region. Sorry for the old information.

I’m not familiar with that package.

Features like drawing something translucent over the text require a layer above the texteditor. Also draggable things clearly need their own layer.

You mentioned seeing the new decorations in the blog. They are for making space between lines and then putting any html you want in the box. You didn’t seem to be asking for that.

I realize now that I was pretty much off-track with my reply. Sorry if I wasted your time.


To do which yourself? To use the Decorations API? Or from your other post, recreate the Decorations API in something of your own construction? Actually, I’m not sure I have a good answer in either case … though using the Decorations API is pretty simple. And definitely much simpler than trying to recreate something from scratch.


I can answer at least to your questions regarding pigments implementations.

though I can’t tell whether their implementation can place them arbitrarily vs. in-line

I’m not sure what you mean by arbitrarily versus inline, but if by arbitrarily you mean inserting the dots within the text, that’s not possible as it would require to impact the layout of the text editor’s lines.

but hopefully overlines are possible to

Sure, I just thought it wasn’t required.

Do you have a sense re: how much work it might be to do this myself?

If you want to have the same kind of implementaton as I did in pigments, it’ll probably take some time. The basic implementation to render a highlight is quite simple, but that’s how to deal with the amount to highlights to not penalize the editor that is tricky. In Pigments’ case, when you’re using all decoration types except gutter’s ones I’m using an objects pool to avoid touching the DOM too much and limiting the cost of the garbage collector passing to collect the destroyed DOM elements. Another downside to not using the native decorations is that you have to keep up-to-date with every API changes that could break your own implementation. It can be non-trivial depending the change.
Gutter decorations are the only type of decorations that uses Atom’s native decorations. All the other types use custom code due to the current limitations in how Atom deals with highlight and overlay decorations. Typically, highlight decorations can’t receive additional data or markup, and can’t change the text color, and overlay decorations are always present in the DOM, even when the region they’re attached to is outside the visible range (unless it changed recently, but I didn’t checked).

As for your case, based on the screenshot you provided, I think only the yellow line linking several annotations together would require custom decorations. Annotations themselves could be made with a mix of highligh decorations and overlay decorations (for the small red or green rectangle in the top left corner of annotations), even the outlines version could be made with highlight decorations (just use a different CSS style). The last kind of decorations, for the scrollbar, you can take inspiration in the scroll-searcher package as it looks much more closer to what you’re looking for.


Thanks very much. That definitely factors into my decision. --m