@snapwp/blocks

A React component library for rendering and hydrating WordPress Blocks from their block data.

[!WARNING] 🐉 There be dragons! This project is in active development and considered experimental. Some features may be incomplete, unstable, or subject to change.

Installation

npm install @snapwp/blocks

Features

• Additive DX: Just include or extend the Block Components you need, and fallback to default rendering for the rest.
• Custom Block Definitions: Override components on a block-level, or even entire patterns, template parts, and templates.
• Fallback Rendering: Uses html-react-parser to let you transform your WordPress data on even an HTML element level.
• Comprehensive Support: Includes an ever-growing list of strongly-typed Block Components that can be used to recreate or enhance the block HTML markup.

When combined with a headless WordPress framework like SnapWP, this library offers parity with many modern WordPress features out of the box.

Usage

Basic Rendering

<EditorBlocksRenderer
	editorBlocks={ editorBlocks } // Array of blocks to render
	blockDefinitions={ blockDefinitions } // Optional custom block definitions
/>

Override Block Definitions

const blockDefinitions = {
	CoreParagraph: CustomCoreParagraph,
};

<EditorBlocksRenderer
	editorBlocks={ editorBlocks }
	blockDefinitions={ blockDefinitions }
/>;

Included Block Components

These components provide developer-friendly APIs for rendering core WordPress blocks. If a WordPress block does not have a corresponding component, it will fallback to the Default block component, which uses html-react-parser under the hood.

| Type | Component | | ------------------ | ---------------- | | core-audio | CoreAudio | | core-button | CoreButton | | core-buttons | CoreButtons | | core-code | CoreCode | | core-column | CoreColumn | | core-columns | CoreColumns | | core-cover | CoreCover | | core-details | CoreDetails | | core-file | CoreFile | | core-freeform | CoreFreeform | | core-gallery | CoreGallery | | core-group | CoreGroup | | core-heading | CoreHeading | | core-html | CoreHtml | | core-image | CoreImage | | core-list | CoreList | | core-list-item | CoreListItem | | core-media-text | CoreMediaText | | core-paragraph | CoreParagraph | | core-post-content | CorePostContent | | core-preformatted | CorePreformatted | | core-pullquote | CorePullquote | | core-quote | CoreQuote | | core-separator | CoreSeparator | | core-spacer | CoreSpacer | | core-template-part | CoreTemplatePart | | core-verse | CoreVerse | | core-video | CoreVideo | | default | Default |

Known Limitations

Work is ongoing for full feature parity with Gutenberg, in particular around Block Supports and certain aspects of the Interactivity API. The following functionality is coming soon:

• Duotone Filters
• Image Lightboxes
• @todo

Contributing

This package is part of SnapWP's monorepo and is actively maintained by rtCamp. Packages are published to npm from the packages directory, and can be used standalone in the headless WordPress ecosystem or as part of SnapWP's framework.

Contributions are welcome and encouraged! To learn more about contributing to this package or SnapWP as a whole, please read the Contributing Guide.

For development guidelines, please refer to our Development Guide.

Want to expand what's possible with WordPress?