richText

const richText: (content) => RichTextBuilder & object

Defined in: src/helpers/richText.helpers.ts:312

Factory function for creating Notion rich text, with static helpers for mentions, equations, and joining multiple segments.

Type Declaration

equation

equation: (expression) => RichTextBuilder

Create an equation (LaTeX) rich text segment.

Parameters

expression

string

Returns

RichTextBuilder

join

join: (…parts) => ({ annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; plain_text: string; text: { content: string; link: { url: string; } | null; }; type: "text"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; mention: { database: { id: string; }; type: "database"; } | { date: { end: string | null; start: string; time_zone?: string | null; }; type: "date"; } | { link_preview: { url: string; }; type: "link_preview"; } | { page: { id: string; }; type: "page"; } | { template_mention: { template_mention_date: … | …; type: "template_mention_date"; } | { template_mention_user: "me"; type: "template_mention_user"; }; type: "template_mention"; } | { type: "user"; user: { avatar_url?: … | … | …; id: string; name?: … | …; object: "user"; person: { email: …; email_verified?: …; }; type: "person"; } | { avatar_url?: … | … | …; bot: { owner: …; workspace_id?: …; workspace_limits?: …; workspace_name?: …; }; id: string; name?: … | …; object: "user"; type: "bot"; } | { id: string; object: "user"; }; }; plain_text: string; type: "mention"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; equation: { expression: string; }; href: string | null; plain_text: string; type: "equation"; })[]

Combine multiple rich text builders (or pre-built NotionRichText values) into a single NotionRichText.

Parameters

parts

…(({ annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; plain_text: string; text: { content: string; link: { url: …; } | null; }; type: "text"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; mention: { database: { id: …; }; type: "database"; } | { date: { end: …; start: …; time_zone?: …; }; type: "date"; } | { link_preview: { url: …; }; type: "link_preview"; } | { page: { id: …; }; type: "page"; } | { template_mention: … | …; type: "template_mention"; } | { type: "user"; user: … | … | …; }; plain_text: string; type: "mention"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; equation: { expression: string; }; href: string | null; plain_text: string; type: "equation"; })[] | RichTextBuilder)[]

Returns

({ annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; plain_text: string; text: { content: string; link: { url: string; } | null; }; type: "text"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; href: string | null; mention: { database: { id: string; }; type: "database"; } | { date: { end: string | null; start: string; time_zone?: string | null; }; type: "date"; } | { link_preview: { url: string; }; type: "link_preview"; } | { page: { id: string; }; type: "page"; } | { template_mention: { template_mention_date: … | …; type: "template_mention_date"; } | { template_mention_user: "me"; type: "template_mention_user"; }; type: "template_mention"; } | { type: "user"; user: { avatar_url?: … | … | …; id: string; name?: … | …; object: "user"; person: { email: …; email_verified?: …; }; type: "person"; } | { avatar_url?: … | … | …; bot: { owner: …; workspace_id?: …; workspace_limits?: …; workspace_name?: …; }; id: string; name?: … | …; object: "user"; type: "bot"; } | { id: string; object: "user"; }; }; plain_text: string; type: "mention"; } | { annotations: { bold: boolean; code: boolean; color: "default" | "blue" | "blue_background" | "brown" | "brown_background" | "gray" | "gray_background" | "green" | "green_background" | "orange" | "orange_background" | "pink" | "pink_background" | "purple" | "purple_background" | "red" | "red_background" | "yellow" | "yellow_background"; italic: boolean; strikethrough: boolean; underline: boolean; }; equation: { expression: string; }; href: string | null; plain_text: string; type: "equation"; })[]

Example

richText.join(
  richText('Hello '),
  richText('world').bold(),
  richText('!'),
);

mentionDatabase

mentionDatabase: (databaseId) => RichTextBuilder

Create a mention of a Notion database.

Parameters

databaseId

string

Returns

RichTextBuilder

mentionDate

mentionDate: (start, options?) => RichTextBuilder

Create a date mention.

Parameters

start

string

ISO 8601 date string.

options?

Optional end date and time_zone.

end?

string | null

time_zone?

string | null

Returns

RichTextBuilder

mentionLinkPreview

mentionLinkPreview: (url) => RichTextBuilder

Create a link preview mention.

Parameters

url

string

Returns

RichTextBuilder

mentionPage

mentionPage: (pageId) => RichTextBuilder

Create a mention of a Notion page.

Parameters

pageId

string

Returns

RichTextBuilder

mentionUser

mentionUser: (user) => RichTextBuilder

Create a mention of a Notion user.

Parameters

user

{ avatar_url?: string | null; id: string; name?: string; object: "user"; person: { email: string; email_verified?: boolean; }; type: "person"; } | { avatar_url?: string | null; bot: { owner: { type: "workspace"; workspace: true; } | { type: "user"; }; workspace_id?: string; workspace_limits?: { max_file_upload_size_in_bytes: number; }; workspace_name?: string | null; }; id: string; name?: string; object: "user"; type: "bot"; } | { id: string; object: "user"; }

A full or partial Notion user object (must have at least object and id).

Returns

RichTextBuilder

Example

// Plain text with annotations
richText('Hello').bold().build();

// Mentions
richText.mentionPage('abc-123').build();
richText.mentionUser({ object: 'user', id: 'abc-123' }).build();

// Equation
richText.equation('E=mc^2').build();

// Combine multiple segments
richText.join(
  richText('Normal '),
  richText('bold').bold(),
  richText(' and '),
  richText('italic').italic(),
);