How to Customize the Toolbar

This guide covers how to customize your site's Toolbar utilizing the toolbarNodes filter.

Add the Toolbar to your project

info

The Toolbar is currently an experimental feature that was introduced in @faustwp/core@0.2.5.

Add styles

The (Faust) Toolbar shares mostly the the same HTML as the WordPress core Toolbar. This enables the use of the same styles that exist in WordPress core, and have been converiently provided for you to import within @faustwp/core.

pages/_app.js

import '@faustwp/core/dist/css/toolbar.css';

Enable toolbar

Add experimentalToolbar: true to your project's faust.config.js.

faust.config.js

import { setConfig } from '@faustwp/core';
import templates from './wp-templates';
import possibleTypes from './possibleTypes.json';

export default setConfig({
  experimentalToolbar: true, // Enable experimental toolbar
  templates,
  possibleTypes,
});

Login to your site

The Toolbar was designed to only load for authenticated user.

tip

A WordPress user will be automatically authenticated with your site when previewing a post. This approach can be used as a quick way view the Toolbar for development purposes.

See Authentication for more details about implementing auth within Faust.

Create the plugin

Create a new file in your Faust project: plugins/CustomPlugin.tsx.

info

See Creating a Plugin for additional information about Faust's plugin system.

Add the following code to plugins/CustomPlugin.tsx.

plugins/CustomPlugin.tsx

import React from 'react';
import {
  FaustHooks,
  FaustPlugin,
  FaustToolbarNodes,
  FaustToolbarContext,
  ToolbarItem,
  ToolbarSubmenu,
  ToolbarSubmenuWrapper,
} from '@faustwp/core';

/**
 * Example Custom Toolbar Plugin.
 */
export class CustomToolbar implements FaustPlugin {
  apply(hooks: FaustHooks) {
    /**
     * This example demonstrates how to filter on the core Toolbar nodes
     * in order to add your own custom nodes!
     */
    hooks.addFilter(
      'toolbarNodes',
      'faust',
      (toolbarNodes: FaustToolbarNodes, context: FaustToolbarContext) => {
        const customToolbarNodes: FaustToolbarNodes = [
          {
            id: 'custom-node',
            location: 'primary',
            component: <CustomNode />,
          },
          {
            id: 'custom-node-with-submenu',
            location: 'primary',
            component: <CustomNodeWithSubmenu />,
          },
        ];

        return [...toolbarNodes, ...customToolbarNodes];
      },
    );
  }
}

/**
 * A simple link.
 */
export function CustomNode() {
  return (
    <ToolbarItem href="https://wpengine.com" rel="nofollow">
      Custom Node
    </ToolbarItem>
  );
}

/**
 * A simple link with a submenu that displays on hover.
 */
export function CustomNodeWithSubmenu() {
  return (
    <>
      <ToolbarItem href="https://wpengine.com" rel="nofollow">
        Custom Node w/ Submenu
      </ToolbarItem>
      <ToolbarSubmenuWrapper>
        <ToolbarSubmenu>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
          <li>
            <ToolbarItem href="https://wpengine.com" rel="nofollow">
              Link
            </ToolbarItem>
          </li>
        </ToolbarSubmenu>
      </ToolbarSubmenuWrapper>
    </>
  );
}

Register The Plugin

Import and register your new plugin in faust.config.js.

faust.config.js

import { setConfig } from '@faustwp/core';
import templates from './wp-templates';
import possibleTypes from './possibleTypes.json';
import { CustomToolbar } from './plugins/CustomToolbar.js';

export default setConfig({
  templates,
  experimentalToolbar: true,
  experimentalPlugins: [new CustomToolbar()], // Register plugin
  possibleTypes,
});

You should now be able to see your new Custom Nodes.