Rich text object

Rich text objects contain the data that Notion uses to display formatted text, mentions, and inline equations. Arrays of rich text objects within database property objects and page property value objects are used to create what a user experiences as a single text value in Notion.

An example rich text object

{
  "type": "text",
  "text": {
    "content": "Some words ",
    "link": null
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "Some words ",
  "href": null
}

Each rich text object contains the following fields.

Field	Type	Description	Example value
`type`	`string` (enum)	The type of this rich text object. Possible type values are: `"text"`, `"mention"`, `"equation"`.	`"text"`
`text`	`mention`	`equation`	`object`
`annotations`	`object`	The information used to style the rich text object. Refer to the annotation object section below for details.	Refer to the annotation object section below for examples.
`plain_text`	`string`	The plain text without annotations.	`"Some words "`
`href`	`string` (optional)	The URL of any link or Notion mention in this text, if any.	`"https://www.notion.so/Avocado-d093f1d200464ce78b36e58a3f0d8043"`

The annotation object

All rich text objects contain an annotations object that sets the styling for the rich text. annotations includes the following fields:

Property	Type	Description	Example value
`bold`	`boolean`	Whether the text is bolded.	`true`
`italic`	`boolean`	Whether the text is italicized.	`true`
`strikethrough`	`boolean`	Whether the text is struck through.	`false`
`underline`	`boolean`	Whether the text is underlined.	`false`
`code`	`boolean`	Whether the text is `code style`.	`true`
`color`	`string` (enum)	Color of the text. Possible values include: - `"blue"` - `"blue_background"` - `"brown"` - `"brown_background"` - `"default"` - `"gray"` - `"gray_background"` - `"green"` - `"green_background"` - `"orange"` -`"orange_background"` - `"pink"` - `"pink_background"` - `"purple"` - `"purple_background"` - `"red"` - `"red_background”` - `"yellow"` - `"yellow_background"`	`"green"`

Rich text type objects

Equation

Notion supports inline LaTeX equations as rich text object’s with a type value of "equation". The corresponding equation type object contains the following:

Field	Type	Description	Example value
`expression`	`string`	The LaTeX string representing the inline equation.	`"\frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}"`

Example rich text `equation` object

JSON

{
  "type": "equation",
  "equation": {
    "expression": "E = mc^2"
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "E = mc^2",
  "href": null
}

Mention

Mention objects represent an inline mention of a database, date, link preview mention, page, template mention, or user. A mention is created in the Notion UI when a user types @ followed by the name of the reference.

If a rich text object’s type value is "mention", then the corresponding mention object contains the following:

Field	Type	Description	Example value
`type`	`string` (enum)	The type of the inline mention. Possible values include: - `"database"` - `"date"` - `"link_preview"` - `"page"` - `"template_mention"` - `"user"`	`"user"`
`database`	`date`	`link_preview`	`page`

Database mention type object

Database mentions contain a database reference within the corresponding database field. A database reference is an object with an id key and a string value (UUIDv4) corresponding to a database ID.

If an integration doesn’t have access to the mentioned database, then the mention is returned with just the ID. The plain_text value that would be a title appears as "Untitled" and the annotation object’s values are defaults.

Example rich text mention object for a database mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "database",
    "database": {
      "id": "a1d8501e-1ac1-43e9-a6bd-ea9fe6c8822b"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "Database with test things",
  "href": "https://www.notion.so/a1d8501e1ac143e9a6bdea9fe6c8822b"
}

Date mention type object

Date mentions contain a date property value object within the corresponding date field.

Example rich text mention object for a date mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "date",
    "date": {
      "start": "2022-12-16",
      "end": null
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "2022-12-16",
  "href": null
}

Link Preview mention type object

If a user opts to share a Link Preview as a mention, then the API handles the Link Preview mention as a rich text object with a type value of link_preview. Link preview rich text mentions contain a corresponding link_preview object that includes the url that is used to create the Link Preview mention.

Example rich text mention object for a link_preview mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "link_preview",
    "link_preview": {
      "url": "https://workspace.slack.com/archives/C04PF0F9QSD/z1671139297838409?thread_ts=1671139274.065079&cid=C03PF0F9QSD"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "https://workspace.slack.com/archives/C04PF0F9QSD/z1671139297838409?thread_ts=1671139274.065079&cid=C03PF0F9QSD",
  "href": "https://workspace.slack.com/archives/C04PF0F9QSD/z1671139297838409?thread_ts=1671139274.065079&cid=C03PF0F9QSD"
}

Page mention type object

Page mentions contain a page reference within the corresponding page field. A page reference is an object with an id property and a string value (UUIDv4) corresponding to a page ID.

If an integration doesn’t have access to the mentioned page, then the mention is returned with just the ID. The plain_text value that would be a title appears as "Untitled" and the annotation object’s values are defaults.

Example rich text mention object for a page mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "page",
    "page": {
      "id": "3c612f56-fdd0-4a30-a4d6-bda7d7426309"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "This is a test page",
  "href": "https://www.notion.so/3c612f56fdd04a30a4d6bda7d7426309"
}

Template mention type object

The content inside a template button in the Notion UI can include placeholder date and user mentions that populate when a template is duplicated. Template mention type objects contain these populated values.

Template mention rich text objects contain a template_mention object with a nested type key that is either "template_mention_date" or "template_mention_user".

If the type key is "template_mention_date", then the rich text object contains the following template_mention_date field:

Field	Type	Description	Example value
`template_mention_date`	`string` (enum)	The type of the date mention. Possible values include: `"today"` and `"now"`.	`"today"`

Example rich text mention object for a template_mention_date mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "template_mention",
    "template_mention": {
      "type": "template_mention_date",
      "template_mention_date": "today"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "@Today",
  "href": null
}

If the type key is "template_mention_user", then the rich text object contains the following template_mention_user field:

Field	Type	Description	Example value
`template_mention_user`	`string` (enum)	The type of the user mention. The only possible value is `"me"`.	`"me"`

Example rich text mention object for a template_mention_user mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "template_mention",
    "template_mention": {
      "type": "template_mention_user",
      "template_mention_user": "me"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "@Me",
  "href": null
}

User mention type object

If a rich text object’s type value is "user", then the corresponding user field contains a user object.

📘
If your integration doesn’t yet have access to the mentioned user, then the plain_text that would include a user’s name reads as "@Anonymous". To update the integration to get access to the user, update the integration capabilities on the integration settings page.

Example rich text mention object for a user mention

JSON

{
  "type": "mention",
  "mention": {
    "type": "user",
    "user": {
      "object": "user",
      "id": "b2e19928-b427-4aad-9a9d-fde65479b1d9"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "@Anonymous",
  "href": null
}

Text

If a rich text object’s type value is "text", then the corresponding text field contains an object including the following:

Field	Type	Description	Example value
`content`	`string`	The actual text content of the text.	`"Some words "`
`link`	`object` (optional)	An object with information about any inline link in this text, if included. If the text contains an inline link, then the object key is `url` and the value is the URL’s string web address. If the text doesn’t have any inline links, then the value is `null`.	`{ "url": "https://developers.notion.com/" }`

Example rich text `text` object without link

JSON

{
  "type": "text",
  "text": {
    "content": "This is an ",
    "link": null
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "This is an ",
  "href": null
}

Example rich `text` text object with link

JSON

{
  "type": "text",
  "text": {
    "content": "inline link",
    "link": {
      "url": "https://developers.notion.com/"
    }
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  },
  "plain_text": "inline link",
  "href": "https://developers.notion.com/"
}

📘Rich text object limits
Refer to the request limits documentation page for information about limits on the size of rich text objects.

The annotation object#

Rich text type objects#

Equation#

Example rich text equation object#

Mention#

Database mention type object#

Date mention type object#

Link Preview mention type object#

Page mention type object#

Template mention type object#

User mention type object#

📘#

Text#

Example rich text text object without link#

Example rich text text object with link#

📘Rich text object limits#

The annotation object

Rich text type objects

Equation

Example rich text `equation` object

Mention

Database mention type object

Date mention type object

Link Preview mention type object

Page mention type object

Template mention type object

User mention type object

📘

Text

Example rich text `text` object without link

Example rich `text` text object with link

📘Rich text object limits