|
| 1 | +--- |
| 2 | +title: Work with notes using the Excel JavaScript API |
| 3 | +description: Information on using the APIs to add, remove, and edit notes. |
| 4 | +ms.date: 04/04/2025 |
| 5 | +ms.localizationpriority: medium |
| 6 | +--- |
| 7 | + |
| 8 | +# Work with notes using the Excel JavaScript API |
| 9 | + |
| 10 | +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](https://support.microsoft.com/office/bdcc9f5d-38e2-45b4-9a92-0b2b5c7bf6f8) article. For information about the differences between notes and comments, see [The difference between threaded comments and notes](https://support.microsoft.com/office/the-difference-between-threaded-comments-and-notes-75a51eec-4092-42ab-abf8-7669077b7be3). |
| 11 | + |
| 12 | +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](/javascript/api/excel/excel.notecollection) object that contains a collection of [Note](/javascript/api/excel/excel.note) objects. Notes are also accessible at the [Worksheet](/javascript/api/excel/excel.worksheet) level. |
| 13 | + |
| 14 | +> [!TIP] |
| 15 | +> To learn about adding and editing comments with the Excel JavaScript API, see [Work with comments using the Excel JavaScript API](excel-add-ins-comments.md). |
| 16 | +
|
| 17 | +## Add a note |
| 18 | + |
| 19 | +Use the `NoteCollection.add` method to add notes to a workbook. This method takes two parameters: |
| 20 | + |
| 21 | +- `cellAddress`: The cell where the comment is added. This can either be a string or [Range](/javascript/api/excel/excel.range) object. The range must be a single cell. |
| 22 | +- `content`: The comment's content, as a string. |
| 23 | + |
| 24 | +The following code sample shows how to add a note to the selected cell in a worksheet. |
| 25 | + |
| 26 | +```js |
| 27 | +await Excel.run(async (context) => { |
| 28 | + // This function adds a note to the selected cell. |
| 29 | + const selectedRange = context.workbook.getSelectedRange(); |
| 30 | + |
| 31 | + // Note that an InvalidArgument error is thrown if multiple cells are selected. |
| 32 | + context.workbook.notes.add(selectedRange, "The first note."); |
| 33 | + await context.sync(); |
| 34 | +}); |
| 35 | +``` |
| 36 | + |
| 37 | +## Change note visibility |
| 38 | + |
| 39 | +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](/javascript/api/excel/excel.note#excel-excel-note-visible-member) property. The following code sample shows how to change the visibility of a note. |
| 40 | + |
| 41 | +```js |
| 42 | +await Excel.run(async (context) => { |
| 43 | + // This function sets the note on cell A1 to visible. |
| 44 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 45 | + const firstNote = sheet.notes.getItem("A1"); |
| 46 | + |
| 47 | + firstNote.load(); |
| 48 | + await context.sync(); |
| 49 | + |
| 50 | + firstNote.visible = true; |
| 51 | +}); |
| 52 | +``` |
| 53 | + |
| 54 | +## Edit the content of a note |
| 55 | + |
| 56 | +To edit the content of a note, use the [Note.content](/javascript/api/excel/excel.note#excel-excel-note-content-member) property. The following sample shows how to change the content of the first note in the `NoteCollection`. |
| 57 | + |
| 58 | +```js |
| 59 | +await Excel.run(async (context) => { |
| 60 | + // This function changes the content in the first note. |
| 61 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 62 | + const note = sheet.notes.getItemAt(0); |
| 63 | + |
| 64 | + note.content = "Changing the content of the first note."; |
| 65 | + await context.sync(); |
| 66 | +}); |
| 67 | +``` |
| 68 | + |
| 69 | +> [!NOTE] |
| 70 | +> Use the `Note.authorName` property to get the author of a note. The author name is a read-only property. |
| 71 | +
|
| 72 | +## Change the size of a note |
| 73 | + |
| 74 | +By default, notes are automatically sized to fit the content. To make notes larger or smaller, use the [Note.height](/javascript/api/excel/excel.note#excel-excel-note-height-member) and [Note.width](/javascript/api/excel/excel.note#excel-excel-note-width-member) properties. |
| 75 | + |
| 76 | +The following sample shows how to set the size of the first note in the `NoteCollection`. |
| 77 | + |
| 78 | +```js |
| 79 | +await Excel.run(async (context) => { |
| 80 | + // This function changes the height and width of the first note. |
| 81 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 82 | + const note = sheet.notes.getItemAt(0); |
| 83 | + |
| 84 | + note.width = 400; |
| 85 | + note.height = 200; |
| 86 | + |
| 87 | + await context.sync(); |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +## Delete a note |
| 92 | + |
| 93 | +To delete a note, use the [Note.delete](/javascript/api/excel/excel.note#excel-excel-note-delete-member(1)) method. The following sample shows how to delete the note attached to cell **A2**. |
| 94 | + |
| 95 | +```js |
| 96 | +await Excel.run(async (context) => { |
| 97 | + // This function deletes the note from cell A2. |
| 98 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 99 | + const note = sheet.notes.getItem("A2"); |
| 100 | + |
| 101 | + note.delete(); |
| 102 | + await context.sync(); |
| 103 | +}); |
| 104 | +``` |
| 105 | + |
| 106 | +## See also |
| 107 | + |
| 108 | +- [Excel JavaScript object model in Office Add-ins](excel-add-ins-core-concepts.md) |
| 109 | +- [Work with workbooks using the Excel JavaScript API](excel-add-ins-workbooks.md) |
| 110 | +- [Work with comments using the Excel JavaScript API](excel-add-ins-comments.md) |
| 111 | +- [Insert comments and notes in Excel](https://support.microsoft.com/office/bdcc9f5d-38e2-45b4-9a92-0b2b5c7bf6f8) |
0 commit comments