Introduction
Usage
Once configured, you will begin to see the Matrix Field Preview "modal button" and "inline previews" appear in the matrix fields within your entry types.
Modal Overlay
When your editors are working on matrix fields, the button for adding a new block to the field will launch a modal overlay including previews of the blocks:
This overlay has a few features:
- The matrix field blocks. These are all of the blocks available the matrix field being edited. Editors will see a preview screenshot, a title and a short description (if added).
- Search input. Editors can search through blocks by title or description. This field is autofocused by default for efficiency.
- Category filters. The lefthand sidebar displays the categories that have been configured, allowing editors to narrow down their search to particular types of content.
Keyboard Navigation
When the modal is open, you can use keyboard arrows to make it quicker to add blocks. When the modal opens, the search input will be automatically focussed. Hit tab or the ↓ or → arrow on the keyboard to start selecting blocks using the keyboard. Hit enter or space to select the highlighted block.
Takeover
By default, the Matrix Field Preview modal will replace the default "add block" button.
This is called "takeover". If disabled, instead of completely replacing the button, an additional "content preview" button will appear beside the "add block" button:
Inline Previews
When editing entries in the Craft CMS control panel, there will now be "inline" preview images for all matrix field blocks. These are small thumbnail images alongside the title & description:
These are useful to give editors a visual reminder of what each block looks like on the page. Each thumbnail can be hovered-over to see the full thumbnail image:
Other View Modes
Craft has a number of different "view modes" available for matrix fields. These are essentially different ways of rendering the matrix field to users:
- Cards
- Card grid
- Blocks
- Index
In the above examples, you'll see screenshots of the traditional "blocks" view mode. Matrix Field Preview works with all four of these views, although not all features are supported for every view mode:
| View | Has Button & Modal | Has Inline Previews |
|---|---|---|
| Cards | ✅ | ❌ |
| Card Grid | ✅ | ❌ |
| Blocks | ✅ | ✅ |
| Index | ✅ | ❌ |
Why no inline previews?
The reason that we don't have inline previews for the card and index view modes is that the interface can already be customised via native Craft functionality to show previews, without needing our plugin. See "custom card attributes" in the Craft docs for more.
Blocks
"Blocks" is the traditional matrix field view. When using this view, a preview button is added to the matrix field as well as the inline previews
Cards & Index
For "Cards", "Card grid" and "index" views, the preview button is added to the matrix field, but there are no inline previews (it's possible to use native Craft features to handle this)
