README

Blocksmith brings visual block selection to your Craft CMS Matrix fields.
Say goodbye to long dropdown lists - Blocksmith transforms block selection into an intuitive and elegant experience. Choose between two UI modes: Button Group or Preview Modal (Pro only) - individually configurable per Matrix field. Both are fully compatible with Inline and Cards view modes.

Key Features

Lite Edition

• Full Cards view compatibility
  Blocksmith fully supports Craft’s Cards view mode - including the ability to insert cards above or before existing ones.

• Button Group UI mode
  Quickly insert blocks via contextual buttons. Fully compatible with both Inline and Cards views, including Grid mode.

• Grouped Button Group entries
  Organize Button Group entries using Craft’s native Entry Type Groups - ideal for keeping large sets of block types structured and easy to navigate (requires Craft 5.8+).

• Context menu enhancements
  Add blocks directly above existing ones with the "Add block above" option - seamlessly replacing Craft’s native “Add {entry type} above” buttons with the Blocksmith UI.

Pro Edition

Includes all Lite features, plus:

• Preview Modal UI mode
  A visual modal interface for selecting blocks. Includes image previews, category tabs, and search - fully compatible with both Inline and Cards views, including Grid mode.

• Dynamic modal layout
  Block previews are displayed in a gapless Masonry grid that adapts to varying image heights - for a clean and aesthetic visual experience.

• Categories management
  Define custom categories for your block types and display them as tabs in the Preview Modal - useful for filtering and organizing large block libraries.

• Flexible preview image handling
  Upload custom preview images via the Craft Asset Browser, or use handle-based image files stored in either an Asset Volume or the public folder @webroot/blocksmith/previews (ideal for teams using version control or automated deployment workflows).

• Block settings management
  Easily manage block descriptions and preview images directly within the "Configure Blocks" section.

Language support

Blocksmith is localized in:
Arabic, Chinese, Czech, Danish, Dutch, English, French, German, Greek, Hebrew, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Swedish, Turkish, Ukrainian. Need another language? Feel free to contact us or submit a feature request.

Requirements

• Craft CMS: 5.0.0+
• PHP: 8.2+

Installation

Install Blocksmith via the Craft Plugin Store
or using Composer:

composer require mediakreativ/craft-blocksmith
./craft plugin/install blocksmith

Feedback & Support

Your feedback helps us improve! For feature requests or bug reports, please submit an issue on GitHub. You can also reach us directly via email at plugins@mediakreativ.de.