Posted on by & filed under css, ebooks, epub, geek, html5, interactivity, ipad.

iBooks now supports an extension to EPUB that allows publishers to create books with precise layout using CSS. This is Apple’s own extension, not part of the EPUB specification itself (and not one that they suggested be included in EPUB3).

The goal of this post is to simply document the extension and show how to create new works with it. I’m not going to debate whether it’s a good thing for the ecosystem here.

Install Phone Disk

Anyone working extensively with iBooks EPUB development should first grab a copy of the invaluable Phone Disk. This allows Mac and Windows computers to browse most of the iOS device filesystem as a normal drive, including opening and inspecting EPUB books.

Download a fixed-layout EPUB sample from the iBookstore

iBooks samples do not have DRM and so can be opened and read normally. A good bet is to download one of the “Children’s Picture Books”; these tend to be fixed-layout books.

Find the display-options file

The key component of the extension is the addition of the file META-INF/ This file tells iBooks that the book is the fixed-layout type, and typically looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
    <platform name="*">
        <option name="fixed-layout">true</option>

There are a number of options here which are detailed in the iBookstore Asset Guide (v4.5), including how to define two-page spreads.

The first thing I tried with one of the samples was to validate it with the latest epubcheck 1.1:

Epubcheck Version 1.1
WARNING: /Users/liza/foo.epub: item (iTunesMetadata.plist) exists in the zip file, but is not declared in the OPF file
WARNING: /Users/liza/foo.epub: item (iTunesArtwork) exists in the zip file, but is not declared in the OPF file

These are just warnings; the fixed-layout book is valid. You can try opening them in other EPUB readers, with varying success depending on how wild the book designer got with the fixed-positioning.

Inspect the OPF and NCX

One immediate surprise to iBooks developers is that you’re likely to find an embedded font (now supported in any iBooks EPUB). Otherwise there’s nothing added to the OPF.

The NCX examples I found did not include all of the XHTML pages; I’m not sure whether that’s just a function of the book being a sample.

Structure of a fixed-layout book

In a typical EPUB, each chapter or major division of content is a single XHTML file. In the fixed-layout model, each XHTML file corresponds to a single physical page. So while it’s typical to name most EPUB XHTML files like chapter01.html, chapter02.html, in the fixed-layout book you’re apt to see a layout like:

XHTML content

The one unusual element in the fixed-layout content will be this HTML, which is required:

<meta name="viewport" content="width=1000, height=1000"></meta>

The specific width/height is per-book and based on the desired dimensions of the page. iBooks uses this information to scale the screen size appropriately (more on this later).

Otherwise the XHTML should look relatively normal (other than being very short). In fact the XHTML will be exceptionally readable since these books are by necessity all hand-coded at the moment.


Here’s where things get interesting:

The body element must be defined with an absolute width/height that matches the viewport above:

