Export (0) Print
Expand All

Document.getSelectedDataAsync method (JavaScript API for Office v1.0)

JavaScript API for Office v1.0

Reads the data contained in the current selection of the document.

Last modified: June 12, 2014

Office.context.document.getSelectedDataAsync(coercionType [, options], callback); 


Type: CoercionType

The type of data structure to return. Required.


Type: object

Specifies the following optional parameters.


Type: ValueFormat

Specifies whether to return the result with its number or date values formatted or unformatted. Optional.


Type: FilterType

Specifies whether to apply filtering when the data is retrieved. Optional.

Note Note

This parameter is ignored in Word 2013, Word 2013 RT documents.


Type: array, boolean, null, number, object, string, or undefined

A user-defined item of any type that is returned in the AsyncResult object without being altered. Optional.


Type: function

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. Optional.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

In the callback function passed to the getSelectedDataAsync method, you can use the properties of the AsyncResult object to return the following information.


Use to...


Access the values in the current selection, which are returned in the data structure or format you specified with the coercionType parameter. (See Remarks for more information about data coercion.)


Determine the success or failure of the operation.


Access an Error object that provides error information if the operation failed.


Access your user-defined object or value, if you passed one as the asyncContext parameter.

In your task pane or content app, use the getSelectedDataAsync method to write script that reads the data from the user's selection in a document, spreadsheet, presentation, or project. For example, after a user selects content in a Word document, you can use the getSelectedDataAsync method to read that selection, and then submit it to a web service as a query or some other operation.

After reading the selection, you can also use the setSelectedDataAsync and addHandlerAsync methods of the Document object to write back to the selection or add an event handler to detect if the user changes the selection.

The getSelectDataAsync method can read from the selection only as long as it's active. In apps for Word and Excel, if you need to make a persistent association to read and write to the user's selection, instead use the Bindings.addFromSelectionAsync method to bind to that selection.

Use the coercionType parameter of the getSelectedDataAsync method to specify the data structure or format of the selected data being read.

Specified coercionType

Data returned

Office host application support

Office.CoercionType.Text or "text"

A string.

Word, Excel, PowerPoint, and Project.

Note Note

In Excel, even when a subset of a cell is selected, the entire cell contents are returned.

Office.CoercionType.Matrix or "matrix"

An array of arrays. For example, [['a','b'], ['c','d']] for a selection of two rows in two columns.

Word and Excel.

Office.CoercionType.Table or "table"

A TableData object for reading a table with headers.

Word and Excel.

Office.CoercionType.Html or "html"

In HTML format.

Word only.

Office.CoercionType.Ooxml or "ooxml"

In Open Office XML (OpenXML) format.

Word only.

Tip Tip

When developing your app's code, you can use the "ooxml"coercionType of the getSelectedDataAsync method to see how the content you select in a Word document is defined as OpenXML tags. Then, use those tags in the data parameter of the Document.setSelectedDataAsync method to write content with that formatting or structure to a document. For example, you can insert an image into a document as OpenXML.

If the data structure of the selection doesn't match the specified coercionType, the getSelectedDataAsync method will attempt to coerce the data into that type or structure. If the selection can't be coerced into the Office.CoercionType you specified, the AsyncResult.status property returns "failed".

To read the value of the current selection, you need to write a callback function that reads the selection. The following example shows how to:

  • Pass an anonymous callback function that reads the value of the current selection to the callback parameter of the getSelectedDataAsync method.

  • Read the selection as text, unformatted, and not filtered.

  • Display the value on the app's page.

function getText() {
        { valueFormat: "unformatted", filterType: "all" },
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(error.name + ": " + error.message);
            else {
                // Get selected data.
                var dataValue = asyncResult.value; 
                write('Selected data is ' + dataValue);

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

Supported clients

Excel 2013, Excel 2013 RT, Excel Online, Word 2013, Word 2013 RT, PowerPoint 2013, and Project 2013





© 2014 Microsoft