1.3.21
Welcome to the notion-helper documentation. This library provides a heaping spoonful of syntactic sugar for the Notion API.
It primarily gives you a fluent interface for quickly building JSON to create Notion blocks, pages, and property values.
You'll also find functions that can intelligently make API calls for creating new pages and appending blocks. Pass these a valid client object or API call function, and they'll handle the comlicated process of splitting blocks into chunks to deal with the Notion API's limits.
Create a page:
See the notion-helper website for more examples.
This library works in both Node.js and browser environments!
Important: Browsers can't directly call the Notion API due to CORS restrictions. You'll need a backend proxy or serverless function to handle the actual API calls.
Want to see it in action? Check out our Interactive Browser Example that lets you run code and see the JSON output in real-time!
Object with methods to construct the majority of block types supported by the Notion API.
Block types include audio, bookmark, breadcrumb, bulleted list item, callout, code, column_list, column, divider, embed, file, heading, image, numbered list item, paragraph, pdf, quote, table, table row, table of contents, to-do, toggle, and video. Some block types return null if they are provided with invalid data; you should filter these out your final children array.
Not supported: Link preview, synced block. Equation and Mention are supported within the buildRichTextObj() function, not here.
Methods for audio blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates an audio block.
((string | Object))
A string representing the audio URL, a file upload ID, or an options object.
Name | Description |
---|---|
options.url string
|
The URL for the audio. |
options.id string
|
The ID of the file upload. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
(Object | null)
:
An audio block object compatible with Notion's API, or null if the URL/ID is invalid.
// Use with an external URL
const externalAudio = block.audio.createBlock("https://thomasjfrank.com/wp-content/uploads/2025/05/output3.mp3");
// Use with a file upload ID
const fileUploadAudio = block.audio.createBlock("123e4567-e89b-12d3-a456-426614174000");
// Use with options object for external audio
const externalAudio = block.audio.createBlock({
url: "https://thomasjfrank.com/wp-content/uploads/2025/05/output3.mp3",
caption: "Check out my mixtape, man."
});
// Use with options object for file upload
const fileUploadAudio = block.audio.createBlock({
id: "123e4567-e89b-12d3-a456-426614174000",
caption: "Check out my mixtape, man."
});
Methods for bookmark blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a bookmark block.
Object
:
A bookmark block object compatible with Notion's API.
// Use with just a URL
const simpleBookmark = block.bookmark.createBlock("https://www.flylighter.com");
// Use with options object
const complexBookmark = block.bookmark.createBlock({
url: "https://www.flylighter.com",
caption: "Flylighter is a super-rad web clipper for Notion."
});
// Use with options object and array of strings for caption
const multiLineBookmark = block.bookmark.createBlock({
url: "https://www.flylighter.com",
caption: ["Flylighter is a web clipper for Notion...", "...and Obsidian, too."]
});
Methods for breadcrumb blocks.
(boolean)
: Indicates if the block supports child blocks.
Methods for bulleted list item blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a bulleted list item block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the list item content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The item's content as a string, an array of strings, or an array of rich text objects. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the text. |
Object
:
A bulleted list item block object compatible with Notion's API.
// Use with a string
const simpleItem = block.bulleted_list_item.createBlock("Simple list item");
// Use with an array of strings
const multiLineItem = block.bulleted_list_item.createBlock(["Line 1", "Line 2"]);
// Use with options object
const complexItem = block.bulleted_list_item.createBlock({
rich_text: "Complex item",
color: "red",
children: [
// Child blocks would go here
]
});
Methods for callout blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a callout block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the callout content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.icon string
(default "" )
|
An optional icon value (URL for "external" or emoji character for "emoji"). |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the callout background. |
Object
:
A callout block object compatible with Notion's API.
// Use with a string
const simpleCallout = block.callout.createBlock("I though I told you never to come in here, McFly!");
// Use with options object
const complexCallout = block.callout.createBlock({
rich_text: "Now make like a tree and get outta here.",
icon: "💡",
color: "blue_background",
children: [
// Child blocks would go here
]
});
Methods for code blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a code block.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The code content as a string, an array of strings, or an array of rich text objects. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
options.language string
(default "plain text" )
|
Programming language of the code block. |
Object
:
A code block object compatible with Notion's API.
// Use with a string
const simpleCode = block.code.createBlock("console.log('Give me all the bacon and eggs you have.');");
// Use with options object
const complexCode = block.code.createBlock({
rich_text: "const name = 'Monkey D. Luffy'\n console.log(`My name is ${name} and I will be king of the pirates!`)",
language: "JavaScript",
caption: "A simple JavaScript greeting function"
});
Methods for column list blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a column list block. Column list blocks must have at least two column child blocks, each of which must have at least one child block - otherwise, the Notion API will throw an error.
(Array?)
An array where each element represents a column. Each element can be:
(Object | null)
:
The created column list block object, or null if invalid input is provided.
// Create a column list with 3 empty columns
const emptyColumns = block.column_list.createBlock(3);
// Create a column list with 2 columns, each containing a paragraph
const twoColumnList = block.column_list.createBlock(["First column", "Second column"]);
// Create a column list with mixed content
const mixedColumnList = block.column_list.createBlock([
"Text in first column",
["Paragraph 1 in second column", "Paragraph 2 in second column"],
{
type: "column",
column: {},
children: [block.heading_2.createBlock("Custom heading in third column")]
}
]);
// Create an empty column list
const emptyColumnList = block.column_list.createBlock();
Methods for column blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a column block. A column block must have at least one non-column block in its children array, and the column block itself must be appended as a child block to a column_list block.
(string?)
A string that will be converted into a paragraph block within the column.
Object
:
The created column block object.
// Create an empty column
const emptyColumn = block.column.createBlock();
// Create a column with a single paragraph
const singleParagraphColumn = block.column.createBlock("This is a paragraph in a column");
// Create a column with multiple blocks
const multiBlockColumn = block.column.createBlock([
"First paragraph",
block.heading_2.createBlock("Heading in column"),
"Another paragraph"
]);
// Create a column with custom blocks
const customBlocksColumn = block.column.createBlock([
block.paragraph.createBlock("Custom paragraph"),
block.bulleted_list_item.createBlock("Bullet point in column"),
block.image.createBlock({ url: "https://example.com/image.jpg" })
]);
Methods for divider blocks.
(boolean)
: Indicates if the block supports child blocks.
Methods for embed blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates an embed block.
Object
:
An embed block object compatible with Notion's API.
// Use with a string
const simpleEmbed = block.embed.createBlock("https://www.youtube.com/watch?v=ec5m6t77eYM");
// Use with options object
const complexEmbed = block.embed.createBlock({
url: "https://www.youtube.com/watch?v=ec5m6t77eYM"
});
Methods for file blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a file block.
((string | Object))
A string representing the file URL, a file upload ID, or an options object.
Name | Description |
---|---|
options.url string
|
The URL for the file. |
options.id string
|
The ID of the file upload. |
options.name string?
|
The name of the file. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
(Object | null)
:
A file block object compatible with Notion's API, or null if the URL/ID is invalid.
// Use with a file URL
const externalFile = block.file.createBlock("https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf");
// Use with a file upload ID
const fileUploadFile = block.file.createBlock("123e4567-e89b-12d3-a456-426614174000");
// Use with options object for external file
const externalFile = block.file.createBlock({
url: "https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf",
name: "10 Steps to Earning Awesome Grades (preview)",
caption: "The Reddit preview of the 10 Steps to Earning Awesome Grades book."
});
// Use with options object for file upload
const fileUploadFile = block.file.createBlock({
id: "123e4567-e89b-12d3-a456-426614174000",
name: "10 Steps to Earning Awesome Grades (preview)",
caption: "The Reddit preview of the 10 Steps to Earning Awesome Grades book."
});
Methods for heading_1 blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a heading_1 block.
Adding children will coerce headings to toggle headings.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the heading content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.color string
(default "default" )
|
Color for the heading text. |
options.is_toggleable boolean
(default false )
|
Whether the heading is toggleable. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
Object
:
A heading_1 block object compatible with Notion's API.
// Use with a string
const simpleHeading = block.heading_1.createBlock("Simple Heading");
// Use with options object
const complexHeading = block.heading_1.createBlock({
rich_text: "Complex Heading",
color: "red",
is_toggleable: true,
children: [
// Child blocks would go here
]
});
Methods for heading_2 blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a heading_2 block.
Adding children will coerce headings to toggle headings.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the heading content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.color string
(default "default" )
|
Color for the heading text. |
options.is_toggleable boolean
(default false )
|
Whether the heading is toggleable. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
Object
:
A heading_2 block object compatible with Notion's API.
// Use with a string
const simpleHeading = block.heading_2.createBlock("Simple Heading");
// Use with options object
const complexHeading = block.heading_2.createBlock({
rich_text: "Complex Heading",
color: "red",
is_toggleable: true,
children: [
// Child blocks would go here
]
});
Methods for heading_3 blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a heading_3 block.
Adding children will coerce headings to toggle headings.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the heading content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.color string
(default "default" )
|
Color for the heading text. |
options.is_toggleable boolean
(default false )
|
Whether the heading is toggleable. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
Object
:
A heading_3 block object compatible with Notion's API.
// Use with a string
const simpleHeading = block.heading_3.createBlock("Simple Heading");
// Use with options object
const complexHeading = block.heading_3.createBlock({
rich_text: "Complex Heading",
color: "red",
is_toggleable: true,
children: [
// Child blocks would go here
]
});
Methods for image blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates an image block.
((string | Object))
A string representing the image URL, a file upload ID, or an options object.
Name | Description |
---|---|
options.url string
|
The URL for the image. |
options.id string
|
The ID of the file upload. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
(Object | null)
:
An image block object compatible with Notion's API, or null if the URL/ID is invalid.
// Use with a string
const simpleImage = block.image.createBlock("https://i.imgur.com/5vSShIw.jpeg");
// Use with a file upload ID
const fileUploadImage = block.image.createBlock("123e4567-e89b-12d3-a456-426614174000");
// Use with options object for external image
const complexImage = block.image.createBlock({
url: "https://i.imgur.com/5vSShIw.jpeg",
caption: "A beautiful landscape"
});
// Use with options object for file upload
const fileUploadImage = block.image.createBlock({
id: "123e4567-e89b-12d3-a456-426614174000",
caption: "A beautiful landscape"
});
Methods for numbered list item blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a numbered list item block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the list item content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the text. |
Object
:
A numbered list item block object compatible with Notion's API.
// Use with a string
const simpleItem = block.numbered_list_item.createBlock("Simple list item");
// Use with an array of strings
const multiLineItem = block.numbered_list_item.createBlock(["Line 1", "Line 2"]);
// Use with options object
const complexItem = block.numbered_list_item.createBlock({
rich_text: "Complex item",
color: "red",
children: [
// Child blocks would go here
]
});
Methods for paragraph blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a paragraph block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the paragraph content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the text. |
Object
:
A paragraph block object compatible with Notion's API.
// Direct use with a string
const paragraphBlock = block.paragraph.createBlock("Hello, World!");
// Direct use with an array of strings
const multiLineParagraph = block.paragraph.createBlock(["I'm a line", "I'm also a line!"]);
// Usage with options object
const complexParagraph = block.paragraph.createBlock({
rich_text: "Complex paragraph",
color: "red",
children: [
// Child blocks would go here
]
});
Methods for PDF blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a PDF block.
((string | Object))
A string representing the PDF URL, a file upload ID, or an options object.
Name | Description |
---|---|
options.url string
|
The URL for the PDF. |
options.id string
|
The ID of the file upload. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
(Object | null)
:
A PDF block object compatible with Notion's API, or null if the URL/ID is invalid.
// Use with a PDF URL
const externalPDF = block.pdf.createBlock("https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf");
// Use with a file upload ID
const fileUploadPDF = block.pdf.createBlock("123e4567-e89b-12d3-a456-426614174000");
// Use with options object for external PDF
const externalPDF = block.pdf.createBlock({
url: "https://collegeinfogeek.com/wp-content/uploads/2015/01/10steps-reddit.pdf",
caption: "The Reddit preview of the 10 Steps to Earning Awesome Grades book."
});
// Use with options object for file upload
const fileUploadPDF = block.pdf.createBlock({
id: "123e4567-e89b-12d3-a456-426614174000",
caption: "The Reddit preview of the 10 Steps to Earning Awesome Grades book."
});
Methods for quote blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a quote block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the quote content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the text. |
Object
:
A quote block object compatible with Notion's API.
// Use with a string
const simpleQuote = block.quote.createBlock("Simple quote");
// Use with an array of strings
const multiLineQuote = block.quote.createBlock(["Line 1 of quote", "Line 2 of quote"]);
// Use with options object
const complexQuote = block.quote.createBlock({
rich_text: "Complex quote",
color: "gray",
children: [
// Child blocks would go here
]
});
Methods for table blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a table block.
(Object?)
Options for creating the table. If undefined, creates an empty table.
Name | Description |
---|---|
options.has_column_header boolean
(default false )
|
Whether the table has a column header. |
options.has_row_header boolean
(default false )
|
Whether the table has a row header. |
options.rows (Array<Array<string>> | Array<Object>)
(default [] )
|
An array of rows. Each row can be an array of strings or a table_row object. |
Object
:
A table block object compatible with Notion's API.
// Use with array of string arrays
const simpleTable = block.table.createBlock({
rows: [
["Header 1", "Header 2"],
["Row 1, Cell 1", "Row 1, Cell 2"],
["Row 2, Cell 1", "Row 2, Cell 2"]
],
has_column_header: true
});
// Use with array of table_row objects
const complexTable = block.table.createBlock({
rows: [
block.table_row.createBlock(["Header 1", "Header 2"]),
block.table_row.createBlock(["Row 1, Cell 1", "Row 1, Cell 2"]),
block.table_row.createBlock(["Row 2, Cell 1", "Row 2, Cell 2"])
],
has_column_header: true,
has_row_header: false
});
// Create an empty table
const emptyTable = block.table.createBlock();
Methods for table row blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a table row block.
Object
:
A table row block object compatible with Notion's API.
// Use with an array of strings
const simpleRow = block.table_row.createBlock(["Cell 1", "Cell 2", "Cell 3"]);
// Use with an array of rich text objects
const complexRow = block.table_row.createBlock([
[{ type: "text", text: { rich_text: "Cell 1" } }],
[{ type: "text", text: { rich_text: "Cell 2", annotations: { bold: true } } }],
[{ type: "text", text: { rich_text: "Cell 3" } }]
]);
Methods for table of contents blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a table of contents block.
Object
:
A table of contents block object compatible with Notion's API.
// Use with default settings
const simpleTOC = block.table_of_contents.createBlock();
// Use with a color string
const coloredTOC = block.table_of_contents.createBlock("red");
// Use with options object
const complexTOC = block.table_of_contents.createBlock({ color: "blue" });
Methods for to-do list blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a to-do list block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the to-do content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.checked boolean
(default false )
|
Whether the to-do item is checked. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the to-do text. |
Object
:
A to-do list block object compatible with Notion's API.
// Use with a string
const simpleToDo = block.to_do.createBlock("Simple task");
// Use with options object
const complexToDo = block.to_do.createBlock({
rich_text: "Complex task",
checked: true,
color: "green",
children: [
// Child blocks would go here
]
});
Methods for toggle blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a toggle block.
((string | Array<string> | Object))
A string, an array of strings, or an options object representing the toggle content.
Name | Description |
---|---|
options.rich_text (string | Array<string> | Array<Object>)
(default [] )
|
The content as a string, an array of strings, or an array of rich text objects. |
options.children Array<Object>
(default [] )
|
An array of child block objects. |
options.color string
(default "default" )
|
Color for the toggle text. |
Object
:
A toggle block object compatible with Notion's API.
// Use with a string
const simpleToggle = block.toggle.createBlock("Simple toggle");
// Use with options object
const complexToggle = block.toggle.createBlock({
rich_text: "Complex toggle",
color: "blue",
children: [
// Child blocks would go here
]
});
Methods for video blocks.
(boolean)
: Indicates if the block supports child blocks.
Creates a video block.
((string | Object))
A string representing the video URL, a file upload ID, or an options object.
Name | Description |
---|---|
options.url string
|
The URL for the video. |
options.id string
|
The ID of the file upload. |
options.caption (string | Array<string> | Array<Object>)
(default [] )
|
The caption as a string, an array of strings, or an array of rich text objects. |
(Object | null)
:
A video block object compatible with Notion's API, or null if the URL/ID is invalid.
// Use with a video URL
const externalVideo = block.video.createBlock("https://www.youtube.com/watch?v=ec5m6t77eYM");
// Use with a file upload ID
const fileUploadVideo = block.video.createBlock("123e4567-e89b-12d3-a456-426614174000");
// Use with options object for external video
const externalVideo = block.video.createBlock({
url: "https://www.youtube.com/watch?v=ec5m6t77eYM",
caption: "Never gonna give you up"
});
// Use with options object for file upload
const fileUploadVideo = block.video.createBlock({
id: "123e4567-e89b-12d3-a456-426614174000",
caption: "Never gonna give you up"
});
Block shorthand methods – these allow you to call the createBlock() method for the properties of the block object more quickly. Import them directly into a file, or call them on NotionHelper.
Creates an audio block.
(Object | null)
:
An audio block or null if the URL is invalid.
Creates a bulleted list item block.
Object
:
A bulleted list item block.
Shorthand alias for bulletedListItem(). Creates a bulleted list item block.
Object
:
A bulleted list item block.
Creates a callout block.
Object
:
A callout block.
Creates a column list block.
Object
:
A column list block.
Creates a column block.
Object
:
A column block.
Creates a file block.
(Object | null)
:
A file block or null if the URL is invalid.
Creates a heading_1 block.
Object
:
A heading_1 block.
Creates a heading_2 block.
Object
:
A heading_2 block.
Creates a heading_3 block.
Object
:
A heading_3 block.
Creates an image block.
(Object | null)
:
An image block or null if the URL is invalid.
Creates a numbered list item block.
Object
:
A numbered list item block.
Shorthand alias function for numberedListItem(). Creates a numbered list item block.
Object
:
A numbered list item block.
Creates a paragraph block.
Object
:
A paragraph block.
Creates a PDF block.
(Object | null)
:
A PDF block or null if the URL is invalid.
Creates a quote block.
Object
:
A quote block.
Creates a table of contents block.
Object
:
A table of contents block.
Creates a to-do list block.
Object
:
A to-do list block.
Creates a toggle block.
Object
:
A toggle block.
Simple function to create standard Paragraph blocks from an array of strings without any special formatting. Each Paragraph block will contain a single Rich Text Object.
Array<Object>
:
array of Paragraph blocks.
(string)
either an emoji character or a URL for an externally-hosted image file.
Object
:
An object representing the icon.
Creates a representation of an external link.
(string)
The URL of the external link.
Object
:
An object containing the external URL.
Creates a representation of an emoji.
(string)
The emoji character.
Object
:
An object containing the emoji.
Creates a representation of a file link.
(string)
The ID of the file.
Object
:
An object containing the file ID.
Object with methods for constructing Notion page metadata, including parent, page, block, property, cover, and icon.
Parent creates a parent object. Page, block, and property create ID objects. Cover creates an external image object, while icon can create an external image object or an emoji object.
Metadata definition for a page ID property.
(string)
: The data type the property accepts.
Metadata definition for a block ID property.
(string)
: The data type the property accepts.
Metadata definition for a property ID property.
(string)
: The data type the property accepts.
Metadata definition for an icon.
(string)
: The data type the property accepts.
Page shorthand methods - these allow you to call the createMeta() method for the properties of the page_meta object more quickly. Import them directly into a file, or call them on NotionHelper.
Object with methods for constructing each of the possible property types within a Notion database page.
Property types include title, rich_text, checkbox, date, email, files, multi_select, number, people, phone_number, relation, select, status, and url.
Methods for title properties.
(string)
: The data type the property accepts.
Sets a title property's value.
Object
:
A title property object.
Notion API will throw an error if title doesn't contain an array of Rich Text object(s) (RTOs). setProp() will convert a string, or array of strings, to an array of Rich Text object(s). On other invalid input, it will throw an error.
Methods for rich text properties.
(string)
: The data type the property accepts.
Methods for checkbox properties.
(string)
: The data type the property accepts.
Methods for date properties.
(string)
: The data type the property accepts.
Methods for email properties.
(string)
: The data type the property accepts.
Methods for files properties.
(string)
: The data type the property accepts.
Sets a files property's value.
((string | Array<(string | Array<string> | Object)> | Object))
A url/file ID string, an array of url/file ID strings, an array of [url/file ID, name] arrays, an array of file objects, or a single file object. File objects can be simple - ({ name, url }) or ({ name, id }) - or fully constructed ({ name, external: { url }}) or ({ name, file_upload: { id }})
(string?)
a name for a singular file. Used if a string value is passed for the files parameter. If not provided, the file's URL/ID will be used for the name.
Object
:
A files property object.
Methods for multi_select properties.
(string)
: The data type the property accepts.
Methods for number properties.
(string)
: The data type the property accepts.
Methods for phone_number properties.
(string)
: The data type the property accepts.
Methods for select properties.
(string)
: The data type the property accepts.
Methods for status properties.
(string)
: The data type the property accepts.
Property shorthand methods - these allow you to call the setProp() method for the properties of the page_props object more quickly. Import them directly into a file, or call them on NotionHelper.
Validates values passed to the setProp() methods above. Performs some transformation in certain cases.
(any)
the value being passed to setProp(), which invokes this function
(string)
the type of value expected by this Notion API property
(Object)
Name | Description |
---|---|
$0.parent any
|
|
$0.parent_type any
|
|
$0.pages any
|
|
$0.schema any
|
|
$0.childrenFn any
|
(Object)
(string)
The ID of the parent page or database.
(string)
"page_id" or "database_id".
((Array<Object> | Object))
an array of simple objects, each of which will be turned into a valid page object. Each can have property types that match to valid Notion page properties, as well as a "cover", "icon", and "children" property. The "children" prop's value should be either a string or an array. You can also pass a single object, but the function will still return an array.
(Object)
an object that maps the schema of the pages objects to property names and types in the parent. Saves you from needing to specify the property name and type from the target Notion database for every entry in your pages object. For each property in your pages object that should map to a Notion database property, specify the key as the property name in the pages object and set the value as an array with the Notion property name as the first element and the property type as the second. Non-valid property types will be filtered out. Optionall, you can specify custom keys for the icon (["Icon", "icon"]), cover (["Cover", "cover"]), and children array (["Children", "children"]).
(function)
a callback you can specify that will run on any array elements present in a "children" property of any object in the pages array. If that "children" property contains a single string, it'll run on that as well. If omitted, any "children" values will be converted to Paragraph blocks by default.
Array<Object>
:
An array of page objects, each of which can be directly passed as the children for a POST request to
https://api.notion.com/v1/pages
(or as the single argument to notion.pages.create() when using the SDK).
const database = "abcdefghijklmnopqrstuvwxyz"
const tasks = [ {
icon: "😛",
task: "Build Standing Desk",
due: "2024-09-10",
status: "Not started"
} ]
const schema = {
task: [ "Name", "title" ],
due: [ "Due Date", "date"],
status: [ "Status", "status" ]
}
const pageObjects = quickPages({
parent: database,
parent_type: "database_id",
pages: tasks,
schema: schema,
childrenFn: (value) => NotionHelper.makeParagraphs(value)
})
A builder object for Notion content with fluent interface methods.
Type: Object
const notionBuilder = createNotionBuilder();
// Build a new Notion page with various blocks
const result = notionBuilder
.parentDb('database-id')
.title('Page Title', 'Hello World')
.paragraph('This is the first paragraph.')
.heading1('Main Heading')
.build();
Creates a fluent interface builder for constructing Notion objects, including pages, properties, and blocks.
Fluent Interface Methods:
The returned builder provides chainable methods organized into categories:
Page Setup Methods:
parentDb(database_id)
- Sets parent databaseparentPage(page_id)
- Sets parent pagepageId(page_id)
- Adds page ID for updatesblockId(block_id)
- Adds block ID for block operationspropertyId(property_id)
- Adds property ID for property operationscover(url)
- Sets page cover imageicon(url)
- Sets page iconProperty Methods:
property(name, type, value)
- Adds custom propertytitle(name, value)
- Adds title propertyrichText(name, value)
- Adds rich text propertycheckbox(name, value)
- Adds checkbox propertydate(name, value)
- Adds date propertyemail(name, value)
- Adds email propertyfiles(name, value)
- Adds files propertymultiSelect(name, value)
- Adds multi-select propertynumber(name, value)
- Adds number propertypeople(name, value)
- Adds people propertyphoneNumber(name, value)
- Adds phone number propertyrelation(name, value)
- Adds relation propertyselect(name, value)
- Adds select propertystatus(name, value)
- Adds status propertyurl(name, value)
- Adds URL propertyBlock Methods:
paragraph(content, options, url)
- Adds paragraph blockheading1(content, options, url)
- Adds H1 blockheading2(content, options, url)
- Adds H2 blockheading3(content, options, url)
- Adds H3 blockbulletedListItem(content, options, url)
- Adds bulleted list itemnumberedListItem(content, options, url)
- Adds numbered list itemtoDo(content, checked, options, url)
- Adds to-do blockcallout(content, emoji, options, url)
- Adds callout blockquote(content, options, url)
- Adds quote blockcode(content, language)
- Adds code blockdivider()
- Adds divider blockimage(url, caption)
- Adds image blockvideo(url, caption)
- Adds video blockaudio(url, caption)
- Adds audio blockfile(url, caption)
- Adds file blockpdf(url, caption)
- Adds PDF blockbookmark(url, caption)
- Adds bookmark blockembed(url, caption)
- Adds embed blocktable(tableArray)
- Adds table blocktableRow(cellContents)
- Adds table rowcolumnList(columnArray)
- Adds column listcolumn(columnContent)
- Adds columntoggle(content, children, options, url)
- Adds toggle blockStructure Management:
startParent(parentBlock)
- Begins nested block structureendParent()
- Ends current nesting levelbuild()
- Finalizes and returns the built objectReturn Object:
Returns an object with two possible properties:
content
(always returned) - can be a full page object, an array of blocks, or a properties objectadditionalBlocks
- array containing block chunks that exceed Notion's limits for subsequent requests(Object?)
Configuration options for the builder
Name | Description |
---|---|
options.strict boolean
(default false )
|
If true, throws errors for invalid data. Otherwise gracefully handles nulls. |
options.limitNesting boolean
(default true )
|
If true, limits nested children to 2 levels (Notion API limit). |
options.limitChildren boolean
(default true )
|
If true, limits children arrays to 100 blocks, putting excess in additionalBlocks. |
options.allowBlankParagraphs boolean
(default false )
|
If true, allows empty paragraph blocks. |
NotionBuilder
:
A builder object with fluent interface methods for constructing Notion content.
// Basic page creation
const page = createNotionBuilder()
.parentDb('database-id')
.title('Name', 'My Task')
.select('Status', 'In Progress')
.date('Due Date', '2024-12-01')
.paragraph('This is a task description.')
.toDo('Complete the first step', false)
.toDo('Review with team', false)
.build();
// Complex nested structure
const complexPage = createNotionBuilder()
.parentDb('database-id')
.title('Project Name', 'Website Redesign')
.heading1('Project Overview')
.paragraph('This project involves redesigning our main website.')
.heading2('Phase 1: Research')
.startParent(toggle('Research Tasks', []))
.toDo('Conduct user interviews', false)
.toDo('Analyze competitor websites', false)
.endParent()
.heading2('Phase 2: Design')
.callout('Important: Get stakeholder approval before development', '⚠️')
.build();
// Handle large content with additionalBlocks
const result = page.content;
const extraBlocks = page.additionalBlocks;
// Create page first, then append additional blocks if needed
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const newPage = await notion.pages.create(result);
if (extraBlocks && extraBlocks.length > 0) {
for (const blockChunk of extraBlocks) {
await notion.blocks.children.append({
block_id: newPage.id,
children: blockChunk
});
}
}
Type: NotionBuilder
Sets a checkbox property value for the page.
this
:
The builder instance for method chaining.
Sets a email property value for the page.
this
:
The builder instance for method chaining.
Sets a files property value for the page.
NOTE: The separate file() method creates a file block.
(string)
The name of the property.
this
:
The builder instance for method chaining.
Sets a number property value for the page.
this
:
The builder instance for method chaining.
Sets a phone number property value for the page.
this
:
The builder instance for method chaining.
Sets a select property value for the page.
this
:
The builder instance for method chaining.
Sets a status property value for the page.
this
:
The builder instance for method chaining.
Sets a URL property value for the page.
this
:
The builder instance for method chaining.
Starts a new parent block that can contain child blocks.
(string)
The type of block to create as a parent.
(Object
= {}
)
Options for creating the block, specific to the block type.
this
:
The builder instance for method chaining.
notion.startParent('toggle', 'Click to expand')
.paragraph('This is inside the toggle')
.endParent();
Ends the current parent block and moves up one level in the block hierarchy.
this
:
The builder instance for method chaining.
notion.startParent('toggle', 'Click to expand')
.paragraph('This is inside the toggle')
.endParent();
Adds a new block to the current level in the block hierarchy.
(string)
The type of block to add.
(Object
= {}
)
Options for creating the block, specific to the block type.
this
:
The builder instance for method chaining.
notion.addBlock('paragraph', 'This is a paragraph.');
// Or using the shorthand method:
notion.paragraph('This is a paragraph.');
Adds an existing Notion block to the current level in the block hierarchy. This method is useful when you have a pre-constructed Notion block that you want to add directly.
(Object)
A valid Notion block object to add.
this
:
The builder instance for method chaining.
// Add a pre-constructed paragraph block
const myBlock = {
type: "paragraph",
paragraph: {
rich_text: [{ type: "text", text: { content: "Hello" } }]
}
};
notion.addExistingBlock(myBlock);
Adds a blank paragraph block to the current level in the block hierarchy.
this
:
The builder instance for method chaining.
notion.blank()
Adds a paragraph block to the current stack.
If this method recieves a string over the max character length, it will split it and add multiple paragraph blocks to the stack. This differs from the other block methods, which will instead split long strings into an array of multiple rich_text objects.
If you prefer that behavior for paragraphs, you can import enforceStringLength() yourself, run your string through it, then pass the returned array to this method.
If you allow for blank paragraph blocks, calling .paragraph("") or .paragraph() will add a blank paragraph block to the current stack. You can do this with createNotionBuilder({ allowBlankParagraphs: true }).
If allowBlankParagraphs is false (the default):
(any)
this
:
The builder instance for method chaining.
Adds a heading_1 block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a heading_2 block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a heading_3 block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a bulleted_list_item block to the current stack.
(any)
this
:
The builder instance for method chaining.
Shorthand alias for bulletedListItem(). Adds a bulleted_list_item block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a numbered_list_item block to the current stack.
(any)
this
:
The builder instance for method chaining.
Shorthand alias for numberedListItem(). Added a numbered_list_item block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a to_do block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a toggle block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a code block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a quote block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a callout block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a divider block to the current stack.
this
:
The builder instance for method chaining.
Adds an image block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a video block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds an audio block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a file block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a pdf block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a bookmark block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds an embed block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a table_of_contents block to the current stack.
(any)
this
:
The builder instance for method chaining.
Adds a table block to the current stack, then increments the stack one level down, so further blocks are added as children of the table block. Only tableRow() and endTable() may be chained directly to this method.
(any)
this
:
The builder instance for method chaining.
Adds a table_row block to the current stack.
(any)
this
:
The builder instance for method chaining.
Alias for endParent(). Provides an intuitive way to stop adding table_row blocks to the current table block, and goes one level up in the block stack.
this
:
The builder instance for method chaining.
Adds a breadcrumb block to the current stack.
this
:
The builder instance for method chaining.
Adds a column list to the current stack, then increments the stack one level down, so further blocks are added as children of the column list block. Only column() may be chained directly to this method. Column lists must have at least two column children, each of which must have at least one non-column child block.
(any)
this
:
The builder instance for method chaining.
Alias for endParent(). Provides an intuitive way to stop adding column blocks to the current column_list block, and goes one level up in the block stack.
this
:
The builder instance for method chaining.
Adds a column block to the current stack, then increments the stack one level down, so further blocks are added as children of the column block. Only non-column blocks can be added as children of column blocks.
(any)
this
:
The builder instance for method chaining.
Alias for endParent(). Provides an intuitive way to stop adding blocks to the current column block, and goes one level up in the block stack.
this
:
The builder instance for method chaining.
Adds a block to the stack for each element in the passed array.
(any)
(any)
this
:
The builder instance for method chaining.
Builds and returns the final Notion object based on the current state of the builder.
((Object | Array))
: The main content of the built object. This can be a full page object, a properties object, or an array of blocks, depending on what was added to the builder.
(Array)
: Any blocks that exceed Notion's maximum block limit per request. These will need to be added in subsequent requests.
this
:
An object containing the built content and any additional blocks.
const notion = createNotionBuilder();
const result = notion
.dbId('your-database-id')
.title('Page Title', 'My New Page')
.paragraph('This is a paragraph.')
.build();
console.log(result.content); // The main page content
console.log(result.additionalBlocks); // Any blocks that couldn't fit in the initial request
Creates a new page in Notion using user-provided callback functions for page creation and block-append operations.
(any)
(any)
Resets the builder to its initial state, clearing all added content.
this
:
The builder instance for method chaining.
const notion = createNotionBuilder();
notion
.dbId('your-database-id')
.title('Page Title', 'My New Page')
.paragraph('This is a paragraph.')
.build();
// Reset the builder for a new page
notion.reset()
.dbId('another-database-id')
.title('Page Title', 'Another New Page')
.build();
(Object)
The options for creating a Notion builder.
Name | Description |
---|---|
options.strict boolean
(default false )
|
If true, the builder will throw errors when passed invalid or null data. |
options.limitNesting number
(default true )
|
If true, limits the number of nested children block arrays to 2. |
options.limitChildren boolean
(default true )
|
If true, the final content object's children array will have a maximum of 100 blocks. |
options.allowBlankParagraphs boolean
(default false )
|
If true, calling .paragraph("") will result in an empty paragraph block. |
NotionBuilder
:
A builder object with methods for constructing and managing Notion content.
These functions take user-provided callback functions for API-specific requests, such as page-creation.
This will allow the library to handle requests directly, which will eventually enable deep tree-traversal and the construction of very complex pages and blocks structures.
Needed request types:
Auth
blocks X Append block children (patch)
More block tasks
page X Create a page (post)
database
users
comments
search
Methods for page creation.
Creates a new page in Notion and optionally appends child blocks to it. Includes as many child blocks as possible in the initial request. Uses request.blocks.children.append() for all remaining child blocks, so it can handle nested blocks to any level.
(Object)
The options for creating a page.
Name | Description |
---|---|
options.data Object
|
The data for creating the page. |
options.data.parent Object
|
The parent of the page (must include either database_id or page_id). |
options.data.properties Object?
|
The properties of the page. |
options.data.icon Object?
|
The icon of the page. |
options.data.cover Object?
|
The cover of the page. |
options.data.children Array<Object>?
|
An array of child blocks to add to the page. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getPage Function
(default (response)=>response )
|
A function to extract the page data from the API response. If you're passing a custom apiCall function, you should pass a getPage function as well. |
options.getResults Function
(default (response)=>response.results )
|
A function to extract results from the API response when appending blocks. Enables the append() method to append all child blocks in the request. If you're passing a custom apiCall function, you should pass a getResults function as well. |
Promise<Object>
:
An object containing the API response for page creation and, if applicable, the result of appending children.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const page = createNotion()
.parentDb("your-database-id")
.title("Name", "Charmander")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/4.png")
.richText("Category", "Lizard Pokémon")
.quote("Obviously prefers hot places. When it rains, steam is said to spout from the tip of its tail.")
.build()
const result = await request.pages.create({
data: page.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const NOTION_VERSION = '2022-06-28';
const customApiCall = async (data) => {
return await ky.post('https://api.notion.com/v1/pages', {
json: data,
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': NOTION_VERSION,
},
}).json();
};
const page = createNotion()
.parentDb("your-database-id")
.title("Name", "Squirtle")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/7.png")
.richText("Category", "Tiny Turtle Pokémon")
.quote("After birth, its back swells and hardens into a shell. Powerfully sprays foam from its mouth.")
.build()
const result = await request.pages.create({
data: page.content,
apiCall: customApiCall,
getPage: (response) => response,
getResults: (response) => response.results
});
Methods for working with blocks.
Methods for working with block children.
Appends a children block array to a parent block (or page). Handles nested blocks to any level via recursion.
(Object)
The options for appending blocks.
Name | Description |
---|---|
options.block_id string
|
The ID of the parent block to append children to. Can be a page ID. |
options.after string
|
The ID of an existing block after which to append the children. |
options.children Array<Object>
|
An array of child blocks to append. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getResults Function?
|
A function to extract results from the API response. Defaults to response => response.results, which will work if you pass a client object created with the Notion SDK: https://github.com/makenotion/notion-sdk-js . If you're passing a custom apiCall function, you should provide a matching getResults function that can handle the response and return the results array, which contains the created blocks. |
Promise<Object>
:
An object containing the API responses and the total number of API calls made.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const childBlocks = createNotion().paragraph("A paragraph").build()
const { apiResponses, apiCallCount } = await request.blocks.children.append({
block_id: 'your-block-id',
children: childBlocks.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const customApiCall = async (block_id, children) => {
const response = await ky.patch(
`https://api.notion.com/v1/blocks/${block_id}/children`,
{
json: { children },
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': '2022-06-28',
},
}
).json();
return response;
};
const childBlocks = createNotion().paragraph("Hello, World!").build();
const { apiResponses, apiCallCount } = await request.blocks.children.append({
block_id: 'your-block-id',
children: childBlocks.content,
apiCall: customApiCall
});
Object with methods for making requests to the Notion API.
Each method requires that you passe either a Client object created with the Notion SDK (https://github.com/makenotion/notion-sdk-js) or a custom apiCall function.
Methods for page creation.
Creates a new page in Notion and optionally appends child blocks to it. Includes as many child blocks as possible in the initial request. Uses request.blocks.children.append() for all remaining child blocks, so it can handle nested blocks to any level.
(Object)
The options for creating a page.
Name | Description |
---|---|
options.data Object
|
The data for creating the page. |
options.data.parent Object
|
The parent of the page (must include either database_id or page_id). |
options.data.properties Object?
|
The properties of the page. |
options.data.icon Object?
|
The icon of the page. |
options.data.cover Object?
|
The cover of the page. |
options.data.children Array<Object>?
|
An array of child blocks to add to the page. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getPage Function
(default (response)=>response )
|
A function to extract the page data from the API response. If you're passing a custom apiCall function, you should pass a getPage function as well. |
options.getResults Function
(default (response)=>response.results )
|
A function to extract results from the API response when appending blocks. Enables the append() method to append all child blocks in the request. If you're passing a custom apiCall function, you should pass a getResults function as well. |
Promise<Object>
:
An object containing the API response for page creation and, if applicable, the result of appending children.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const page = createNotion()
.parentDb("your-database-id")
.title("Name", "Charmander")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/4.png")
.richText("Category", "Lizard Pokémon")
.quote("Obviously prefers hot places. When it rains, steam is said to spout from the tip of its tail.")
.build()
const result = await request.pages.create({
data: page.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const NOTION_VERSION = '2022-06-28';
const customApiCall = async (data) => {
return await ky.post('https://api.notion.com/v1/pages', {
json: data,
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': NOTION_VERSION,
},
}).json();
};
const page = createNotion()
.parentDb("your-database-id")
.title("Name", "Squirtle")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/7.png")
.richText("Category", "Tiny Turtle Pokémon")
.quote("After birth, its back swells and hardens into a shell. Powerfully sprays foam from its mouth.")
.build()
const result = await request.pages.create({
data: page.content,
apiCall: customApiCall,
getPage: (response) => response,
getResults: (response) => response.results
});
Methods for working with blocks.
Methods for working with block children.
Appends a children block array to a parent block (or page). Handles nested blocks to any level via recursion.
(Object)
The options for appending blocks.
Name | Description |
---|---|
options.block_id string
|
The ID of the parent block to append children to. Can be a page ID. |
options.after string
|
The ID of an existing block after which to append the children. |
options.children Array<Object>
|
An array of child blocks to append. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getResults Function?
|
A function to extract results from the API response. Defaults to response => response.results, which will work if you pass a client object created with the Notion SDK: https://github.com/makenotion/notion-sdk-js . If you're passing a custom apiCall function, you should provide a matching getResults function that can handle the response and return the results array, which contains the created blocks. |
Promise<Object>
:
An object containing the API responses and the total number of API calls made.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const childBlocks = createNotion().paragraph("A paragraph").build()
const { apiResponses, apiCallCount } = await request.blocks.children.append({
block_id: 'your-block-id',
children: childBlocks.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const customApiCall = async (block_id, children) => {
const response = await ky.patch(
`https://api.notion.com/v1/blocks/${block_id}/children`,
{
json: { children },
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': '2022-06-28',
},
}
).json();
return response;
};
const childBlocks = createNotion().paragraph("Hello, World!").build();
const { apiResponses, apiCallCount } = await request.blocks.children.append({
block_id: 'your-block-id',
children: childBlocks.content,
apiCall: customApiCall
});
Request shorthand methods - these allow you to call the methods of the request object directly. Import them directly into a file, or call them on NotionHelper.
Creates a new page in Notion and optionally appends child blocks to it.
(Object)
The options for creating a page.
Name | Description |
---|---|
options.data Object
|
The data for creating the page. |
options.data.parent Object
|
The parent of the page (must include either database_id or page_id). |
options.data.properties Object?
|
The properties of the page. |
options.data.icon Object?
|
The icon of the page. |
options.data.cover Object?
|
The cover of the page. |
options.data.children Array<Object>?
|
An array of child blocks to add to the page. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getPage Function?
|
A function to extract the page data from the API response. Defaults to (response) => response. |
options.getResults Function?
|
A function to extract results from the API response when appending blocks. Defaults to (response) => response.results. |
Promise<Object>
:
An object containing the API response for page creation and, if applicable, the result of appending children.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const page = createNotion()
.parentDb("your-database-id")
.title("Name", "Charmander")
.icon("https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/4.png")
.richText("Category", "Lizard Pokémon")
.quote("Obviously prefers hot places. When it rains, steam is said to spout from the tip of its tail.")
.build()
const result = await createPage({
data: page.content,
client: notion
});
// Using with custom API call function
const customApiCall = async (data) => {
// Your custom API call implementation
};
const result = await createPage({
data: page.content,
apiCall: customApiCall,
getPage: (response) => response,
getResults: (response) => response.results
});
Appends a children block array to a parent block (or page). Handles nested blocks to any level via recursion.
(Object)
The options for appending blocks.
Name | Description |
---|---|
options.block_id string
|
The ID of the parent block to append children to. Can be a page ID. |
options.children Array<Object>
|
An array of child blocks to append. |
options.client Object?
|
The Notion client object. Either this or apiCall must be provided. |
options.apiCall Function?
|
A custom function for making API calls. Either this or client must be provided. |
options.getResults Function?
|
A function to extract results from the API response. Defaults to response => response.results, which will work if you pass a client object created with the Notion SDK: https://github.com/makenotion/notion-sdk-js . If you're passing a custom apiCall function, you should provide a matching getResults function that can handle the response and return the results array, which contains the created blocks. |
Promise<Object>
:
An object containing the API responses and the total number of API calls made.
// Using with Notion SDK client
const notion = new Client({ auth: NOTION_TOKEN });
const childBlocks = createNotion().paragraph("A paragraph").build()
const { apiResponses, apiCallCount } = await appendBlocks({
block_id: 'your-block-id',
children: childBlocks.content,
client: notion
});
// Using with custom API call function (using ky)
import ky from 'ky';
const NOTION_TOKEN = 'your-notion-token';
const customApiCall = async (block_id, children) => {
const response = await ky.patch(
`https://api.notion.com/v1/blocks/${block_id}/children`,
{
json: { children },
headers: {
'Authorization': `Bearer ${NOTION_TOKEN}`,
'Notion-Version': '2022-06-28',
},
}
).json();
return response;
};
const childBlocks = createNotion().paragraph("Hello, World!").build();
const { apiResponses, apiCallCount } = await appendBlocks({
block_id: 'your-block-id',
children: childBlocks.content,
apiCall: customApiCall
});
Builds a Rich Text Object. See: https://developers.notion.com/reference/rich-text
(Object?
= {}
)
Options for configuring the rich text object
Name | Description |
---|---|
options.annotations Object?
|
Options for the Annotation object |
options.annotations.bold boolean?
|
Bold text |
options.annotations.italic boolean?
|
Italic text |
options.annotations.strikethrough boolean?
|
Strikethrough text |
options.annotations.underline boolean?
|
Underlined text |
options.annotations.code boolean?
|
Code-style text |
options.annotations.color string?
|
String specifying the text's color or background color. Options: "blue", "brown", "default", "gray", "green", "orange", "pink", "purple", "red", "yellow". All except "default" can also be used as a background color with "[color]_background" - example: "blue_background". See: https://developers.notion.com/reference/rich-text#the-annotation-object |
options.url string?
|
The URL for this object, if any. Creates a clickable link. |
options.type string
(default "text" )
|
An optional type for the Rich Text Object. Supports text, equation, and mention. |
Array<Object>
:
Array with a single Rich Text Object
// Simple text
buildRichTextObj("Hello World")
// Text with URL
buildRichTextObj("Watch this very important video", { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" })
// Text with annotations
buildRichTextObj("Bold and brown", {
annotations: { bold: true, color: "brown" }
})
// Text with URL and annotations
buildRichTextObj("Bold blue link", {
url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
annotations: { bold: true, color: "blue" }
})
// Equation
buildRichTextObj("E = mc^2", { type: "equation" })
// Mention
buildRichTextObj({ type: "user", user: { id: "user_id" } }, { type: "mention" })
Enforces Rich Text format for content.
Array
:
An array of Rich Text Objects.
Enforces a single Rich Text Object format.
Object
:
A Rich Text Object.
Checks if a string contains only a single emoji.
(string)
boolean
:
Checks if a string is a valid URL.
(string)
boolean
:
Checks if a string is a valid UUID.
(string)
boolean
:
Checks if an image URL is both a valid URL and has a supported image file type.
(url)
the URL to be checked
boolean
:
Checks if a video URL is both a valid URL and will be accepted by the API, based on a list of supported file extensions and embed websites.
(url)
the URL to be checked
boolean
:
Checks if a audio URL is both a valid URL and will be accepted by the API, based on a list of supported file extensions.
(url)
the URL to be checked
boolean
:
Checks if a PDF URL is both a valid URL and ends with the .pdf extension.
(url)
the URL to be checked
boolean
:
Enforces a length limit on a string. Returns the original string in a single-element array if it is under the limit. If not, returns an array with string chunks under the limit.
Array<string>
:
array with the original string, or chunks of the string if it was over the limit.
Validates Date object or string input that represents a date, and converts it to an ISO-8601 date string if possible.
string
:
Checks a provided array of child blocks to see how many nested levels of child blocks are present. Used by requests.blocks.children.append to determine if recursive calls need to be used.
(number
= 1
)
The current level.
number
:
Gets the total number of blocks within an array of child blocks, including child blocks of those blocks (and so on). Used to ensure that requests do not exceed the 1,000 total block limit of the Notion API.
number
:
Gets the length of the longest array within a nested block array.
(number
= 0
)
The length of the array one level up from the array being checked, or 0 if this is the initial call of the function
number
:
Gets the size in bytes of a block array when converted to JSON. Used to ensure API requests don't exceed Notion's payload size limits.
number
:
Size in bytes