Edit

Share via

Office.OfficeTheme interface

Package:
office

Provides access to the properties for Office theme colors.

Using Office theme colors lets you coordinate the color scheme of your add-in with the current Office theme selected by the user. The user sets a theme in an Office application through File > Account or Office Account > Office Theme. The selected theme is then applied across all Office applications. Using Office theme colors is appropriate for mail and task pane add-ins.

For more information on Office themes, see Change the look and feel of Microsoft 365.

Remarks

Supported applications, by platform

Office on the web Office on Windows Office on Mac Office on iOS Office on Android
Excel Supported Supported Supported Supported Not available
Outlook Supported Supported Supported Not available Not available
PowerPoint Supported Supported Supported Supported Not available
Word Supported Supported Supported Supported Not available

Important: In Outlook, the Office theme API is supported starting in Mailbox requirement set 1.14. It isn't supported in Outlook add-ins that implement event-based activation.

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);
    }
}

Properties

bodyBackgroundColor

Gets the Office theme body background color as a hexadecimal color triplet (e.g., "#FFA500").
bodyForegroundColor

Gets the Office theme body foreground color as a hexadecimal color triplet (e.g., "#FFA500").
controlBackgroundColor

Gets the Office theme control background color as a hexadecimal color triplet (e.g., "#FFA500").
controlForegroundColor

Gets the Office theme control foreground color as a hexadecimal color triplet (e.g., "#FFA500").
fluentThemeData

Gets the Office host native theme.
isDarkTheme

Returns true if the Office theme that's currently selected is Black (dark mode) or Dark Gray.
themeId

Gets the Office theme that's currently selected.

Property Details

bodyBackgroundColor

Gets the Office theme body background color as a hexadecimal color triplet (e.g., "#FFA500").

bodyBackgroundColor: string;

Property Value

string

bodyForegroundColor

Gets the Office theme body foreground color as a hexadecimal color triplet (e.g., "#FFA500").

bodyForegroundColor: string;

Property Value

string

controlBackgroundColor

Gets the Office theme control background color as a hexadecimal color triplet (e.g., "#FFA500").

controlBackgroundColor: string;

Property Value

string

controlForegroundColor

Gets the Office theme control foreground color as a hexadecimal color triplet (e.g., "#FFA500").

controlForegroundColor: string;

Property Value

string

fluentThemeData

Gets the Office host native theme.

fluentThemeData?: object;

Property Value

object

Remarks

Important: The fluentThemeData property is only supported on the Excel, PowerPoint, and Word desktop clients for Windows.

isDarkTheme

Returns true if the Office theme that's currently selected is Black (dark mode) or Dark Gray.

isDarkTheme: boolean;

Property Value

boolean

Remarks

Important: The isDarkTheme property isn't supported in Outlook. To determine the current theme in Outlook, use the body*Color and control*Color properties instead. To automatically detect theme changes, use the addHandlerAsync method to create an event handler for the OfficeThemeChanged event.

themeId

Gets the Office theme that's currently selected.

themeId: ThemeId;

Property Value

Office.ThemeId

Remarks

Important: The themeId property isn't supported in Outlook. To determine the current theme in Outlook, use the body*Color and control*Color properties instead. To automatically detect theme changes, use the addHandlerAsync method to create an event handler for the OfficeThemeChanged event.