Office.Context interface

Reference

Package:: office

Represents the runtime environment of the add-in and provides access to key objects of the API. The current context exists as a property of Office. It's accessed using Office.context.

Remarks

Support details

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

Supported applications, by platform

	Office on the web	Office on Windows	Office on Mac	Office on iPad	Outlook on mobile devices
Excel	Supported	Supported	Supported	Supported	Not applicable
Outlook	Supported	Supported	Supported	Supported	Supported
PowerPoint	Supported	Supported	Supported	Supported	Not applicable
Project	Not supported	Supported	Supported	Not supported	Not applicable
Word	Supported	Supported	Supported	Supported	Not applicable

Properties

commerceAllowed	True, if the current platform allows the add-in to display a UI for selling or upgrading; otherwise returns False.
contentLanguage	Gets the locale (language) specified by the user for editing the document or item.
diagnostics	Gets information about the environment in which the add-in is running.
displayLanguage	Gets the locale (language) specified by the user for the UI of the Office application.
document	Gets an object that represents the document the content or task pane add-in is interacting with.
host	Contains the Office application in which the add-in is running.
license	Gets the license information for the user's Office installation.
mailbox	Provides access to the Microsoft Outlook add-in object model.
officeTheme	Provides access to the properties for Office theme colors.
partitionKey	Gets a partition key for local storage. Add-ins should use this partition key as part of the storage key to securely store data. The partition key is `undefined` in environments without partitioning, such as the browser controls for Windows applications.
platform	Provides the platform on which the add-in is running.
requirements	Provides a method for determining what requirement sets are supported on the current Office application and platform.
roamingSettings	Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox. The `RoamingSettings` object lets you store and access data for a mail add-in that is stored in a user's mailbox, so it's available to that add-in when it is running from any client application used to access that mailbox.
sensitivityLabelsCatalog	Gets the object to check the status of the catalog of sensitivity labels in Outlook and retrieve all available sensitivity labels if the catalog is enabled.
touchEnabled	Specifies whether the platform and device allows touch interaction. True if the add-in is running on a touch device, such as an iPad; false otherwise.
ui	Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes.
urls	Gets the object to retrieve the runtime URLs of an add-in.

Property Details

commerceAllowed

True, if the current platform allows the add-in to display a UI for selling or upgrading; otherwise returns False.

commerceAllowed: boolean;

Property Value

boolean

Remarks

Applications: Excel, Word

commerceAllowed is only supported in Office on iPad.

The iOS App Store doesn't support apps with add-ins that provide links to additional payment systems. However, Office Add-ins running in Office on the Windows desktop or in the browser do allow such links. If you want the UI of your add-in to provide a link to an external payment system on platforms other than iOS, you can use the commerceAllowed property to control when that link is displayed.

Examples

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

contentLanguage

Gets the locale (language) specified by the user for editing the document or item.

contentLanguage: string;

Property Value

string

Remarks

The contentLanguage value reflects the Editing Language setting specified with File > Options > Language in the Office application.

Support details

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

Supported applications, by platform

	Office on the web	Office on Windows	Office on Mac	Office on iPad	Outlook on mobile devices
Excel	Supported	Supported	Not supported	Supported	Not applicable
Outlook	Supported	Supported	Supported	Supported	Supported
PowerPoint	Supported	Supported	Not supported	Supported	Not applicable
Project	Not supported	Supported	Not supported	Not supported	Not applicable
Word	Supported	Supported	Not supported	Supported	Not applicable

Examples

