Settings object

Represents custom settings for a task pane or content add-in that are stored in the host document as name/value pairs.

Hosts: Access, Excel, PowerPoint, Word
Available in Requirement set Settings
Last changed in 1.1



Name Description
addHandlerAsync Adds an event handler for the settingsChanged event.
get Retrieves the specified setting.
refreshAsync Reads all settings persisted in the document and refreshes the add-in's copy of those settings held in memory.
remove Removes the specified setting.
removeHandlerAsync Removes an event handler for the settingsChanged event.
saveAsync Saves the settings.
set Sets or creates the specified setting.


Name Description
settingsChanged Occurs when a setting is changed.


The settings created by using the methods of the Settings object are saved per add-in and per document. That is, they are available only to the add-in that created them, and only from the document in which they are saved.

The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array.

The Settings object is automatically loaded as part of the Document object, and is available by calling the settings property of that object when the add-in is activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the document.

Support details

A capital Y in the following matrix indicates that this object is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this object.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
PowerPoint Y Y Y
Word Y Y Y
Available in requirement sets Settings
Add-in types Content, task pane
Library Office.js
Namespace Office

Support history

Version Changes
1.1 Added support for Excel, PowerPoint, and Word in Office for iPad.
1.1 For methods addHandlerAsync and removeHandlerAsync, added support to add and remove event handlers for the event in content add-ins for Access. For methods get, refreshAsync, remove, saveAsync, and set, added support for custom settings in content add-ins for Access.
1.0 Introduced