Notion API, update the icon emoji of a page

To update the icon emoji of a Notion page, call notion.pages.update() and pass an icon object with type emoji.

The icon is the little symbol next to the page title. Setting it from code is handy when your script creates or processes pages, for example flipping a task page to ✅ when a job completes, so you can see the status at a glance in Notion.

I’ll assume you have the Notion client initialized:

import { Client } from '@notionhq/client'

//...

const notion = new Client({ auth: process.env.NOTION_API_KEY })

Let’s say the page id is stored in the page_id variable.

Then you can do this to set the value of the page icon to a new emoji:

await notion.pages.update({
  page_id: page_id,
  icon: {
    type: 'emoji',
    emoji: '✅',
  },
})

The call returns the updated page object, so you can check the result right away if you want:

const page = await notion.pages.update({
  page_id: page_id,
  icon: {
    type: 'emoji',
    emoji: '✅',
  },
})

console.log(page.icon)
//{ type: 'emoji', emoji: '✅' }

The emoji value must be a single emoji character. You can’t pass arbitrary text there, the API rejects it with a validation error.

How do I remove the icon?

Pass null as the icon value:

await notion.pages.update({
  page_id: page_id,
  icon: null,
})

The page goes back to having no icon at all.

The pitfall: object_not_found

Here’s the error that got me the first time:

APIResponseError: Could not find page with ID: ...

The page ID was correct. The problem was that the page wasn’t shared with my integration.

An integration only sees the pages you explicitly give it access to. Open the page in Notion, click the ... menu in the top right, then under Connections add your integration. Child pages inherit the connection from their parent, so sharing a top-level page is usually enough.

Once the page is connected, the same call succeeds.

Note that this updates the icon of a page. Database entries are pages too, so the exact same call works for rows in a database.