function sayHelloWithContentLanguage() {
    const myContentLanguage = Office.context.contentLanguage;
    switch (myContentLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

Gets information about the environment in which the add-in is running.

diagnostics: ContextInformation;

Property Value

Office.ContextInformation

Remarks

Important: In Outlook, this property is available from Mailbox requirement set 1.5. For all Mailbox requirement sets, you can use the Office.context.mailbox.diagnostics property to get similar information.

Examples

const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

displayLanguage

Gets the locale (language) specified by the user for the UI of the Office application.

displayLanguage: string;

Property Value

string

Remarks

The returned value is a string in the RFC 1766 Language tag format, such as en-US.

The displayLanguage value reflects the current Display Language setting specified with File > Options > Language in the Office application.

When using in Outlook, the applicable modes are Compose or Read.

Support details

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

Supported applications, by platform

	Office on the web	Office on Windows	Office on Mac	Office on iPad	Outlook on mobile devices
Excel	Supported	Supported	Supported	Supported	Not applicable
Outlook	Supported	Supported	Supported	Supported	Supported
PowerPoint	Supported	Supported	Supported	Supported	Not applicable
Project	Not supported	Supported	Supported	Not supported	Not applicable
Word	Not supported	Supported	Supported	Supported	Not applicable

Examples

function sayHelloWithDisplayLanguage() {
    const myDisplayLanguage = Office.context.displayLanguage;
    switch (myDisplayLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

document

Gets an object that represents the document the content or task pane add-in is interacting with.

document: Office.Document;

Property Value

Office.Document

Examples

// Extension initialization code.
let _document;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Initialize instance variables to access API objects.
    _document = Office.context.document;
    });
}

host

Contains the Office application in which the add-in is running.

host: HostType;

Property Value

Office.HostType

Remarks

Important: In Outlook, this property is available from Mailbox requirement set 1.5. You can also use the Office.context.diagnostics property to get the application starting with requirement set 1.5. For all Mailbox requirement sets, you can use the Office.context.mailbox.diagnostics property to get similar information.

Examples

const host = Office.context.host;
if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
    // Do something.
} else if (host === Office.HostType.Outlook) {
    // Do something.
}

license

Gets the license information for the user's Office installation.

license: object;

Property Value

object

Examples

const license = Office.context.license;
console.log(`Office license: ${license}`);

mailbox

Provides access to the Microsoft Outlook add-in object model.

mailbox: Office.Mailbox;

Property Value

Office.Mailbox

Remarks

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Key properties:

diagnostics: Provides diagnostic information to an Outlook add-in.
item: Provides methods and properties for accessing a message or appointment in an Outlook add-in.
userProfile: Provides information about the user in an Outlook add-in.

Examples

// The following line of code access the item object of the JavaScript API for Office.
const item = Office.context.mailbox.item;

officeTheme

Provides access to the properties for Office theme colors.

officeTheme: OfficeTheme;

Property Value

Office.OfficeTheme

Examples

function applyOfficeTheme() {
    // Identify the current Office theme in use.
    const currentOfficeTheme = Office.context.officeTheme.themeId;

    if (currentOfficeTheme === Office.ThemeId.Colorful || currentOfficeTheme === Office.ThemeId.White) {
        console.log("No changes required.");
    }

    // Get the colors of the current Office theme.
    const bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
    const bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
    const controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor;
    const controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

    // Apply theme colors to a CSS class.
    $("body").css("background-color", bodyBackgroundColor);

    if (Office.context.officeTheme.isDarkTheme()) {
        $("h1").css("color", controlForegroundColor);
    }
}

partitionKey

Gets a partition key for local storage. Add-ins should use this partition key as part of the storage key to securely store data. The partition key is undefined in environments without partitioning, such as the browser controls for Windows applications.

partitionKey: string;

Property Value

string

Remarks

See the article Persist add-in state and settings for more information.

Examples

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned. 
    // If so, use the partition to ensure the data is only accessible by your add-in.
    if (myPartitionKey) {
        localStorage.setItem(myPartitionKey + key, value);
    } else {
        localStorage.setItem(key, value);
    }
}

function getFromLocalStorage(key: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned.
    if (myPartitionKey) {
        return localStorage.getItem(myPartitionKey + key);
    } else {
        return localStorage.getItem(key);
    }
}

platform

Provides the platform on which the add-in is running.

platform: PlatformType;

Property Value

Office.PlatformType

Remarks

Important:

In Outlook, this property is available from Mailbox requirement set 1.5. You can also use the Office.context.diagnostics property to get the platform starting with requirement set 1.5. For all Mailbox requirement sets, you can use the Office.context.mailbox.diagnostics property to get similar information.
In Outlook, OfficeOnline is returned if an add-is is running in Outlook on the web or in new Outlook on Windows.

