Create HTML5 widgets for iBooks Author

Learn how to make HTML5 widgets that you can use in the books that you create in iBooks Author.

iBooks Author supports HTML5 widgets, which have the filename extension .wdgt. To make an HTML5 widget, use a text editor or content creation app to create these three files:

Main HTML file: This file is the main part of the widget. It can have any name you like, but its extension must be .html. You can put CSS and JavaScript inside the main HTML file. Or, you can add .css and .js files to the widget bundle and load them from the main HTML file. You can use any technique that you'd use to design a webpage. Use HTML to define the widget’s structure, CSS to provide the visual style, and JavaScript to make it interactive.

Default.png file: The easiest way to create a Default.png is to take a screenshot of your main HTML file in a web content creation app or web browser. This is the image that readers see on the page and tap to open the widget. In a web browser or web content creation app, take a screenshot of your main HTML file. Name it “Default.png,” and be sure to use a capital letter "D." When your widget is active, it's the size of the Default.png file. You can change its size in the Info.plist file.

Info.plist file: This file gives iBooks Author and Apple Books the information that they need to run your widget. The filename must be "Info.plist."

After you create these required files, create any optional files that you want, like CSS or JavaScript files. Then, add them all to a widget bundle:

In the Finder, create a folder.

Add the files to your new folder.

Rename the folder and add a .wdgt extension to the folder name to create the widget bundle. The folder icon changes to a widget icon.

Tips for creating widgets

If you set your widget to play automatically, it can't access the Internet.

Don't use custom folder icons, and avoid these folder names in your widget:

Resources/

Support Files/Resources/

Contents/Resources/

To optimize your widget for a Retina display:

In your HTML, CSS, and JavaScript files, use the standard protocol for websites with Retina (2x) graphics.

Include a Default@2x.png file in your widget. Make the file twice the resolution of the Default.png file. You can't see this file in iBooks Author, but you can see it in Apple Books on a Retina display.

Key restrictions and limitations

Widgets in books created with iBooks Author can't access files in the general file system.

AllowFullAccess

Shorthand for a list of other access keys, some of which aren't compatible.

AllowInternetPlugins

Internet plugins, such as Flash, are unavailable in books created with iBooks Author. You can include movies and audio using the HTML5 <video> and <audio> elements.
Movies and audio inside of HTML widgets won't be DRM-protected.

AllowJava

Widgets in books created with iBooks Author can't include Java content.

AllowSystem

Widgets in the books created with iBooks Author can't access system commands.

Plugin

Widgets in books created with iBooks Author can't include a Cocoa plugin component.

iBooks Author ignores these keys:

Key

Description

CloseBoxInsetX

Widgets in iBooks Author and Apple Books don't display a close decoration.

CloseBoxInsetY

Fonts

iBooks Author widgets can't use bundled fonts.

Video and audio requirements

You can't use media that has .m4v or .m4p file extensions. Use one of these formats with an .mp4 file extension:

H.264 video: Up to 720p, 60 frames per second. High Profile level 4.2 with AAC-LC audio up to 160 kbps, 48 kHz, stereo audio. Videos that open in iMovie 10 with the HD 720p option use these settings.

For audio, use AAC (8 to 320 Kbps, 48 kHz stereo) with an .m4a file extension.

Video and audio media in HTML widget bundles aren't DRM-protected.

If a movie or audio file doesn't play in your widget in iBooks Author, preview it on your iPhone, iPad or Mac. This shows how the file will play in your completed book.

Localization

iBooks Author doesn't support localized strings and assets. Include text strings in the target language that the reader can see inline.

Fix clipped elements

An element, such as <video>, might appear clipped on one side. This can happen if its dimensions are larger than the available space. Find the CSS for "width:auto" in the #video selector and change it to reflect the actual dimensions. For example, your widget might contain a video whose dimensions are 960 x 540. Check the CSS for the relevant selector and set the width and height to the correct values:

#video {
width: 960;
height: 540;
}

Develop for iOS and macOS

iOS and macOS use different input types. You can accommodate both touch and mouse input when you create your HTML widgets for iBooks Author.

Avoid a flash when readers open the HTML widget

If your HTML widget is very complicated, your readers might see a flash when they open it in Apple Books. To avoid this, update your widget to tell Apple Books when to switch from the Default.png file to the HTML widget:

1. Add an "IBNotifiesOnReady" item that's set to true in the widget's Info.plist file. This lets Apple Books know that the widget will tell it when to switch to the HTML widget.

<key>IBNotifiesOnReady</key>
<true/>

2. Set your widget to load the Apple JavaScript library in the <head> portion of the HTML file: