Work with notes using the Excel JavaScript API

This article describes how to add, change, and remove notes in a workbook with the Excel JavaScript API. You can learn more about notes from the Insert comments and notes in Excel article. For information about the differences between notes and comments, see The difference between threaded comments and notes.

Notes are tied to an individual cell. Anyone viewing the workbook with sufficient permissions can view a note. Notes in a workbook are tracked by the Workbook.notes property. This includes notes created by users and also notes created by your add-in. The Workbook.notes property is a NoteCollection object that contains a collection of Note objects. Notes are also accessible at the Worksheet level.

Add a note

Use the NoteCollection.add method to add notes to a workbook. This method takes two parameters:

• cellAddress: The cell where the comment is added. This can either be a string or Range object. The range must be a single cell.
• content: The comment's content, as a string.

The following code sample shows how to add a note to the selected cell in a worksheet.

await Excel.run(async (context) => {
    // This function adds a note to the selected cell.
    const selectedRange = context.workbook.getSelectedRange();

    // Note that an InvalidArgument error is thrown if multiple cells are selected.
    context.workbook.notes.add(selectedRange, "The first note.");
    await context.sync();
});

Change note visibility

By default, the content of a note is hidden unless a user hovers over the cell with the note or sets the workbook to display notes. To display a note, use the Note.visible property. The following code sample shows how to change the visibility of a note.

await Excel.run(async (context) => {
    // This function sets the note on cell A1 to visible.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const firstNote = sheet.notes.getItem("A1");

    firstNote.load();
    await context.sync();

    firstNote.visible = true;
});

Edit the content of a note

To edit the content of a note, use the Note.content property. The following sample shows how to change the content of the first note in the NoteCollection.

await Excel.run(async (context) => {
    // This function changes the content in the first note.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItemAt(0);

    note.content = "Changing the content of the first note.";
    await context.sync();
});

Change the size of a note

By default, notes are automatically sized to fit the content. To make notes larger or smaller, use the Note.height and Note.width properties.

The following sample shows how to set the size of the first note in the NoteCollection.

await Excel.run(async (context) => {
    // This function changes the height and width of the first note.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItemAt(0);

    note.width = 400;
    note.height = 200;    

    await context.sync();
});

Delete a note

To delete a note, use the Note.delete method. The following sample shows how to delete the note attached to cell A2.

await Excel.run(async (context) => {
    // This function deletes the note from cell A2.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItem("A2");

    note.delete();
    await context.sync();
});

See also

• Excel JavaScript object model in Office Add-ins
• Work with workbooks using the Excel JavaScript API
• Work with comments using the Excel JavaScript API
• Insert comments and notes in Excel