Posted on by & filed under css, epub, ibooks, interactivity, ipad.

Note: As of iBooks 1.1.2 (December 2010) this example no longer works, though JavaScript is still supported. I’m hoping to post an updated example soon.

iBooks supports JavaScript-based interactivity in EPUB content.

I took some content from Cooking with Booze by James Bridle (a.k.a. George Harvey Bone). It’s released under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 license, which means that this derivative work is as well.

I took one recipe and marked it up in EPUB:

I added some slightly useless annotations and illustrative images from Flickr (also under an Attribution license). I then added some JavaScript-based event handlers. If you tap on the hyperlinked items in the recipe, the annotation will fade in as a popup. Tap on the annotation to dismiss it.

There are two kinds of annotations available: image popups and textual notes. Here’s a text note:

The JavaScript here is extremely simple, though I needed to use webkitTransform rather than normal positioning code because iBooks does not recognize position: absolute and the like:

function popup() {
  var p = document.getElementById( + '-popup');
  var top_of_el = this.offsetTop; = 1;
  var new_y = p.offsetTop - top_of_el - 30; = 'translateY(-' + new_y + 'px) translateX(' + this.offsetLeft + 'px)';
function dismiss() { = 0;
  var el = this;
  setTimeout(function () { = null;
  }, 1000);
/* Register the events */
var terms = document.getElementsByClassName('term');
for (var i=0; i < terms.length; i++) {
  terms[i].addEventListener('click', popup);
var popups = document.getElementsByClassName('popup');
for (var i=0; i < popups.length; i++) {
  popups[i].addEventListener('click', dismiss);

Here’s a sample of the XHTML:

1 wild <a class="term" id="turkey">turkey</a> breast

Some other nerdy details:

  1. The fade-in effect uses CSS3. I think the iBooks implementation may not be hardware-accelerated like Mobile Safari — it’s less smooth than the transitions on Ibis Reader, for example.
  2. Inline script blocks do not work, which is not a bad thing.
  3. Scripts are disallowed from accessing remote URLs. This means that ebooks that interact with remote data, like the geo-aware ebook, do not work. Interestingly, this is one of the restrictions that Baldur Bjarnason suggested might allow for safe JavaScript use in ebooks in a recent comment on our post Practical Interactivity and Shaping the Future of EPUB.
  4. iBooks caching is really annoying isn’t it?
  5. I haven’t tried this on iBooks for iPhone.
  6. I have no idea if JavaScript is allowed in the iBookstore…
  7. …not that you need Apple’s permission to sell a DRM-free enhanced EPUB that users could load into iBooks themselves.

Download the sample EPUB book. All content in the book is licensed under a Creative Commons license of some kind; the whole bundle should be considered Creative Commons Attribution-Noncommercial-Share Alike 3.0.

That said, I encourage commercial publishers to explore interactivity in EPUB, and it goes without saying that we’d love to help, whether it’s to provide glosses and annotations like those shown here, or interactive quizzes, or animation, or…


40 Responses to “JavaScript and interactivity in iBooks”

  1. Marcio Duarte

    This is really nice, thank you for sharing this! I know the code have some webkit specifics, but there’s any alternative way to make this work in ADE?

  2. Liza Daly

    Joseph: I think it might open the popup on the original page, which is at the end of the document.

    I’m looking forward to seeing how Monocle develops!

  3. Frank Lowney

    This is a very cool demo.

    On iPad with iBook 1.1, I get a blue line wherever I tap. Avoiding that would increase the elegance of this approach.

    The honey link does not have an image.

    Attempting to open and inspect the code in Sigil 0.2.3 caused it to crash.

    Ninetheless, I really liked it.

  4. Liza Daly

    On iPad with iBook 1.1, I get a blue line wherever I tap. Avoiding that would increase the elegance of this approach.

    Hopefully at some point Apple will publish a design document that will make it clear what aspects of the iBooks UI are customizable, and with what CSS.

    The honey link does not have an image.

    Works for me.

    Attempting to open and inspect the code in Sigil 0.2.3 caused it to crash.

    It’s a valid EPUB so that is a bug in Sigil.

  5. Kamal

    Increasing the font I experienced problems to see the turkey img. Follow these steps: tap 2 times on the font magnifier and tap on the img link. Do yoo see the turkey?

  6. David Gray

    This would be useful for footnotes. Current footnote/endnote implementation in ePub books I’ve read so far is pretty clunky for the reader.

  7. Peter Schoppert

    Agree that a Javascript call works well for footnotes, and then of course it could be a way to pull in 3rd-party annotations (kept in a separate xhtml file within the epub package?) But as things stand now, this doesn’t even work consistently across iBooks on iPhone and iPad… which is too bad because I think there would be publishers willing to follow Virgina Quarterly Review and develop ebooks for Apple ecosystem. Liz, Joseph, did you get to bottom of iPhone issue?

    Also wouldn’t it be more consistent if the annotation faded out when you touch “outside” the annotation, as per Apple’s UI guidelines for popups? Or did that complicate the Javascript too much, to listen for clicks outside the annotation?

  8. Liza Daly

    Peter: This is just a proof-of-concept and an opportunity for others to experiment. Until Apple provides some public guidelines or an API, I’m not planning on doing much further exploration.

    iBooks is shifting quickly and doing multiple iterations on what’s essentially a black box strikes me as a waste of time (I had to make some last-minute changes to accommodate iBooks 1.1 when the demo was first developed for 1.0, for example).

    I do hope they retain the support, and to that end I’d like to see more people experimenting, but at this time trying to get a stable, fully-interactive book product would result in coding to a lot of bugs and edge cases, which is what we’re seeing right now with people trying to have explicit control over their iBooks CSS.

  9. HKd

    Does anybody know whether iBooks supports ‘mailto’ links? I tried to make one and it did not…

  10. Gerald Schmidt

    Hi Liza

    Thanks for sharing the ebook. The main problem I find is that this technique only works if the popup link is on the first page shown of the ePub.

    It’s the same for video, which works brilliantly on p. 1 and fails on later pages. It’s possible that this would work on p. 1 of all HTML chapters embedded in the ePub, but even then it’s not ideal having to chop up one’s content just so interactive content is shown.

    iBooks 1.1 solved a lot of issues (e.g. refreshing table rows on the second page in landscape mode when javascript-sorting tables), but this one will need more work.


  11. louis

    Dear Liza,

    Thanks for your good information and samples. In your comment about test you mentioned that “iBooks does not recognize position: absolute”.

    If I use that tag for CSS or in Script, is that going to cause mal-function of interectivity in ePub book?

    I also tried to use some Script, and tested in iBooks, but didn’t work like planned. with Safari, I think, that planned interectivity is quite good, but not in iBooks.


  12. Liza Daly


    The epub specification itself discourages the use of absolute positioning since it conflicts with the preference for reflowability.

  13. Jodi Schneider

    In Stanza on the iphone, the annotations are pushed to the end of the document. The beginning of the document says:
    Time-stamp: <2010-06-24-11:17:34-liza&rt;

  14. sara

    I have the same problem about the tooltip windown in the iBook in iPod touch( iOS 4, already, and ibook l.1.2)

    When I clicked the links, it’s just nothing happend. I tried to decompile the epub to folder then rebuilt via Calibre again. The result is the same which made me sooo disappointed since I’ve complained to a book forum about I’d rather using html files in a folder rather than a epub for months.

    I have no idea why it doesn’t work in touch/iphone? Would you please test it on iphone, if it doen’t too trouble. I’m new here, but after reading lots of articles here, I’m much impressed by Liza. Although I lost my faith in epub a little bit, but I like reading this blog.

  15. Liza Daly

    Sara: I recommend waiting for Apple to formally sanction this approach and provide JavaScript guidelines.

  16. Jacobus

    Dear Liza,

    Thank you for the informative demos and code.

    Will you mind sharing some information regarding the use of SVG in ePub. I’m particularly interested in the level of SVG support, e.g. fonts, animation, filters, etc and also interactivity using javascript. SVG just makes better sense than flash since it’s open and XML and plays nicely with XHTML, CSS etc.

    Kind regards,

  17. Tony

    Thanks for sharing.
    Apart from the pre-mentioned issue with this only working on the 1st page, I wonder if there is a way to tailor it so it can work anywhere on that page. Currently the popup get progressively smaller as it moves down and across the page effectively cutting off content. Also, I wish I could scale the text and/or box so it could fit all of the text. I tried using position:fixed to get a consistent size but couldn’t get it to work. Would appreciate any comments on this.

  18. David Cizek

    I am definitelly impressed by this blog and Lisa’s work. Thanks a lot.

    In the comments Gerald mentioned video – please, have you some examples?

  19. Martin Bayly

    Should this work in Ibis Reader on the desktop? – I tried uploading the epub to my Ibis Reader account accessed through Chrome on Windows. None of the interactions work. It looked like the tag was removed.
    Just that you mentioned that on iBook the transitions were less smooth than the transitions on Ibis Reader

  20. Martin Bayly

    In previous comment meant to say it looked like the <script> tag was removed.

  21. Liza Daly

    Martin: You’re right, it shouldn’t work in Ibis as we do deliberately disable scripts.

    My comparison was based on the transitions that Ibis Reader uses for its own interface (like menus), not based on what was added to a book.

  22. Julien

    Liza, I just checked your code, and the slowdown could very well be because of the use of TranslateY / TranslateX instead of Translate3D:

    «When using -webkit-transform, be sure to use the translate3d(x,y,z) syntax, instead of using translate(x,y). For some reason, the latter is not hardware-accelerated, at least not on iPhone OS 3.x »

    From Paragraph 7. there : (a nice post by the javascript guru Thomas Fuchs :-)

    Also, he points to Opacity, that you also use in your code, as a possible culprit «For some reason, using the opacity CSS property sometimes interferes with hardware-accelerated rendering, so if you experience slowdowns and think you’re doing everything right, see if you have opacity set somewhere.»

  23. Liza Daly

    Hi Julien,

    Opacity changes via CSS transitions _are_ hardware-accelerated on Mobile Safari. Same with translateX — that was fixed in (I believe) iPhone OS 3.2.

  24. Julien

    Thanks Liza, that’s good to know that it’s fixed! Let’s just hope iBooks use the stock webkit and not some kind of dumbed down fork.

    Some time after I posted my comment, I quickly tried your code without opacity (using visible) and with translate3D, and it indeed doesn’t react faster at all after the touch event. But as there is no more transition, we gain the transition time, so it’s perceptually a little bit quicker.

    Anyway, thanks a lot for these nice experiments — I surely now want to try a few other things with CSS and Javascript in iBooks :-) And let push some of these experimentations to the iBookstore, because, contrary to the popular belief, Apple listen… well, they sometimes listen!

    (Sorry that I didn’t came back to say so earlier… it was a quick experiment late at night, and the next morning I had totally forgotten)

  25. Raju Chakraborty

    I found quite a few problems in trying this in one of our iBooks for iPad. I found it to be working on the first page and not to be working on pages thereafter. Another problem I saw is that if the clickable object is at the page end it only shows the part of the pop up box, based on the bottom space available on that particular page. It doesn’t turns the page over or the pop up box doesn’t appear above the clickable object.
    I also require some hints on how to animate text (fly, say from top to bottom) on iPad through Javascript. My code is working fine on the browser but not working in iPad. Is the application in iPad still not that smart?


  1.  Practical Interactivity and Shaping the Future of EPUB : Threepress Consulting blog
  2.  Планета е-книг » Blog Archive » Text 2.0 на основе JavsScript
  3.  Stop Press for June 24th |
  4.  Morning Links 25 June 2010 | The Digital Reader
  5.  iPad – iBooks
  6.  아이폰&아이패드가 열어준 새로운 방식의 미디어 소비방법 | Guru's Blog
  7.  iPhone版iBooksでの写真や表の見え方 « ECollab Ltd.
  8.  Easier EPUB Experimenting and Updating in iBooks : Threepress Consulting blog
  9.  Pumping Irony » Investigating MOBI