notro-ui

notro-ui

Styled Notion block components for notro, installable via CLI.

This is NOT a component library.

notro-ui is a collection of copy-and-own Astro components. You run a CLI command, the source files are copied into your project, and they become your code. Edit them directly. No prop drilling. No theme configuration. No version lock-in.

This is the same philosophy as shadcn/ui and StarwindUI.

---

How it works

packages/notro-ui/src/templates/   ← canonical source (well-tested starting point)
         ↓  npx notro-ui init
apps/your-project/src/components/notro/   ← your code, fully owned by you

1. npx notro-ui init copies all component files to src/components/notro/
2. Files are yours — edit classes, add variants, restructure markup freely
3. Re-run npx notro-ui add <name> to reset a single component to the template default

---

Installation

# Copy all components into your project
npx notro-ui init

# Or copy a single component
npx notro-ui add callout

Files are written to src/components/notro/ by default. Use --out-dir to change the destination:

npx notro-ui init --out-dir src/components/blocks

---

Prerequisites

Your project needs:

npm install notro-loader tailwind-variants

And notro-theme.css imported in your global CSS (src/styles/global.css):

@import "./notro-theme.css";

(npx notro-ui init copies notro-theme.css to src/styles/notro-theme.css automatically.)

---

Using the installed components

After init, wire up the local NotroContent in your page:

---
// src/pages/blog/[slug].astro
import { buildLinkToPages, getPlainText } from "notro-loader";
import NotroContent from "../../components/notro/NotroContent.astro";

const { entry } = Astro.props;
---

<NotroContent
  markdown={entry.data.markdown}
  linkToPages={linkToPages}
/>

The local NotroContent.astro (in src/components/notro/) imports all your installed components and maps them to Notion block types. This file is yours — add, remove, or swap components by editing it directly.

---

Customizing components

Every component exports its style definition using tailwind-variants:

<!-- src/components/notro/Callout.astro -->
export const callout = tv({
  base: 'flex items-start gap-3 my-4 rounded-lg border ...',
  variants: {
    color: {
      default: 'notro-bg-gray',
      blue_background: 'notro-bg-blue',
      // ...
    },
  },
});

To customize, just edit the file:

<!-- Change border radius, padding, font -->
export const callout = tv({
  base: 'flex items-start gap-2 my-6 rounded-none border-l-4 pl-6 ...',
  ...
});

Color tokens (notro-bg-gray, notro-text-blue, etc.) are CSS variables defined in notro-theme.css. Edit that file to change colors globally.

---

Available components

Component	Notion block
Callout	Callout block
Toggle + ToggleTitle	Toggle block
H1 – H4	Heading 1–4
Quote	Quote block
TableBlock	Table
TableOfContents	Table of contents
Columns + Column	Column layout
ImageBlock	Image
Audio	Audio embed
Video	Video embed
FileBlock	File attachment
PdfBlock	PDF embed
PageRef	Page link
DatabaseRef	Database link
StyledSpan	Colored / underlined inline text
Mention	@mention
MentionDate	Date mention
SyncedBlock	Synced block
EmptyBlock	Empty line spacer
TableRow / TableCell / TableCol / TableColgroup	Table internals
NotroContent.astro	Entry point — maps all components; edit makeHtmlElement(...) calls to style <p>, <ul>, <a>, etc.
colors.ts	Color variant map for tv()
notro-theme.css	CSS variables + complex selectors

# See the full list
npx notro-ui list

---

How it relates to notro-loader

Package	Role
notro-loader	Headless — Content Loader, MDX pipeline, unstyled components
notro-ui	Style layer — copy-and-own styled components that sit on top of notro-loader

notro-loader provides compileMdxCached (the MDX compiler) and the headless component set. notro-ui's NotroContent.astro uses compileMdxCached directly and wires in your local styled components.

---

Reference implementation

templates/blog/ is the reference implementation. It shows what a project looks like after running npx notro-ui init:

• src/components/notro/ — installed components
• src/styles/notro-theme.css — installed theme
• src/pages/blog/[slug].astro — using NotroContent