Examples

// Request permission from a user to access their devices from Office on the web.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                // Do something with device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);
        });
}

requirements

Provides a method for determining what requirement sets are supported on the current Office application and platform.

requirements: RequirementSetSupport;

Property Value

Office.RequirementSetSupport

Examples

// To use the setCellProperties API, check if ExcelApi 1.9 is supported.
if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
    const cellProperties: Excel.SettableCellProperties[][] =
    colors2D.map(row =>
        row.map(color =>
            ({
                format: {
                    fill: {
                        color: color
                    }
                }
            })
        )
    );
    sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
}
...

roamingSettings

Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox.

The RoamingSettings object lets you store and access data for a mail add-in that is stored in a user's mailbox, so it's available to that add-in when it is running from any client application used to access that mailbox.

roamingSettings: Office.RoamingSettings;

Property Value

Office.RoamingSettings

Remarks

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Examples

// Get the current value of the 'myKey' setting.
const value = Office.context.roamingSettings.get('myKey');
// Update the value of the 'myKey' setting.
Office.context.roamingSettings.set('myKey', 'Hello World!');
// Persist the change.
Office.context.roamingSettings.saveAsync();

sensitivityLabelsCatalog

Gets the object to check the status of the catalog of sensitivity labels in Outlook and retrieve all available sensitivity labels if the catalog is enabled.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Property Value

Office.SensitivityLabelsCatalog

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Examples

// Check if the catalog of sensitivity labels is enabled on the current mailbox.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    // If the catalog is enabled, get all available sensitivity labels.
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                console.log(JSON.stringify(catalog));
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

touchEnabled

Specifies whether the platform and device allows touch interaction. True if the add-in is running on a touch device, such as an iPad; false otherwise.

touchEnabled: boolean;

Property Value

boolean

Remarks

Applications: Excel, PowerPoint, Word

touchEnabled is only supported in Office on iPad.

Use the touchEnabled property to determine when your add-in is running on a touch device and if necessary, adjust the kind of controls, and size and spacing of elements in your add-in's UI to accommodate touch interactions.

Examples

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

ui

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes.

ui: UI;

Property Value

Office.UI

Examples

// Open a dialog and register an event handler.
Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/myDialog.html",
    { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

urls

Gets the object to retrieve the runtime URLs of an add-in.

urls: Urls;

Property Value

Office.Urls

Remarks

Applications: Outlook on the web and on Windows (new and classic clients)

[ API set: Mailbox 1.14 ]

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Important:

In Outlook on the web and new Outlook on Windows, this API isn't supported in add-ins that implement a task pane. On these clients, the API is only supported in add-ins that implement event-based activation or integrated spam reporting.
In classic Outlook on Windows, this API is supported in add-ins that implement a task pane, event-based activation, or integrated spam reporting.

Examples

// Get the value of the first parameter of the JavaScript runtime URL.
// For example, if the URL is https://wwww.contoso.com/training?key1=value1&key2=value2,
// the following function logs "First parameter value: value1" to the console.
const url = Office.context.urls.javascriptRuntimeUrl;
const regex = /=([^&]+)/;
console.log(`First parameter value: ${url.match(regex)[1]}`);

Share via

Office.Context interface

Remarks

Properties

Property Details

commerceAllowed

Property Value

Remarks

Examples

contentLanguage

Property Value

Remarks

Examples

diagnostics

Property Value

Remarks

Examples

displayLanguage

Property Value

Remarks

Examples

document

Property Value

Examples

host

Property Value

Remarks

Examples

license

Property Value

Examples

mailbox

Property Value

Remarks

Examples

officeTheme

Property Value

Examples

partitionKey

Property Value

Remarks

Examples

platform

Property Value

Remarks

Examples

requirements

Property Value

Examples

roamingSettings

Property Value

Remarks

Examples

sensitivityLabelsCatalog

Property Value

Remarks

Examples

touchEnabled

Property Value

Remarks

Examples

ui

Property Value

Examples

urls

Property Value

Remarks

Examples

Additional resources