Extending Bard

The Bard fieldtype is a rich-text and block-based editor based on Tiptap, which in turn is a Vue component that wraps around ProseMirror — a robust JavaScript framework for building rich-text editors that don't directly write HTML or rely on contenteditable, but rather a document model.

Required Reading

Before you attempt to create any Bard extensions, it is wise to learn how to write a Tiptap extension first. Otherwise you’d be trying to learn how to ride a motorcycle before you can even ride a bike. Or a unicycle before you can juggle. To have a better understanding of how to write a Tiptap extension, you’d in turn benefit greatly on reading about how ProseMirror works.

Hot Tip!

Writing custom extensions for Bard is pretty complicated, but can be rewarding and provide powerful results.

In short, here’s a quick-start of the things you should probably start with:


Adding New Extensions

You may add your own Tiptap extensions to Bard using the addExtension method. The callback may return a single extension, or an array of them.

const { Node, Mark, Extension } = Statamic.$bard.tiptap.core;
Statamic.$bard.addExtension(() => Node.create({...}));
Statamic.$bard.addExtension(() => {
return [

Check out Tiptap’s custom extension documentation and code samples for the core Tiptap extensions to find out how to write an extension.

If you’re providing a new mark or node and intend to use this Bard field on the front-end, you will also need to create a Mark or Node class to be used by the PHP renderer.

Hot Tip!

If you need any other Tiptap helpers or utilities you can use our Tiptap API.

Replacing Existing Extensions

If you’d like to replace a native extension (e.g. headings or paragraphs) you can use the replaceExtension method. It takes the name of the extension, and a callback that returns a single extension instance.

const { Node } = Statamic.$bard.tiptap.core;
Statamic.$bard.replaceExtension('heading', ({ extension, bard }) => {
return Node.create({
name: 'heading',

The callback will provide you with the existing extension instance, so if you are doing simple tweaks to an extension (e.g. customizing an input rule) you can simply extend the existing instance. Then you don’t need to author an entire extension:

const { nodeInputRule } = Statamic.$bard.tiptap.core;
Statamic.$bard.replaceExtension('heading', ({ extension, bard }) => {
return extension.extend({
addInputRules() {
return [

You can also reconfigure extensions (e.g. to add Tailwind classes to headings or disable specific “smart typography” rules):

Statamic.$bard.replaceExtension('heading', ({ extension, bard }) => {
return extension.configure({
HTMLAttributes: {
class: 'font-bold',
Statamic.$bard.replaceExtension('typography', ({ extension, bard }) => {
return extension.configure({
oneHalf: false,
oneQuarter: false,
threeQuarters: false,


To add a button to the toolbar, provide a callback to the buttons method.

The callback will receive two arguments:

  • buttons - an array of the existing buttons in the toolbar (more about that in a moment)
  • button - a function that wraps your button objects

The callback may return a button object, or an array of them.

Statamic.$bard.buttons((buttons, button) => {
return button({
name: 'custom_bold',
text: __('Custom Bold'), // Tooltip text
svg: 'bold', // Name of an SVG icon
html: '<svg>...</svg>', // Custom icon HTML
args: { class: 'font-bold' }, // The command arguments
command: (editor, args) => editor.chain().focus().setCustomBold(args).run(), // The command to run
activeName: 'customBold', // The active node/mark type that will activate this button (falls back to name)
active: (editor, args) => editor.isActive('bold'), // Active check callback (overrides activeName)
visibleWhenActive: 'example', // The active node/mark type that will show this button (always visible if not set)
visible: (editor, args) => editor.isActive('example'), // Visible check callback (overrides visibleWhenActive)
Statamic.$bard.buttons((buttons, button) => [

Returning values to the buttons method will push them onto the end. If you need more control, you can manipulate the supplied buttons argument, and then return nothing. For example, we’ll add a button after wherever the existing bold button happens to be:

Statamic.$bard.buttons((buttons, button) => {
const indexOfBold = _.findIndex(buttons, { name: 'bold' });
buttons.splice(indexOfBold + 1, 0, button({...}));
Hot Tip!

Using the button() method will make the button only appear if the Bard field has been configured to show your button.

If you’d like your button to appear on all Bard fields, regardless of whether it’s been configured to use that button, you can just return an object. Don’t wrap with button().

Tiptap API

In your extensions, you may need to use functions from the tiptap library. Rather than importing the library yourself and bloating your JS files, you may use methods through our API.

Statamic.$bard.tiptap.core; // `tiptap` (core, commands, utilities and helpers)
Statamic.$bard.tiptap.pm.state; // `prosemirror-state`
Statamic.$bard.tiptap.pm.model; // `prosemirror-model`
Statamic.$bard.tiptap.pm.view; // `prosemirror-view`

You could shorten things up by using destructuring. For example:

const { InputRule, insertText, getAttributes } = Statamic.$bard.tiptap.core;
new InputRule(...);

Tiptap PHP Rendering

If you have created an extension on the JS side to be used inside the Bard fieldtype, you will need to be able to render it on the PHP side (in your views).

The Bard Augmentor class is responsible for converting the ProseMirror structure to HTML.

You can use the addExtension or replaceExtension methods to bind an extension class into the renderer. Your AppServiceProvider’s boot method is a good place to do this.

use Statamic\Fieldtypes\Bard\Augmentor;
public function boot()
// Pass an object
Augmentor::addExtension('myExtension', new MyExtension);
// or a closure. You will be passed the bard fieldtype and an array of options as arguments.
Augmentor::addExtension('myExtension', function ($bard, $options) {
return new MyExtension(['foo' => $bard->config('should_foo')];
// Same for replacing extensions.
Augmentor::replaceExtension('paragraph', new MyCustomParagraph);
// Closures too. There will be an additional argument at the front which is the existing extension.
Augmentor::replaceExtension('paragraph', function ($existing, $bard, $options) {
return new CustomParagraph;

Check out code samples for the core Tiptap extensions to find out how to write PHP extensions.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →