Overview of task pane and content add-ins

Office Add-ins

Use the JavaScript API to create task pane or content apps with the features that you want for different host applications.

Last modified: July 16, 2015

Applies to: Access apps for SharePoint | apps for Office | Excel | Office Add-ins | PowerPoint | Project | Word

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

In this article
JavaScript API support for content and task pane apps
Reading and writing to an active selection
Binding to a region in a document or spreadsheet
Getting entire documents
Reading and writing custom XML parts of a Word document
Persisting app settings
Reading properties of a project document
Permissions model and governance
In this section
Additional resources

This section briefly describes the subset of the JavaScript API for Office you can call from content and task pane apps. See Understanding the JavaScript API for Office for an overview of the features of the API. For samples, see Office Add-ins code samples.

Use the following table to explore the API by app type or by host application

Explore by app type

Explore by host application

Zoom into the Office object model for content apps

Content apps


Zoom into the object model for task pane apps

Task pane apps


Download the set of maps

for each app type and host application.




Zoom into the app object model for Excel



Zoom into the app object model for PowerPoint



Zoom into the app object model for Project



Zoom into the app object model for Word



You can categorize the primary objects and methods supported by content and task pane apps as follows:

  1. Common objects shared with other apps for Office

    These objects include Office, Context, and AsyncResult. The Office object is the root object of the JavaScript API for Office. The Context object represents the app's runtime environment. Both Office and Context are the fundamental objects for any app for Office. The AsyncResult object represents the results of an asynchronous operation, such as the data returned to the getSelectedDataAsync method, which reads what a user has selected in a document.

  2. The Document object

    The majority of the API available to content and task pane apps is exposed through the methods, properties, and events of the Document object. Using this subset of the API, your content or task pane app can perform the tasks described later in this topic.

    A content or task pane app can use the Office.context.document property to access the Document object, and through it, can access the key members of the API for working with data in documents, such as the Bindings and CustomXmlParts objects, and the getSelectedDataAsync, setSelectedDataAsync, and getFileAsync methods. The Document object also provides the mode property for determining whether a document is read-only or in edit mode, the url property to get the URL of the current document, and access to the Settings object. The Document object also supports adding event handlers for the SelectionChanged event, so you can detect when a user changes his or her selection in the document.

    A content or task pane app can access the Document object only after the DOM and run-time environment has been loaded, typically in the event handler for the Office.initialize event. For information about the flow of events when an app is initialized, and how to check that the DOM and runtime and loaded successfully, see Loading the DOM and runtime environment.

  3. Objects for working with specific features

    To work with specific features of the API, your content or task pane app can work with the following objects and methods:

    • Use the methods of the Bindings object to create or get bindings, and then work with their data using the methods and properties of the Binding object.

    • Use the CustomXmlParts, CustomXmlPart and associated objects to create and manipulate custom XML parts in Word documents.

    • Use the File and Slice objects to create a copy of the entire document, break it into chunks or "slices", and then read or transmit the data in those slices.

    • Use the Settings object to save custom data, such as user preferences, and app state.

Important note Important

Some of the API members aren't supported across all Office applications that can host content and task pane apps. To determine which members are supported, see any of the following:

For a summary of the JavaScript API for Office support available across Office host applications, see the API support matrix in Understanding the JavaScript API for Office.

You can read or write to the user's current selection in a document, spreadsheet, or presentation. Depending on the host application for your app, you can specify the type of data structure to read or write as a parameter in the getSelectedDataAsync and setSelectedDataAsync methods of the Document object. For example, you can specify any type of data (text, HTML, tabular data, or Office Open XML) for Word, text and tabular data for Excel, and text for PowerPoint and Project. You can also create event handlers to detect changes to the user's selection. The following example gets data from the selection as text using the getSelectedDataAsync method.

    Office.CoercionType.Text, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        else {
            write('Selected data: ' + asyncResult.value);

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 

For more details and examples, see Read and write data to the active selection in a document or spreadsheet.

As described in the previous section, you can use the getSelectedDataAsync and setSelectedDataAsync methods to read or write to the user’s current selection in a document, spreadsheet, or presentation. However, if you would like to access the same region in a document across sessions of running your app without requiring the user to make a selection, you should first bind to that region. You can also subscribe to data and selection change events for that bound region.

You can add a binding by using addFromNamedItemAsync, addFromPromptAsync, or addFromSelectionAsync methods of the Bindings object. These methods return an identifier that you can use to access data in the binding, or to subscribe to its data change or selection change events.

The following is an example that adds a binding to the currently selected text in a document, by using the Bindings.addFromSelectionAsync method.

    Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' +
            asyncResult.value.type + ' and id: ' + asyncResult.value.id);

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 

