@iwritec0de/blockbridge-react

Render WordPress Gutenberg blocks as React components.

Pairs with the BlockBridge WP plugin, which exposes a serializedBlocks field on the WordPress REST API. This library renders that payload as a React component tree.

Install

pnpm add @iwritec0de/blockbridge-react
# or
npm i @iwritec0de/blockbridge-react

Usage

import { BlockContent } from '@iwritec0de/blockbridge-react';
import '@iwritec0de/blockbridge-react/style.css';

export default function Post({ post }) {
  return <BlockContent blocks={post.serializedBlocks} />;
}

post.serializedBlocks is the array returned by the BlockBridge WP plugin's REST field.

Supported Blocks

| Block | Component | Notes | |-------|-----------|-------| | core/paragraph | Paragraph | | | core/heading | Heading | Levels 1–6 | | core/image | Image | Caption, link wrapping | | core/gallery | Gallery | Grid layout, cropped images | | core/list | List | Ordered and unordered | | core/list-item | ListItem | Nested lists via children | | core/quote | Quote | Citation support | | core/button | Button | Colors, border radius, link targets | | core/buttons | Buttons | Flex container for button groups | | core/group | Group | Any tagName, colors | | core/columns | Columns | Stacked on mobile | | core/column | Column | Variable width | | core/cover | Cover | Background image, overlay, parallax, focal point | | core/media-text | MediaText | Side-by-side text + image/video | | core/audio | Audio | Native <audio> with controls | | core/video | Video | Native <video> with controls | | core/file | File | Download button | | core/separator | Separator | | | core/spacer | Spacer | | | core/table | Table | Head / body / foot | | core/embed | Embed | YouTube, Vimeo (responsive iframe), Twitter (blockquote), generic | | Any other block | DefaultBlock | Falls back to raw innerHTML |

Custom serializers

Override how any block renders by passing userSerializers:

const serializers = {
  'core/quote': ({ content, citation, children }) => (
    <blockquote className="my-quote">
      {children}
      {citation && <cite>{citation}</cite>}
    </blockquote>
  ),
};

<BlockContent blocks={blocks} userSerializers={serializers} />

The serializer receives the block's attributes spread as props, plus a children prop for blocks with nested inner blocks. The key is the Gutenberg block name (core/quote, core/heading, etc.).

Theming

All visual styles are driven by CSS custom properties prefixed with --bb-*. Override them on any wrapper to retheme:

.my-content {
  --bb-color-primary: #4f46e5;
  --bb-font-family: 'Inter', sans-serif;
  --bb-content-width: 720px;
}

See src/css/tokens.css for the full token list. Key tokens:

| Token | Default | Description | |-------|---------|-------------| | --bb-color-text | #191e23 | Body text color | | --bb-color-bg | #fff | Background color | | --bb-color-primary | #0693e3 | Links, buttons | | --bb-font-family | System sans-serif | Body font stack | | --bb-font-size-base | 16px | Base font size | | --bb-line-height | 1.8 | Body line height | | --bb-content-width | 610px | Max content width | | --bb-block-margin | 28px | Vertical spacing between blocks |

Demo

pnpm demo

Boots a Dockerized WordPress instance with seeded block content plus a Next.js demo site at http://localhost:3000.

pnpm demo:down   # Stop and remove containers + volumes

Development

pnpm install     # Install dependencies
pnpm dev         # Start webpack dev server
pnpm build       # Build to lib/
pnpm test        # Run tests (Jest)
pnpm typecheck   # TypeScript check
pnpm lint        # ESLint

Project structure

praser/
├── src/
│   ├── components/         # One directory per block type
│   ├── Utils/              # blocksToElements, getSerializers, cleanName
│   ├── css/
│   │   ├── tokens.css      # All CSS custom properties
│   │   ├── base.css        # Global resets + base styles
│   │   └── blocks/         # Per-block styles
│   └── index.ts            # Package entry — exports BlockContent + all components
├── lib/                    # Build output (not committed)
└── docs/                   # VitePress documentation site

License

GPL-3.0-or-later