Astronotion Docs

Components

Components are imported from astronotion/components . These components are framework-agnostic Astro components . They are unstyled but expose data attributes and CSS classes. Check out the Styling page for more details.

(1) Essential components

In most cases, these are the only components you need to import.

NotionBlocks

Renders a list of block objects that constitute a Notion page's content.

Prop:

  • data — accepts the contents field of a "standalone" or "child" page data from astronotion/api
    • type: AnContentBlock[]
    • default: []
JavaScript
---
import { NotionBlocks } from "astronotion/components";
import { getStandalonePage } from "astronotion/api";

const pageData = await getStandalonePage("1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b");
---

<NotionBlocks data={pageData.contents} />

NotionPageCover

Uses astro-imagetools to generate a set of optimised images and placeholders.

If the image is a custom upload, this component also downloads the image file to your site’s public/images/astronotion folder because the Notion API only returns a temporary URL that expires after a specified time.

Props:

  • src — (required) the image file URL
    • type: string
  • pictureProps — (optional) passed to astro-imagetools’ Picture component for additional customisations
JavaScript
---
import { NotionPageCover } from "astronotion/components";
import { getStandalonePage } from "astronotion/api";

const pageData = await getStandalonePage("1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b");
---

<NotionPageCover src={pageData.cover.url} />

You can use this component with any image URL outside of the Notion data, too.

JavaScript
<NotionPageCover src="https://images.unsplash.com/photo-1652454159675-11ead6275680?w=1170" />

NotionTexts

Renders a list of text objects from Notion’s text fields (a parent page’s description , the content of text blocks, lists, quotes, headers, etc). You may want to use this to render a page’s description field.

Props:

  • data — an array of Notion’s “decorated” (marked up for formatting) objects
JavaScript
---
import { NotionTexts } from "astronotion/components";
import { getStandalonePage } from "astronotion/api";

const pageData = await getParentPage("2ba80ec3-d84d-4647-9f23-ec15ba5e39b0");
---

<NotionTexts data={pageData.description} />

(2) Block type components

These components render Notion block objects by type. You don’t need to import and use these components directly unless you'd like to replace NotionBlocks , NotionPageCover , or NotionTexts with your own implementation.

NotionBlockItemBookmark

Renders Notion block object with the type bookmark .

Props:

  • data
    • type: { properties: BookmarkBlock["properties"]; format: BookmarkBlock["format"]; }

NotionBlockItemCallout

Renders Notion block objects with the type callout .

Props:

  • data
    • type: { properties: CalloutBlock["properties"]; format: CalloutBlock["format"]; }

NotionBlockItemCode

Renders Notion block objects with the type code .

It uses Astro's Code component for the code block content. At the moment there is no way to customize this component without entirely replacing <NotionBlocks /> .

rops:

  • data
    • type: CodeBlock["properties"]

NotionBlockItemEmbed

Renders Notion block objects with the type video (and other embeddable types in future releases).

YouTube embeds are rendered with astro-embed ; other sources are shown in an iframe.

Props:

  • data
    • type: { properties: VideoBlock["properties"]; format: VideoBlock["format"]; }

NotionBlockItemImage

Renders Notion block objects with the type of image .

Like NotionPageCover , this component downloads expiring images to your site’s public/images/astronotion folder and uses astro-imagetools to generate optimised images and placeholders.

Props:

  • data
    • type: ImageBlock["properties"]
  • pictureProps — (optional) passed to astro-imagetools’ Picture component for additional customisations

NotionGroupedList

Renders Notion block objects with the types of bulleted_list , numbered_list , todo .

Props:

  • data
    • type: ( BulletedListBlock | NumberedListBlock | TodoBlock | ColumnListBlock | ColumnBlock )[]

(3) Helper components

As with section (2), the only time you should import these components are when you are replacing NotionBlocks , NotionPageCover , or NotionTexts with your own implementation.

NotionBlockWrapper

Uses xelement under the hood to polymorphically render the appropriate semantic HTML element based on the block object type ( p for text , blockquote for quote , etc).

This component also contains the logic to render the appropriate child component if necessary (eg. no child for divider object, NotionBlockItemCallout for callout object), and to assign data attributes and CSS classes for styling.

NotionGroupWrapper

Checks and renders the appropriate component of a “grouped” block objects based on their content. Currently it only handles "list" groups ( bulleted_list , numbered_list , todo ). In the future it will also render columns.

NotionImageBase

Used by NotionPageCover and NotionBlockItemImage , this is the component that runs the download logic and renders astro-imagetools’ Picture component .

RecursiveList

Uses xelement to render the appropriate list element ( ol for numbered_list type, ul for others). This component also converts the flat objects to nested list elements markup, using Astro:self to render itself as a child list until there is no more child.

← Prev: API | Next: Styling →

Astronotion Docs