For more details and examples, see Bind to regions in a document or spreadsheet.

If your task pane app runs in PowerPoint or Word, you can use the Document.getFileAsync, File.getSliceAsync, and File.closeAsync methods to get an entire presentation or document.

When you call Document.getFileAsync, you get a copy of the document in a File object. The File object provides access to the document in "chunks" represented as Slice objects. When you call getFileAsync, you can specify the file type (text or compressed Open Office XML format), and size of the slices (up to 4MB). To access the contents of the File object, you then call File.getSliceAsync which returns the raw data in the Slice.data property. If you specified compressed format, you will get the file data as a byte array. If you are transmitting the file to a web service, you can transform the compressed raw data to a base64-encoded string before submission. Finally, when you are finished getting slices of the file, use the File.closeAsync method to close the document.

For more details, see how to get the whole document from an app for PowerPoint or Word.

Using the Open Office XML file format and content controls, you can add custom XML parts to a Word document and bind elements in the XML parts to content controls in that document. When you open the document, Word reads and automatically populates bound content controls with data from the custom XML parts. Users can also write data into the content controls, and when the user saves the document, the data in the controls will be saved to the bound XML parts. Task pane apps for Word, can use the Document.customXmlParts property, CustomXmlParts, CustomXmlPart, and CustomXmlNode objects to read and write data dynamically to the document.

Custom XML parts may be associated with namespaces. To get data from custom XML parts in a namespace, use the CustomXmlParts.getByNamespaceAsync method.

You can also use the CustomXmlParts.getByIdAsync method to access custom XML parts by their GUIDs. After getting a custom XML part, use the CustomXmlPart.getXmlAsync method to get the XML data.

To add a new custom XML part to a document, use the Document.customXmlParts property to get the custom XML parts that are in the document, and call the CustomXmlParts.addAsync method.

For detailed information about how to work with custom XML parts with a task pane app, see Creating Better Apps for Word with Office Open XML.

Often you need to save custom data for your app, such as a user's preferences or the app's state, and access that data the next time the app is opened. You can use common web programming techniques to save that data, such as browser cookies or HTML 5 web storage. Alternatively, if your app runs in Excel, PowerPoint, or Word, you can use the methods of the Document.Settings object. Data created with the Settings object is stored in the spreadsheet, presentation, or document that the app was inserted into and saved with. This data is available to only the app that created it.

To avoid roundtrips to the server where the document is stored, data created with the Settings object is managed in memory at runtime. Previously saved settings data is loaded into memory when the app is initialized, and changes to that data are only saved back to the document when you call the Settings.saveAsync method. Internally, the data is stored in a serialized JSON object as name/value pairs. You use the get, set, and remove methods of the Settings object, to read, write, and delete items from the in-memory copy of the data. The following line of code shows how to create a setting named themeColor and set its value to 'green'.

Office.context.document.settings.set('themeColor', 'green');

Because settings data created or deleted with the set and remove methods is acting on an in-memory copy of the data, you must call saveAsync to persist changes to settings data into the document your app is working with.

For more details about working with custom data using the methods of the Settings object, see Persisting add-in state and settings.

If your task pane app runs in Project, your app can read data from some of the project fields, resource, and task fields in the active project. To do that, you use the methods and events of the ProjectDocument object which extends the Document object to provide additional Project-specific functionality.

For examples of reading Project data, see Create your first task pane add-in for Project 2013 by using a text editor.

Your app uses the Permissions element in its manifest to request permission to access the level of functionality it requires from the JavaScript API for Office. For example, if your app requires read/write access to the document, its manifest must specify ReadWriteDocument as the text value in its Permissions element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the ReadDocument permission in a task pane's manifest.

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
…<!-- Other manifest elements omitted. -->

For more information, see Requesting permissions for API use in content and task pane add-ins.

© 2015 Microsoft