I am very curious to hear input from others on a problem I've been contemplating for some time now.

Essentially I would like to present a user with a text document and allow him/her to make selections of text and annotate it. Specific to the annotations i aim to achieve the following:

  1. Allow users to make a text selection, annotate it, then save the selection and annotation for reference later
  2. (UI) Support representing overlapped annotations. For example if the string where: "This is the test sentence for my example test sentence", user1 might have an annotation on "is the test sentence for my example" and user2 might have an annotation on "for my example".
  3. Account for a situations where the document's text changes. The annotations would to be updated, if possible.

How would you tackle this from a technical perspective?

Some ideas I've had are:

  • Use javascript ranges and store an annotation as a pair of integers something like: (document_start_char, document_end_char). Save this pair in the db.
  • Alternatively, using JS get the text selected and actually save the full text in the db. (not sure how i would then do overlapping annotations)
  • Represent overlapped annotations by applying a css style to highlight the text then darken the "stack" of annotations where they overlap. Smallest annotation would always have to be on the top of the "stack".

What are your thoughts or areas of improvement? How the heck could I support a document's text being updated without breaking all the annotations?

  • Have you seen google docs? It allows you to annotate / comment pieces of text. You can test their feature set to at least see "What's possible"
    – Raynos
    Commented Jul 4, 2011 at 18:41
  • Raynos, i have seen it but i'm looking to create my own. thanks for the heads up though. Commented Jul 5, 2011 at 17:09

3 Answers 3


You might want to take a look at Open Knowledge Foundation Annotator [ http://okfn.org/projects/annotator/ ] for inspiration, javascript library (GPL or MIT) + couchdb backend...there's also co-ment.org, marginalia which do what you describe I think

@trevor - Rangy [ https://github.com/timdown/rangy ] - a cross-browser JavaScript range and selection library - may solve the IE range selection problem - there's also a position (x,y) module in development in the demos.


Here is some code to get you started:

if (window.getSelection) {
    t = window.getSelection().toString();
} else if (document.getSelection) {
    t = document.getSelection().toString();
} else if (document.selection) {
    t = document.selection.createRange().text.toString();

Put this in a mouseup event and you can get the text for whatever's been selected. The problem I've had in the past is that while you can get the selected text, you can't get the "position" of the text in IE or the node the text is in. From quirksmode:

The Microsoft Text Range object is profoundly different from the other two, because it's string-based. In fact, it is extremely hard to jump from the string contained by Text Range to a DOM node.

I've gotten around this by making each sentence a different tag and capturing what span the mouse-up and mouse-down events occur on. Then I search for the text they've selected within those spans. It's a hack but it's worked well for me. Where it doesn't work is where users select a word or series of words that occur multiple times within a span. So I guess you could do a span on each word.

I haven't worked on this problem for maybe a year, so things may have changed and maybe my solution is not the best.

It looks like there are some good ideas here as well:


As for the overlapping, you'd probably want to have some sort of marker that shows overlapping annotations. User could click or hover the marker and see the two annotations.

  • Trevor, thanks for responding and the code snippet! How did you store your user's selections? Just the raw text? Commented Jul 5, 2011 at 17:10
  • You could store them in a JSON object. Then you could AJAX post the JSON object to the server if you wanted to persist it. Does that make sense? Where do you want to store them? On the server?
    – Trevor
    Commented Jul 5, 2011 at 18:40
  • Yeah exactly, on the server. Ideally i want to save a user's annotations then be able to show them their annotation at a later time. So i will definitely need a way to pass it around but i'm just not sure exactly what to save. I mean i could say an annotation is represented by saying something like "this annotation is a range from character number 112 to character number 200" then when displaying it... count through and change the background color for that range... OR i could do something like save the actual annotated string and send down/search for it when presenting it.... just not sure Commented Jul 6, 2011 at 17:28
  • I'm not sure either. You could put each word into a span tag and each span would have its unique id.
    – Trevor
    Commented Jul 6, 2011 at 19:25

Working on this myself, and using the OKFN Annotator mentioned above. It's non-trivial to do it right, and Annotator does it right:


As for the changing text issue: non-trivial also. Smart guy at the New York Times discusses that issue in this blog post:


Good luck.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.