body {
	width: 1000px;
	height: 1000px;

Images and text will often be absolutely-positioned. z-index and other advanced positioning techniques are also supported. Font sizes are specified in pixels, not ems (users can zoom fixed-layout books, but the text will not reflow). Background colors are useful in this model as the XHTML content is full-bleed and does not usually have the goofy fake book margin.

Since this is all standard CSS 2.1 (or CSS3), these books don’t technically require a specialized reading system; any one based on a modern browser, like the mobile version of Ibis Reader, could potentially consume these books if the reading system could scale the pages appropriately.


It’s been noted that my original JavaScript in EPUB example no longer works in more recent versions of iBooks. This had nothing to do with the JavaScript parts themselves; instead the problem was that Apple began squashing the positioning information needed to align the popups.

In recent work for publishers I’ve found ways to get around those limitations, but they’ve been quite awkward and difficult to author. Would the “freedoms” of positioning in the fixed-layout books allow the original sample to work again?


I took my original file and made only three changes:

  1. I added the file just as shown above.
  2. I added the viewport directive to the XHTML file and set it (arbitrarily to 600 pixels wide, 800 pixels tall).
  3. I modified the CSS body directive to match the viewport.

The result:

Download the example EPUB (Creative Commons Attribution-Noncommercial-Share Alike 3.0)

Obviously the layout could use some work; there’s no longer any default margin added by the ereader, so the text bleeds out. Also my 600×800 dimensions don’t exactly match the iBooks aspect ratio, so there’s more fake book border. But you can see how this could be improved.

Note that the vast majority of EPUB books should not be formatted this way. This isn’t a one-way ticket to CSS Town. If the text on a particular XHTML page overflows the bottom of the single page, it will get cut off. You cannot mix fixed-layout and reflowable pages in the same EPUB file.


23 Responses to “Understanding Apple’s fixed-layout EPUBs”

  1. lordmax

    It was interesting to this point: “You cannot mix fixed-layout and reflowable pages in the same EPUB file.”
    So if I can’t mix pages this fixed layout is totally a mess.
    I can’t waste my time for a single device, no one will pay me for this. ^___^

  2. Frank Lowney

    I’m still waiting for my copy of the iBookstore Asset Guide. It’s taking quite a while to get a response from Apple to my application. I expect that this will also be important to academic publications (journals, textbooks, etc.) as well as children’s books, magazines and newspapers that are rendered in ePub rather than as applications. It will be interesting to see if Murdoch’s “The Daily” will make use of this. There are already automated work flows for multi-column iPad web pages (see:

    I suppose that someone with a lot of time and curiosity could approach the as a “black box” investigation trying out various web techniques to see what works and what doesn’t. I suspect that a lot would work based on the suspicion that is based largely if not entirely on web kit.

  3. Keith Fahlgren

    @Frank: Yes, iBooks is based on the WebKit rendering engine, in the same way that the Safari, Mobile Safari, Blackberry 6.0, Android, and Chrome browsers are, but WebKit is just a platform rather than a finished solution, so each finished implementation can differ quite significantly (as Safari and Chrome do, for example).

  4. ronron

    Does the ipad have to be jailbroken to access sample books? In the Books.plist there is no listing for sample picture books we currently have on the ipad.
    Location for samples?

  5. Rick Gordon

    I’ve been trying to deconstruct the sample, and even after removing the meta viewport, removing body dimenstions, setting fixed-layout to false, and later removing the display-options.xml file completely, and removing any references to positioning, I still can’t get the document to revert to a standard display in iBooks (i.e., where the font menu is there).

    I’ve also checked in iTunesMetadata and Books.plist, and I can’t figure out what iBooks is continuong to reference to display this document as a (now badly screwed-up) fixed-layout document.

    I had figured that simply changing fixed-layout to false (or eliminating the line), along with possibly deleting viewport information would cause it to revert to standard behavior, but so far, I’m stumped.

  6. Rick Gordon

    My goal was to try and determine if I could induce any hybrid behavior, but I so far haven’t been able to reduce it back to standard behavior.

  7. Rick Gordon

    A little more testing on a stub document, edited on the Mac and deleted from the iPad with iTunes before each update, seems to show that absolute positioning may be working again, even with no viewport, body dimensions, or fixed-layout declaration.

  8. Waldo Jaqutih

    Thanks so much for exploring and explaining this, Liza. I hadn’t peered into fixed-layout EPUBs yet, and now I don’t need to. :)

  9. entropy

    Thanks for the helpful rundown Liza.

    To carry forward an earlier comment:
    …even with no viewport, body dimensions, or fixed-layout declaration…
    end snip

    With the same actions we have the opposite issue. No picture book interface appears at any time – standard book only; restart of ipad didn’t call the fixed layout interface either?

    What is controlling this interface call? Suggestions as to fix?

  10. ARC

    I’m developing a book using Apple’s fixed layout spec, and I want to try to make it mimic the non-fixed layout books that allow you to only see 1 page at a time in portait mode. Is there a way to do this? I can’t seem to find any documentation.

    Apple has a display option called “open-to-spread,” but that still allows you to see the full two-page spread in portrait mode, even if you set this value to false.

  11. Loki

    Thanks for the tip in the right direction. Although i’ve got stuck with regards to the content listing of my fixed layer book. Fixed Layer books list contents very differently to Floating layer books and i cant figure out how to make it work properly.

    In your sample it shows contents at the bottom of the page as tiny previews, but since its just a one page example when i added more pages i’ve ended up loosing those page previews and my books continues to turn pages indefinitely even though i only added 3 pages. What have i possibly not done when adding new pages?

  12. inctyk

    hello, i’m looking too to make a fixed layout with only seeing 1 page at a time in portait mode, and don’t find any clue. . is anyone have a solution?. thanx a lot

  13. Tilda Roekle

    Do you folks have a fb fan page? I regarded for one on twitter however could not uncover one, I would love to change into a fan!

  14. Paul Prescott

    Hmmm… I don’t see the samples in my purchased folder??? Can anyone send me a sample epub picture book that I can use as a template?

  15. Sanjeev

    script is not working for me, i have an ipad with iBooks 1.1.2.
    can anyone help me to make it work

  16. BookGenie

    Good one, i still dont get how to code the cover page to show up on ibooks. Although i tried my own trick and it works


    I actually got a book to work with this format – thanks for all your info. I did find one comment you made very interesting: “Font sizes are specified in pixels, not ems (users can zoom fixed-layout books, but the text will not reflow).” So the book looks cool & everything, but what’s the point of using this format if you can’t resize the font?

  18. kenneth krabat

    Thank you for this, Liza. So far it seems to me that the exclusion of reflowable text is a vital part of the answer to absolute positioning for the poet. All that is lacking is a flexible screen-size…!

    all the best,
    kenneth k