Manage notes in Excel add-ins by using the Excel JavaScript API

Use notes when you need simple, cell-based annotations in a workbook. This article shows how to add, show, edit, resize, and delete notes by using the Excel JavaScript API.

If you need conversation threads with replies and mentions, see Manage comments in Excel add-ins by using the Excel JavaScript API. To compare the two note systems in Excel, see The difference between threaded comments and notes.

What you can do with notes

Use the Excel note APIs to:

• Add a note to a single cell.
• Show or hide note content.
• Update note text.
• Change note size.
• Delete a note.

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 note is added. This can either be a string or Range object. The range must be a single cell.
• content: The note 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.visible = true;
    await context.sync();
});

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

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

• Core Excel object model concepts for Office Add-ins
• Manage Excel workbooks with the Excel JavaScript API
• Manage comments in Excel add-ins by using the Excel JavaScript API
• Insert comments and notes in Excel