Edit

Pass data to a dialog box using local storage or query parameters

If your add-in runs on a platform or host that doesn't support the DialogApi 1.2 requirement set, you can't use the messageChild method to send data from a host page to a dialog box. Instead, use one of the following approaches.

  • Local storage - Write data to window.localStorage in the host page before opening the dialog. Both windows can access the same local storage if they share the same domain, including port number.
  • Query parameters - Append key-value pairs to the URL you pass to displayDialogAsync. The dialog reads the values when it opens.

For the recommended approach using messageChild, see Pass information to the dialog box.

Choose an approach

Consideration Local storage Query parameters
Data size Suitable for larger payloads. Best for small values.
Data availability Available anytime after the dialog opens. Available in the URL when the dialog loads.

Tip: Save the values to variables to read them while the dialog remains open.
Persistence across navigation Persists until explicitly cleared. Lost if the dialog redirects.

Use local storage

Call the setItem method of the window.localStorage object in the host page before the displayDialogAsync call, as shown in the following example.

localStorage.setItem("clientID", "15963ac5-314f-4d9b-b5a1-ccb2f1aea248");

Code in the dialog box reads the item when it's needed, as shown in the following example.

const clientID = localStorage.getItem("clientID");
// You can also use property syntax:
// const clientID = localStorage.clientID;

Note

Changes to browser security will affect your strategy for token handling.

  • If your add-in runs in Office on the web in the Safari browser, the dialog and task pane don't share the same local storage, so it can't be used to communicate between them.
  • Starting in Version 115 of Chromium-based browsers, such as Chrome and Edge, storage partitioning is enabled to prevent specific side-channel cross-site tracking (see also Microsoft Edge browser policies). This means that data stored by storage APIs, such as local storage, are only available to contexts with the same origin and the same top-level site. Where possible, we recommend to pass data between the dialog and task pane using the messageParent and messageChild methods as described in Use the Office dialog API in your Office Add-ins.

Use query parameters

Append key-value pairs to the URL you pass to displayDialogAsync. This approach works best for small values that the dialog needs only when it first opens.

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html?clientID=15963ac5-314f-4d9b-b5a1-ccb2f1aea248');

For a sample that uses this technique, see Insert Excel charts using Microsoft Graph in a PowerPoint add-in.

Code in your dialog box can parse the URL and read the parameter value.

Important

Office automatically adds a query parameter called _host_info to the URL passed to displayDialogAsync. It appends this parameter after your custom query parameters, if any. It doesn't append _host_info to any subsequent URLs that the dialog box navigates to. Microsoft might change the content of this value, or remove it entirely, in the future, so your code shouldn't read it. Office adds the same value to the dialog box's session storage (the Window.sessionStorage property). Again, your code should neither read nor write to this value.

Troubleshoot common issues

  • If local storage appears empty in the dialog, verify the host page and dialog use the exact same origin.
  • If a query parameter value is missing, confirm it's present in the initial URL passed to displayDialogAsync.
  • If data is needed after redirects in the dialog flow, use local storage or server state instead of relying only on query parameters.

See also

  • Last updated on