https://github.com/k11k-labs/better-blocks-react-renderer
React renderer for Strapi v5 Blocks content with color and backgroundColor support from Better Blocks plugin
https://github.com/k11k-labs/better-blocks-react-renderer
better-blocks blocks-editor color headless-cms highlight open-source react renderer rich-text strapi strapi-v5 typescript
Last synced: 3 months ago
JSON representation
React renderer for Strapi v5 Blocks content with color and backgroundColor support from Better Blocks plugin
- Host: GitHub
- URL: https://github.com/k11k-labs/better-blocks-react-renderer
- Owner: k11k-labs
- License: mit
- Created: 2026-03-11T20:12:46.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-28T16:54:05.000Z (3 months ago)
- Last Synced: 2026-03-28T18:32:54.841Z (3 months ago)
- Topics: better-blocks, blocks-editor, color, headless-cms, highlight, open-source, react, renderer, rich-text, strapi, strapi-v5, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@k11k/better-blocks-react-renderer
- Size: 547 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Better Blocks React Renderer
React renderer for Strapi v5 Blocks content — supports all standard blocks plus Better Blocks features: color, highlight, text alignment, nested lists, to-do lists, tables, media embeds, image captions, and more.
---
## Table of Contents
1. [Why?](#why)
2. [Compatibility](#compatibility)
3. [Installation](#installation)
4. [Usage](#usage)
5. [Supported Blocks](#supported-blocks)
6. [Supported Modifiers](#supported-modifiers)
7. [Custom Renderers](#custom-renderers)
8. [TypeScript](#typescript)
9. [Contributing](#contributing)
10. [License](#license)
---
## Why?
The official [`@strapi/blocks-react-renderer`](https://github.com/strapi/blocks-react-renderer) doesn't support the features that the [Better Blocks](https://github.com/k11k-labs/strapi-plugin-better-blocks) plugin adds to the Strapi editor — color marks, text alignment, to-do lists, tables, media embeds, and more.
This package is a **drop-in replacement** that renders all Better Blocks features out of the box — no configuration needed.
## Compatibility
| Strapi Version | Renderer Version | React Version |
| -------------- | ---------------- | ------------- |
| v5.x | v0.x | ≥ 17 |
## Installation
```bash
# Using yarn
yarn add @k11k/better-blocks-react-renderer
# Using npm
npm install @k11k/better-blocks-react-renderer
```
**Peer dependencies:** `react >= 17`
## Usage
```tsx
import { BlocksRenderer } from '@k11k/better-blocks-react-renderer';
// Basic — renders all blocks including color/highlight
;
```
That's it. All Better Blocks features — colors, tables, to-do lists, media embeds, alignment, and more — work automatically.
## Supported Blocks
| Block | Default element | Source |
| ------------------------------- | ------------------- | --------------------------- |
| `paragraph` | `
` | Strapi core |
| `heading` (1–6) | `
`–`` | Strapi core |
| `list` (ordered/unordered/todo) | `` / `` | Strapi core + Better Blocks |
| `list-item` | `- ` | Strapi core |
| `link` | `` | Strapi core |
| `quote` | `` | Strapi core |
| `code` | `` | Strapi core |
| `image` | `![]()
` | Strapi core |
| `horizontal-line` | `
` | Better Blocks |
| `table` | `` | Better Blocks |
| `media-embed` | `` (16:9) | Better Blocks |
### Block properties
| Property | Applies to | Description |
| ------------- | ------------------------- | ----------------------------------------------------- |
| `textAlign` | paragraph, heading, quote | Text alignment (`left`, `center`, `right`, `justify`) |
| `lineHeight` | paragraph, heading, quote | CSS line-height value (e.g. `1.5`, `2.0`) |
| `indent` | paragraph, heading, quote | Block indentation level (`marginLeft: N * 2rem`) |
| `indentLevel` | list | Cycling list-style-type per nesting depth |
| `format` | list | `ordered`, `unordered`, or `todo` |
| `checked` | list-item (in todo lists) | Checkbox state (`true`/`false`) |
| `target` | link | `_blank` for new-tab links |
| `rel` | link | `noopener noreferrer` for new-tab links |
| `caption` | image | Text displayed below the image |
| `imageAlign` | image | Image alignment (`left`, `center`, `right`) |
| `url` | media-embed | Embed URL (YouTube/Vimeo iframe src) |
| `originalUrl` | media-embed | Original user-provided URL |
## Supported Modifiers
| Modifier | Default element | Source |
| ----------------- | ---------------------------------- | ------------- |
| `bold` | `` | Strapi core |
| `italic` | `` | Strapi core |
| `underline` | `` | Strapi core |
| `strikethrough` | `` | Strapi core |
| `code` | `` | Strapi core |
| `uppercase` | `` | Better Blocks |
| `superscript` | `` | Better Blocks |
| `subscript` | `` | Better Blocks |
| `color` | `` | Better Blocks |
| `backgroundColor` | `` | Better Blocks |
| `fontFamily` | `` | Better Blocks |
| `fontSize` | `` | Better Blocks |
## Custom Renderers
### Custom block renderers
Override any block type with your own component:
```tsx
(
{children}
),
heading: ({ children, level, style }) => {
const Tag = `h${level}`;
return {children};
},
link: ({ children, url, target, rel }) => (
{children}
),
image: ({ image, caption, imageAlign }) => (
{caption && {caption}}
),
'list-item': ({ children, checked }) =>
checked !== undefined ? (
-
{children}
) : (
- {children}
),
'horizontal-line': () =>
,
table: ({ children }) => {children},
'table-header-cell': ({ children }) => {children},
'table-cell': ({ children }) => {children},
'media-embed': ({ url }) => (
),
}}
/>
```
### Custom modifier renderers
Override any text modifier with your own component:
```tsx
{children},
color: ({ children, color }) => {children},
backgroundColor: ({ children, backgroundColor }) => (
{children}
),
}}
/>
```
## TypeScript
All types are exported:
```ts
import type {
BlocksContent,
BlocksRendererProps,
BlockNode,
TextNode,
LinkNode,
ListNode,
ListItemNode,
ParagraphNode,
HeadingNode,
QuoteNode,
CodeNode,
ImageNode,
HorizontalLineNode,
TableNode,
TableRowNode,
TableCellNode,
TableHeaderCellNode,
MediaEmbedNode,
TextAlign,
CustomBlocksConfig,
CustomModifiersConfig,
} from '@k11k/better-blocks-react-renderer';
```
## Contributing
Contributions are welcome! The easiest way to get started is with Docker:
```bash
# Clone the repository
git clone https://github.com/k11k-labs/better-blocks-react-renderer.git
cd better-blocks-react-renderer
# Start the playground with Docker
cd playground
docker compose up
```
This will start a Strapi v5 instance with the Better Blocks plugin and a React app that renders the content — all pre-configured with a showcase article.
- **Strapi admin:** http://localhost:1337/admin (login: `admin@example.com` / `admin12#`)
- **React app:** http://localhost:5173
### Development workflow
1. Make changes to the renderer source in `src/`
2. Rebuild: `yarn build` (from repo root)
3. The React app picks up the new build automatically
### Without Docker
```bash
# Build the renderer
yarn install && yarn build
# Start Strapi
cd playground/strapi && cp .env.example .env && npm install && npm run dev
# Start the React app (in another terminal)
cd playground/react-app && npm install && npm run dev
```
### Running tests
```bash
yarn test # Run tests
yarn test:ts # Type check
yarn lint # Check formatting
```
## Community & Support
- [GitHub Issues](https://github.com/k11k-labs/better-blocks-react-renderer/issues) — Bug reports and feature requests
## Related
- [@k11k/strapi-plugin-better-blocks](https://github.com/k11k-labs/strapi-plugin-better-blocks) — Strapi plugin that extends the Blocks editor with colors, tables, to-do lists, media embeds, and more
- [@strapi/blocks-react-renderer](https://github.com/strapi/blocks-react-renderer) — Official Strapi renderer (standard blocks only)
## License
[MIT License](LICENSE) © [k11k-labs](https://github.com/k11k-labs)