How to add custom Redactor toolbars to the default Rich Text field in Craft CMS

The default Rich Text field in Craft CMS comes with three options to use as your toolbar: Default, Simple, and Standard.

If you'd like to add custom toolbars, you can do so by adding custom toolbar config file in your craft/config/redactor folder. Redactor is the WYSIWYG html editor that Craft uses for its Rich Text field and a Redactor config file is a json file that tells Redactor what settings it should be using to build your toolbar.

Create a custom toolbar #

Let's create a new toolbar called 'Simple With Link' which is just like the default Rich Text 'Simple' config but adds a link button as well.

To create this new toolbar, create a new Simple With Link.json file in your craft/config/redactor folder and add the following json code:

{
    buttons: ['bold', 'italic', 'link']
}

Let's take a closer look at what each part of this code does:

{ Begin the json object
buttons Use the keyword 'buttons' to tell Redactor that we want to add some button settings and what follows will be an array of buttons that we want to use in our toolbar
: The colon after our keyword 'buttons' separates our keyword from the array of settings that it is associated with
[ Begin our toolbar settings array
'bold' Use the keyword 'bold' to display a bold button
, Separate values in our array with a comma
'italic' Use the keyword 'italic' to display a bold button
, Separate values in our array with a comma
'link' Use the keyword 'link' to display a bold button
] End our toolbar settings array
} End the json object

To view the list of buttons that are available, you can take a look at the 'buttons' setting in the Redactor documentation.

Create a Rich Text field with a fixed height #

Let's take a look at a slightly more advanced toolbar config now. We'll keep the toolbar buttons simple so we can focus on what else is happening here. In the following config, we create a toolbar which includes a bold and italic button and we add two new settings which allow us to set a fixed height for our Rich Text field.

{
    buttons: ['bold', 'italic'],
    autoresize: false,
    minHeight: 400
}

Let's take a closer look at how the autoresize and minHeight settings are being used in our toolbars json settings object:

{ Begin the json object
autoresize Use the keyword 'autoresize' to tell Redactor that we want to set the option for height autoresizing
: The colon separates our keyword from the following settings value it is associated with
false Setting the 'autoresize' setting to false tells Redactor that we want our Rich Text field to have a fixed height.
, Separate each key/value pair in our settings object with a comma
minHeight Redactor does not have a 'height' option, so now that we've set our Rich Text field to have a fixed height with the 'autoresize' setting, we can use the 'minHeight' setting to set the height that we want.
: The colon separates our keyword from the following settings value it is associated with
400 The number we use for our 'minHeight' setting will be the number of pixels high we want our Rich Text field to be
} End the json object

You can find both the 'autoresize' setting and the 'minHeight' setting in the Redactor documentation.

How do the Redactor docs relate to our Rich Text toolbar settings? #

If you've referred to any of the Redactor docs linked above, you'll notice that in the Redactor documentation, we see these settings being used in examples which use a line of javascript. In our custom toolbar settings files however, we only need to use the json object. Let's take a quick look at how the Redactor docs relate to our Rich Text toolbar settings files.

In the Redactor docs, to set autoresize we see the following code:

$('#redactor').redactor({ autoresize: false });

In our use case with Craft, the actual javascript doesn't matter here. Craft is handling the Rich Text field type and will run the necessary javascript code for us: $('#redactor').redactor();. The settings we are preparing in our json object will be handed off to that javascript, so we just need to focus on the json object that is being passed to the examples in the Redactor docs { autoresize: false }.

Let's look at that example again and rename some of the variables to how they are being used in the context of Craft:

$('#idOfOurRichTextFieldInCraft').redactor( ourCustomToolbarSettings );

idOfOurRichTextFieldInCraft: We don't have to worry about this setting, Craft will handle it and set it up when we create our Rich Text field.
ourCustomToolbarSettings: This is the json object we create and place in our toolbar.json file in the craft/config/redactor folder

{
    buttons: ['bold', 'italic'],
    autoresize: false,
    minHeight: 400
}

Customize the formatting dropdown menu to only include the html tags you want #

Some of the buttons in our Rich Text toolbar also have secondary settings that we can customize. The formatting button provides the user a dropdown menu of several HTML tags to choose from. By default, the formatting button includes all of its supported tags ['p', 'blockquote', 'pre', 'h1', 'h2', 'h3', 'h4']. We can customize that list of tags using the 'formattingTags' setting. Here's how that would look:

{
    buttons: ['formatting', 'bold', 'italic'],
    formattingTags: ['h2', 'h3', 'p', 'blockquote']
}

Let's walk through this one step by step:

{ Begin the json object
buttons Use the keyword 'buttons' to tell Redactor that we want to add some button settings and what follows will be an array of buttons that we want to use in our toolbar
: The colon separates our keyword from the following settings value it is associated with
['formatting', 'bold', 'italic'] This is our 'buttons' settings array. The button 'formatting' has additional settings which we can set using the 'formattingTags' setting we've set below.
, Separate each key/value pair in our settings object with a comma
formattingTags Use the keyword 'formattingTags' to tell Redactor that, if the 'formatting' button is in use, we want to customize which HTML tags it uses.
: The colon separates our keyword from the following settings value it is associated with
['h2', 'h3', 'p', 'blockquote'] This is our 'formattingTags' settings array and lists all of the supported HTML tags that we want to include in the dropdown menu for our 'formatting' button.
} End the json object

Bring it all together #

There are a lot more settings you can explore in the Redactor documentation. While we've tried to keep the above examples simple to illustrate specific things, we can also combine all of these settings and create more advanced customized toolbars. Here's what a toolbar using all of the above customizations (and a few more) would look like:

{
  buttons: ['html', 'formatting', 'bold', 'italic','link'],
  plugins: ['fullscreen'],
  formattingTags: ['h2', 'h3', 'p', 'blockquote'],
  autoresize: false,
  minHeight: 400
}

View and download more custom Redactor configs and submit your own custom toolbars to help us build a library of examples we can all use in our projects or just for inspiration.

Don't miss any Craft tips, tricks, and community updates