Emoji and icon

Learn how to use emoji and icon objects in the Notion API.

Emoji and icon objects represent icons on pages, databases, and callout blocks. The icon field is a discriminated union on the type key:

type	Read	Write	Description
"emoji"	Yes	Yes	A standard emoji character. See Emoji.
"custom_emoji"	Yes	Yes	A workspace custom emoji, referenced by id. See Custom emoji.
"icon"	Yes	Yes	A native Notion icon with name and color. See Icon.
"external"	Yes	Yes	An externally hosted image URL. See File object.
"file"	Yes	No	A Notion-hosted file (uploaded via the UI). Returned in responses only. See File object.
"file_upload"	No	Yes	A file uploaded via the File Upload API. Write-only. See File object.

The read/write columns above apply to page and database icons. Callout block icons support all types except file_upload on write — use emoji, external, custom_emoji, or icon instead.

---

Emoji

Example emoji object

{
  "type": "emoji",
  "emoji": "😻"
}

Field	Type	Description	Example value
type	"emoji"	The constant string "emoji" that represents the object type.	"emoji"
emoji	string	The emoji character.	"😻"

Example: set a page icon via the Create a page endpoint

cURL

curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  --data '{
  "parent": {
    "page_id": "13d6da822f9343fa8ec14c89b8184d5a"
  },
  "properties": {
    "title": [
      {
        "type": "text",
        "text": {
          "content": "A page with an avocado icon",
          "link": null
        }
      }
    ]
  },
  "icon": {
    "type": "emoji",
    "emoji": "🥑"
  }
}'

Example: set a page icon via the Update page endpoint

cURL

curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
	--data '{
  "icon": {
	  "type": "emoji",
	  "emoji": "🥨"
    }
}'

---

Custom emoji

Custom emojis are icons uploaded and managed in your workspace. Use the List custom emojis endpoint to retrieve them.

Field	Type	Description	Example value
type	"custom_emoji"	The constant string "custom_emoji" that represents the object type.	"custom_emoji"
custom_emoji	object	Object containing id, name, and url.

Example: custom emoji in a page icon response

JSON

{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  }
}

Example: inline custom emoji in rich text

JSON

{
  "type": "mention",
  "mention": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  }
}

Example: set a page icon to a custom emoji

When writing, only the id field is required inside custom_emoji.

cURL

curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
  --data '{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b"
    }
  }
}'

Example: look up a custom emoji by name

Use the name query parameter on List custom emojis to resolve a custom emoji name to its ID, then use the ID to set a page icon.

cURL

curl 'https://api.notion.com/v1/custom_emojis?name=bufo' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2026-03-11"

import { Client } from "@notionhq/client"

const notion = new Client()

const response = await notion.customEmojis.list({ name: "bufo" })
const emoji = response.results[0]

// Use the ID to set a page icon
if (emoji) {
  await notion.pages.update({
    page_id: "60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7",
    icon: {
      type: "custom_emoji",
      custom_emoji: { id: emoji.id },
    },
  })
}

Example response:

JSON

{
  "object": "list",
  "type": "custom_emoji",
  "results": [
    {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Icon

Native Notion icons are built-in icons with a name and color. They appear in the Notion UI icon picker under the “Icons” tab.

Example object

{
  "type": "icon",
  "icon": {
    "name": "pizza",
    "color": "blue"
  }
}

Field	Type	Description	Example value
type	"icon"	The constant string "icon" that represents the object type.	"icon"
icon	object	An object with name (required) and color (optional, defaults to "gray"). See below for valid values.

Icon name

When setting a native icon, the name field accepts either Notion’s internal API icon name or the name shown in the Notion icon picker tooltip. Responses return the internal API icon name.

Icon picker names are case-insensitive, and spaces, underscores, and hyphens are treated equivalently. For example, "token", "star circle", "star-circle", and "STAR_CIRCLE" set the same icon. "redirect", "arrow redirect heavy", and "arrow_redirect_heavy" also set the same icon.

Icon color

Valid color values: "gray", "lightgray", "brown", "yellow", "orange", "green", "blue", "purple", "pink", "red".

If omitted when setting an icon, the color defaults to "gray".

Example: set a page icon to a native icon

cURL

curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
  --data '{
  "icon": {
    "type": "icon",
    "icon": {
      "name": "pizza",
      "color": "blue"
    }
  }
}'

import { Client } from "@notionhq/client"

const notion = new Client()

const response = await notion.pages.update({
  page_id: "60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7",
  icon: {
    type: "icon",
    icon: { name: "pizza", color: "blue" },
  },
})