notion-helper Documentation

Indicates if the block supports child blocks.

Type: boolean

Creates an audio block.

// 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."
});

Indicates if the block supports child blocks.

Type: boolean

Creates a bookmark block.

// 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."]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a breadcrumb block.

// Create a breadcrumb block
const breadcrumbBlock = block.breadcrumb.createBlock();

Indicates if the block supports child blocks.

Type: boolean

Creates a bulleted list item block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a callout block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a code block.

// 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"
});

Indicates if the block supports child blocks.

Type: boolean

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.

// 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();

Indicates if the block supports child blocks.

Type: boolean

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.

// 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" })
]);

Indicates if the block supports child blocks.

Type: boolean

Creates a divider block.

const divider = block.divider.createBlock();

Indicates if the block supports child blocks.

Type: boolean

Creates an embed block.

// 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"
});

Indicates if the block supports child blocks.

Type: boolean

Creates a file block.

// 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."
});

Indicates if the block supports child blocks.

Type: boolean

Creates a heading_1 block.

Adding children will coerce headings to toggle headings.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a heading_2 block.

Adding children will coerce headings to toggle headings.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a heading_3 block.

Adding children will coerce headings to toggle headings.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates an image block.

// 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"
});

Indicates if the block supports child blocks.

Type: boolean

Creates a numbered list item block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a paragraph block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a PDF block.

// 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."
});

Indicates if the block supports child blocks.

Type: boolean

Creates a quote block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a table block.

// 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();

Indicates if the block supports child blocks.

Type: boolean

Creates a table row block.

// 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" } }]
]);

Indicates if the block supports child blocks.

Type: boolean

Creates a table of contents block.

// 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" });

Indicates if the block supports child blocks.

Type: boolean

Creates a to-do list block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a toggle block.

// 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
  ]
});

Indicates if the block supports child blocks.

Type: boolean

Creates a video block.

// 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"
});

Creates a parent object with a database_id or page_id.

Creates a page_id object.

Creates a block_id object.

Creates a property_id object.

Creates an icon object.

Creates a page cover object.

Sets a title property's value.

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.

Sets a rich text property's value.

Sets a checkbox property's value.

Sets a date property's value.

Sets an email property's value.

Sets a files property's value.

Sets a multi_select property's value.

Sets a number property's value.

Sets a people property's value.

Sets a phone number property's value.

Sets a relation property's value.

Sets a select property's value.

Sets a status property's value.

Sets a URL property's value.

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.

• Error: If no parent is provided or if there's an error during page creation or block appending.

// 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 block children.