Components

Everything on this page is imported from rotion/ui. The components take the objects returned by the functions in API and render them; they do not fetch anything themselves.

import { Page, Table, List, Gallery, Calendar } from 'rotion/ui'

Every module in rotion/ui is marked 'use client'. In the Next.js App Router, a server component can still render them and pass the fetched data as props, because the data is plain JSON. A function prop such as link needs a client reference; see createClientLink.

Page

Renders the content of a Notion page.

const blocks = await FetchBlocks({ block_id: pageId })
 
<Page blocks={blocks} />

Consecutive list items are grouped into one <ul> or <ol>. Headings get an id made from the last 8 characters of the block ID, which is what TableOfContents links to. Block types Rotion does not render are skipped. The showcase has one page per block type, starting with paragraph.

Code blocks are highlighted with Prism  in the browser. The language definitions and the theme (prism.min.css, or prism-tomorrow.min.css when the system is in dark mode) are loaded from unpkg.com when the page runs. The theme follows the system setting even with style-without-dark.css. A code block whose language is mermaid is rendered as a Mermaid  diagram instead.

Database views

Table, List, Gallery and Calendar render the result of FetchDatabase. Their props and options are described in Database views.

Breadcrumbs

Renders the result of FetchBreadcrumbs as a path of links separated by /.

const list = await FetchBreadcrumbs({ type: 'page_id', id: pageId })
 
<Breadcrumbs list={list} hrefs={['/', '/[id]', '/[id]']} />

A breadcrumb block inside a page is rendered with the same component; pass its paths to <Page> as breadcrumb_hrefs.

TableOfContents

Builds a nested list of links from the headings in a page’s top-level blocks.

<TableOfContents blocks={blocks} />

Each link points to # plus the heading’s id, as rendered by <Page>. Use it to place a table of contents outside the page content, such as in a sidebar. A table of contents block written in Notion is rendered by <Page> itself; see table of contents.

GenHtmlId(blockId) returns the id that <Page> gives a heading, if you build your own navigation.

RichText

Renders one rich text item: text with its annotations (bold, italic, strikethrough, underline, code, color), links, mentions and inline equations.

{title.map((item, i) => <RichText key={i} textObject={item} />)}

Icon

Renders one of the SVG icons Rotion uses internally.

Checkbox

Renders a checked or unchecked box, as Notion shows a checkbox property.

createClientLink

function createClientLink<T extends ComponentType<any>>(LinkComponent: T): FC<ComponentProps<T>>

Wraps a link component, such as next/link, in a new function component that renders it with the same props. Call it in a file marked 'use client' and export the result; a server component can then pass it as link.

'use client'
 
import { createClientLink } from 'rotion/ui'
import NextLink from 'next/link'
 
export const ClientLink = createClientLink(NextLink)

import type { Link } from 'rotion/ui'
import { ClientLink } from './components/ClientLink'
 
<Page blocks={blocks} href="/[id]" link={ClientLink as Link} />

The Pages Router and other setups without server components can pass next/link (or any compatible component) directly.

Link

interface Link extends React.FC<{
  children: string | React.ReactNode
  className?: string
  href: string | UrlObject
}> {}

The type of every link prop. Rotion calls it with className, children, and an href that is either a path or { pathname, query } when a query is set. next/link fits this shape; cast it with as Link where TypeScript does not accept it as it is.

Other exports

rotion/ui also exports the component of each block type (TextBlock, ImageBlock, CodeBlock, CalloutBlock, and so on) and each property field of the views (TableTitleField, GalleryCard, ListDateField, and so on). <Page> and the views use them internally; they are exported so that you can render a single block or field on its own.

Among the helper functions, BuildPlainTextByPage(blocks) returns the plain text of a page’s top-level paragraphs, which is handy for a meta description.

Theming

The stylesheet (rotion/style.css or rotion/style-without-dark.css) defines its colors, fonts and borders as CSS custom properties on :root, all prefixed with --rotion-. Override them after importing the stylesheet:

:root {
  --rotion-font-family: 'Inter', sans-serif;
  --rotion-primary-text: rgb(20, 20, 20);
  --rotion-link-color: rgb(0, 102, 204);
  --rotion-border-radius: 6px;
}

The main groups are:

Every class name the components render starts with rotion-, so you can also target elements directly.

Dark mode

Most color variables have a dark counterpart named with -dark-, such as --rotion-dark-primary-text for --rotion-primary-text. rotion/style.css switches to the dark variables inside @media (prefers-color-scheme: dark), so the components follow the operating system’s setting. To change the dark colors, override the --rotion-dark-* variables.

rotion/style-without-dark.css is built from the same source with those media queries removed; the components then always use the light variables. Use it when your site has no dark theme, or when it switches themes by other means: set the light variables to your dark colors under your own selector, such as html.dark.