/handbook/developing-for-block-editor-and-site-editor/custom-toolbar/
What We Do
Digital Platform MigrationsKey SolutionsManaged ServicesStaffing SolutionsIndustriesProducts
OnePress
Unify multiple brands on one governed WordPress platform.
Design & UI/UX
Gutenberg-native UX, UI, and design systems for visitors and editors.
WordPress Modernization
Modernize WordPress for better performance, architecture, and AI readiness.
WordPress as a DXP
WordPress as a composable DXP when monolithic systems no longer cut it.
Headless WordPress
Omnichannel content delivery without sacrificing marketing autonomy.
Frappe/ERPNext
Build scalable ERP and custom applications, from implementation to ongoing support.
Discovery
Strategic consultancy & project roadmap
Growth Services
On demand development & consultation
Site Maintenance
Annual maintenance. Done for you
QE Services
Testing across SDLC for assured quality
Hosting Migration
Move to a performant hosting with zero downtime
WooCommerce
Enterprise commerce delivered without lock-in
AI
Unlock real use cases and integrations
All Services
A suite of services for any need
Technology STACK
eCommerce
Scale your e-commerce with WooCommerce, integrations, and custom extensions for growth.
EasyEngine
Server management tool that makes using WordPress on Nginx easy.
Web Auditor
Performance Audit & Insights for your Website.
rtMedia
A complete media management plugin for WordPress.
Resources
About Us
CLEAR
Resources Developing for Block Editor and Site Editor Extending the editor Creating custom block toolbar
Topics
On this page
Understanding the Block Toolbar
Using the BlockControls Component
Grouping Toolbar Buttons
Using ToolbarDropdownMenu for Multiple Actions
Best Practices for Designing Block Toolbars
Making Toolbars Accessible
Keyboard Accessibility and Shortcuts in Toolbars
Contextual Toolbars for Dynamic Block States
Handling Loading and Disabled States in Toolbar Actions
Performance Considerations for Custom Toolbars
Minimize Re-Renders
Lazy Load Data
Reduce Expensive Operations
Last updated on Mar 31, 2026
Creating Custom Block Toolbar
Block toolbars are an essential part of the WordPress editor experience, offering users quick access to frequently used controls directly on the block itself. These toolbars provide inline, contextual actions like text formatting, alignment, or custom features that are relevant to the selected block. In this guide, we’ll walk through how to create custom block toolbars for your blocks and enhance the editing experience.
Block toolbar
Understanding the Block Toolbar
In the Gutenberg editor, the BlockControls component is used to add custom buttons and actions to the block toolbar. This toolbar typically appears above the block when the user selects it, providing easy access to important settings.
The toolbar can include buttons for:
- Text formatting: Bold, italic, underline, etc.
- Alignment: Align left, center, or right.
- Custom actions: Any custom functionality that suits your block’s behavior.
Why do Toolbars Matter?
Toolbars enhance usability by allowing users to perform quick actions without diving into sidebar settings, making the block editor more intuitive and efficient.
Using the BlockControls Component
The BlockControls component is the foundation for adding toolbar buttons to your blocks. By wrapping your custom toolbar buttons inside, they will integrate seamlessly into the WordPress editor, appearing when the user selects the associated block.
Example: Adding a Custom Toolbar Button
Let’s start by adding a simple button to the toolbar for a custom action. In this case, we’ll add a “Bold Text” button that toggles bold formatting on the selected text.
import { __ } from "@wordpress/i18n";
import { BlockControls } from "@wordpress/block-editor";
import { ToolbarGroup, ToolbarButton } from "@wordpress/components";
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { isBold } = attributes;
const toggleBold = () => setAttributes({ isBold: !isBold });
return (
<div>
<BlockControls>
<ToolbarGroup>
<ToolbarButton
label={__("Bold Text")}
icon="editor-bold"
isActive={isBold}
onClick={toggleBold}
/>
</ToolbarGroup>
</BlockControls>
<p style={{ fontWeight: isBold ? "bold" : "normal" }}>
This is some text content.
</p>
</div>
);
};
export default Edit;
BlockControls: Wraps the toolbar buttons and ensures they appear when the block is selected.ToolbarButton: Adds a button with an icon for “Bold Text” formatting. The button toggles between bold and normal text states based on the “isBold” attribute.
Grouping Toolbar Buttons
To keep toolbars organized, you can group related actions using the ToolbarGroup component. This ensures that users can find relevant actions in one place without cluttering the interface.
Example: Grouping Alignment Buttons in the Toolbar
import { BlockControls } from "@wordpress/block-editor";
import { ToolbarGroup, ToolbarButton } from "@wordpress/components";
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { textAlign } = attributes;
const setAlignment = (alignment) => setAttributes({ textAlign: alignment });
return (
<div>
<BlockControls>
<ToolbarGroup>
<ToolbarButton
label="Align Left"
icon="editor-alignleft"
onClick={() => setAlignment("left")}
isActive={textAlign === "left"}
/>
<ToolbarButton
label="Align Center"
icon="editor-aligncenter"
onClick={() => setAlignment("center")}
isActive={textAlign === "center"}
/>
<ToolbarButton
label="Align Right"
icon="editor-alignright"
onClick={() => setAlignment("right")}
isActive={textAlign === "right"}
/>
</ToolbarGroup>
</BlockControls>
<p style={{ textAlign }}>{"Aligned text"}</p>
</div>
);
};
export default Edit;
ToolbarGroup: Groups multiple related toolbar buttons together.ToolbarButton: Adds alignment options (left, center, right) and visually highlights the active button using the isActive prop.
Using ToolbarDropdownMenu for Multiple Actions
Sometimes, you may have a set of related actions that should be grouped into a dropdown menu rather than individual buttons. This is especially useful when you have more than a few options.
Example: Adding a Dropdown Menu for Text Styles
import { ToolbarGroup, ToolbarDropdownMenu } from "@wordpress/components";
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { textStyle } = attributes;
const setTextStyle = (style) => setAttributes({ textStyle: style });
return (
<div>
<BlockControls>
<ToolbarGroup>
<ToolbarDropdownMenu
icon="editor-textcolor"
label="Text Style"
controls={[
{ title: "Normal", onClick: () => setTextStyle("normal") },
{ title: "Italic", onClick: () => setTextStyle("italic") },
{ title: "Bold", onClick: () => setTextStyle("bold") },
]}
/>
</ToolbarGroup>
</BlockControls>
<p
style={{
fontStyle: textStyle === "italic" ? "italic" : "normal",
fontWeight: textStyle === "bold" ? "bold" : "normal",
}}
>
This is styled text.
</p>
</div>
);
};
export default Edit;
ToolbarDropdownMenu: Creates a dropdown menu with multiple text style options. Users can switch between normal, italic, or bold text styles by selecting from the dropdown.
Best Practices for Designing Block Toolbars
1. Keep the Toolbar Focused
- Toolbars should provide only the most frequently used or relevant controls for the block. Avoid overloading the toolbar with too many options; less critical settings should be placed in the block’s sidebar settings.
2. Group Related Actions
- Group actions that belong together, like alignment or text formatting, to avoid clutter and make it easy for users to find related controls.
3. Use Familiar Icons
- Stick to WordPress’s built-in icons (via the Dashicons library) for consistency and familiarity. Users should be able to recognize the actions at a glance.
4. Provide Clear Labels
- Each button should have a clear and accessible label that describes the action. Use tooltips when necessary to ensure accessibility for all users.
5. Handle Loading and Disabled States
- If the action triggered by a toolbar button involves asynchronous operations (like saving data or fetching content), make sure to handle loading and disabled states appropriately.
Example: Handling a Save Operation with a Disabled Button
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { isSaving } = attributes;
const handleSave = () => {
// Simulate a save operation
setAttributes({ isSaving: true });
setTimeout(() => setAttributes({ isSaving: false }), 2000);
};
return (
<div>
<BlockControls>
<ToolbarGroup>
<ToolbarButton
label="Save"
icon="save"
onClick={handleSave}
isBusy={isSaving}
disabled={isSaving}
/>
</ToolbarGroup>
</BlockControls>
<p>{isSaving ? "Saving..." : "Content"}</p>
</div>
);
};
ToolbarButton with isBusy: The button shows a “loading” state when a save operation is in progress, preventing the user from clicking multiple times.
Making Toolbars Accessible
Toolbars need to be fully accessible for all users, including those using screen readers or keyboard navigation.
Accessibility Tips:
- Use meaningful ARIA labels for buttons.
- Ensure that users can navigate and activate toolbar buttons using the keyboard (focus states and tab order should be clear).
- Provide tooltips for users who rely on visual cues.
Example: Accessible Button with ARIA Label
<ToolbarButton
label="Bold Text"
icon="editor-bold"
onClick={ toggleBold }
aria-label="Toggle bold text"
/>
ARIA Label: Provides an accessible description for screen readers to convey the purpose of the button.
Keyboard Accessibility and Shortcuts in Toolbars
For a great user experience, especially for power users, keyboard shortcuts should be provided where possible. Users should be able to navigate and activate toolbar buttons without relying solely on the mouse.
Best Practices:
- Implement keyboard navigation to move between toolbar buttons (using the tab key).
- Add keyboard shortcuts for frequently used actions (e.g., Ctrl+B for bold text).
Example: Adding Keyboard Shortcuts to Toolbar Buttons
import { ToolbarButton } from "@wordpress/components";
import { useEffect } from "react";
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { isBold } = attributes;
const toggleBold = () => setAttributes({ isBold: !isBold });
// Adding a keyboard shortcut for bold (Ctrl + B)
useEffect(() => {
const handleKeyDown = (event) => {
if (event.ctrlKey && event.key === "b") {
event.preventDefault();
toggleBold();
}
};
window.addEventListener("keydown", handleKeyDown);
return () => {
window.removeEventListener("keydown", handleKeyDown);
};
}, [isBold]);
return (
<div>
<BlockControls>
<ToolbarButton
label="Bold Text"
icon="editor-bold"
onClick={toggleBold}
isActive={isBold}
aria-label="Toggle bold text"
/>
</BlockControls>
<p style={{ fontWeight: isBold ? "bold" : "normal" }}>
This is some boldable text.
</p>
</div>
);
};
export default Edit;
- Keyboard Shortcut: The
useEffecthook listens for the Ctrl+B key combination and triggers the bold action. This is useful for power users who rely on keyboard shortcuts for efficiency. - ToolbarButton: The bold button remains in the toolbar for users who prefer to click, but keyboard users can trigger the same action without leaving the keyboard.
Contextual Toolbars for Dynamic Block States
In some cases, your block might need to display different toolbar buttons depending on the current state of the block. For example, a block could offer different actions based on the selected view mode (list view vs grid view).
Example: Contextual Toolbar for Grid and List Views
{ isGridView ? (
<ToolbarButton label="Switch to List" icon="list-view" onClick={ switchToList } />
) : (
<ToolbarButton label="Switch to Grid" icon="grid-view" onClick={ switchToGrid } />
) }
In this example, the toolbar dynamically changes depending on whether the user is in a grid view or a list view. This ensures the toolbar remains relevant and only shows actions that make sense for the current context.
Explanation:
- The toolbar switches between two buttons, one to switch to list view and one to switch to grid view, depending on the current block state (isGridView).
- This approach improves the user experience by keeping the interface uncluttered and focused on the current task.
Handling Loading and Disabled States in Toolbar Actions
When toolbar actions involve asynchronous processes, such as saving data or fetching content, it’s crucial to handle loading states properly. This provides feedback to users, prevents accidental multiple clicks, and improves the overall user experience.
Best Practices:
- Show a loading indicator when an action is in progress.
- Disable the toolbar button while the action is being processed to prevent multiple clicks.
Example: Toolbar Button with Loading and Disabled States
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { isSaving } = attributes;
const handleSave = () => {
setAttributes({ isSaving: true });
setTimeout(() => setAttributes({ isSaving: false }), 2000); // Simulating save delay
};
return (
<div>
<BlockControls>
<ToolbarButton
label="Save"
icon="save"
onClick={handleSave}
isBusy={isSaving}
disabled={isSaving}
/>
</BlockControls>
<p>{isSaving ? "Saving content..." : "Content saved!"}</p>
</div>
);
};
- isBusy: The ToolbarButton shows a spinner icon to indicate that the save operation is in progress.
- disabled: The button is disabled while the content is being saved, preventing multiple save actions at once.
Performance Considerations for Custom Toolbars
Custom toolbars, especially those involving complex operations or multiple components, can affect the editor’s performance if not optimized properly. Follow these performance tips to ensure smooth operation:
Minimize Re-Renders
useMemo and useCallback to avoid unnecessary re-renders, especially when handling the toolbar button state.
Lazy Load Data
If your toolbar relies on external data (such as pulling items from an API), only load the data when needed.
Reduce Expensive Operations
Avoid running heavy computations or data fetches on every render of the block.
Example: Optimizing Toolbar Actions with useMemo and useCallback
import { useCallback, useMemo } from "react";
import { ToolbarButton } from "@wordpress/components";
const Edit = (props) => {
const { attributes, setAttributes } = props;
const { isBold } = attributes;
const toggleBold = useCallback(() => {
setAttributes({ isBold: !isBold });
}, [isBold]);
const toolbarLabel = useMemo(() => {
return isBold ? "Unbold Text" : "Bold Text";
}, [isBold]);
return (
<div>
<BlockControls>
<ToolbarButton
label={toolbarLabel}
icon="editor-bold"
onClick={toggleBold}
isActive={isBold}
/>
</BlockControls>
<p style={{ fontWeight: isBold ? "bold" : "normal" }}>
This is boldable text.
</p>
</div>
);
};
useCallback: Memoizes the toggleBold function so that it doesn’t get recreated on every render, improving performance.useMemo: Caches the toolbar label (Bold Text or Unbold Text) so it only recalculates when the isBold state changes.
Creating custom block toolbars in the WordPress editor enhances the user experience by providing quick, intuitive access to block controls. By leveraging BlockControls, ToolbarButton, and ToolbarDropdownMenu, you can build toolbars that are efficient, accessible, and tailored to your block’s functionality.
Creating custom sidebar panels
PREVIOUS
Implementing block variations
NEXT
Credits
Shreya Agarwal
Author
Shreya Agarwal
Author
Shreya Agarwal is a Growth Engineer at rtCamp, she brings active, hands-on WordPress development credentials to everything she writes and reviews. A WordPress Core Contributor with merged pull requ…
Good Work. Good People.
Industry partnerships
Compliance certifications
United States India
© rtCamp Inc. since 2009. All rights reserved.
Terms of Service · Privacy Policy · Trust Center
Company
Solutions
Subscribe to Campfire for fresh insights and stories from people behind rtCamp
Δ
Email(Required)
Submit
United States India
© rtCamp Inc. since 2009. All rights reserved.
Terms of Service · Privacy Policy · Trust Center
Cookie Consent
We value your privacy
We use cookies to give you the best possible experience. By clicking “Accept,” you consent to our use of cookies to improve site functionality, analyze usage, and personalize content and communications. Your privacy matters to us, and we are committed to handling your data responsibly and transparently. Please check our Privacy Policy for more details.
Manage PreferencesDon’t AllowAllow All
Why do we use cookies?
×
By clicking "Accept" or "Decline All" at the bottom, you consent to the use of cookies and other tools as described in our Cookie Policy in accordance with your settings and accept our Terms of Service.
Toggle EssentialEssential
Essential cookies enable basic functions and are necessary for the proper function of the website.
Name
Description
Duration
Geolocation Config
This cookie is used to store the consent settings based on the visitor's location.
30 days
Cookie Preferences
This cookie is used to store the user's cookie consent preferences.
30 days
Toggle CloudFlareCloudFlare
CloudFlare provides web performance and security solutions, enhancing site speed and protecting against threats.
Service URL: developers.cloudflare.com (opens in a new window)
Name
Description
Duration
cf_clearance
Whether a CAPTCHA or Javascript challenge has been solved.
session
Toggle CommentsComments
These cookies are needed for adding comments on this website.
Name
Description
Duration
comment_author
Used to track the user across multiple sessions.
Session
comment_author_email
Used to track the user across multiple sessions.
Session
comment_author_url
Used to track the user across multiple sessions.
Session
Toggle GodamGodam
GoDAM" is primarily a specialized WordPress plugin and media management service designed to enhance video hosting, marketing, and asset management directly within the WordPress dashboard.
Service URL: godam.io (opens in a new window)
Name
Description
Duration
user_image
Temporarily stores the path to the user's avatar or profile picture for quick rendering in the website header.
session
user_id
Stores the numerical ID of the logged-in user to maintain session continuity and basic site operations.
session
full_name
Stores the logged-in user's display name to personalize the site interface without needing database queries.
session
system_user
First-party cookie used to store basic application state identifying the current system user role.
session
sid
A generic session ID cookie used to maintain user state and functionality as the visitor navigates through the site.
session
Toggle Google reCAPTCHAGoogle reCAPTCHA
Google reCAPTCHA helps protect websites from spam and abuse by verifying user interactions through challenges.
Name
Description
Duration
_GRECAPTCHA
Google reCAPTCHA sets a necessary cookie (_GRECAPTCHA) when executed for the purpose of providing its risk analysis.
179 days
Toggle Google Tag ManagerGoogle Tag Manager
Google Tag Manager simplifies the management of marketing tags on your website without code changes.
Name
Description
Duration
cookiePreferences
Registers cookie preferences of a user
2 years
td
Registers statistical data on users' behaviour on the website. Used for internal analytics by the website operator.
session
Toggle StatisticsStatistics
Statistics cookies collect information anonymously. This information helps us understand how visitors use our website.
Toggle Factors AIFactors AI
Factors.ai is a B2B account intelligence and marketing analytics platform that helps Go-To-Market (GTM) teams identify anonymous website visitors, track buyer journeys, and measure the ROI of marketing campaigns.
Service URL: www.factors.ai (opens in a new window)
Name
Description
Duration
_fuid
It is sent to capture session details and track user behavior across your website to provide behavioral data and intent signals.
1 Year
Toggle Google AnalyticsGoogle Analytics
Google Analytics is a powerful tool that tracks and analyzes website traffic for informed marketing decisions.
Service URL: policies.google.com (opens in a new window)
Name
Description
Duration
FPGSID
Stores a session or user identifier to track how visitors interact with a website. This helps Google Analytics measure website performance, user engagement, and usage patterns.
Session
FPLC
Used by Google Analytics to link visitor interactions and sessions across multiple related domains.
20 hours
FPID
A server-side Google Analytics cookie used as an alternative user identifier when third-party cookies are restricted.
2 years
_ga
ID used to identify users
2 years
_ga_
ID used to identify users
2 years
Toggle Jetpack StatsJetpack Stats
Jetpack's built-in visitor analytics. It records page views, referring sites, search terms, and outbound link clicks, and also carries the shared visitor-tracking library used by Jetpack Instant Search and WooCommerce Analytics.
Service URL: automattic.com (opens in a new window)
Name
Description
Duration
tk_aip
Stores a list of anonymous visitor IDs so they can be merged into one identity once a visitor is recognized.
Up to 5 years
tk_tc
Used once per page load to work out which cookie domain the Tracks library should use, then removed as soon as it's read back.
Session (deleted immediately after use)
tk_qs
Queues analytics events for Jetpack's Tracks library so none are lost if the page closes before they can be sent.
30 minutes
tk_ai
Stores a randomly-generated anonymous visitor ID so Jetpack's Tracks analytics library can link tracking events to the same visitor.
Session in wp-admin; up to 5 years on the frontend
Toggle Microsoft ClarityMicrosoft Clarity
Clarity is a web analytics service that tracks and reports website traffic.
Service URL: clarity.microsoft.com (opens in a new window)
Name
Description
Duration
CLID
Identifies the first-time Clarity saw this user on any site using Clarity.
12 months
ANONCHK
Indicates whether MUID is transferred to ANID, a cookie used for advertising. Clarity doesn't use ANID and so this is always set to 0.
Session
_clck
Persists the Clarity User ID and preferences, unique to that site is attributed to the same user ID.
12 months
_clsk
Connects multiple page views by a user into a single Clarity session recording.
12 months
Toggle Parse.lyParse.ly
Parse.ly is a content analytics platform that helps publishers optimize audience engagement and content performance.
Name
Description
Duration
_parsely_session
JSON document storing information identifying a browsing session according to Parsely’s proprietary definition
30 minutes
_parsely_visitor
JSON document uniquely identifying a browser and counting its sessions
13 months
cookies.js_dtest
This cookie determines whether the browser accepts cookies.
session
Toggle MarketingMarketing
Marketing cookies are used to follow visitors to websites. The intention is to show ads that are relevant and engaging to the individual user.
Toggle Bing / MicrosoftBing / Microsoft
Bing, powered by Microsoft, is a search engine providing web, image, video, and map search capabilities.
Name
Description
Duration
MR
Used to collect information for analytics purposes.
6 months
ANONCHK
Used to store session ID for a users session to ensure that clicks from adverts on the Bing search engine are verified for reporting purposes and for personalisation
10 minutes
SM
Used by Microsoft in synchronizing the MUID across multiple Microsoft domains to track users for advertising.
session
MUID
Identifies unique web browsers visiting Microsoft sites. These cookies are used for advertising, site analytics, and other operational purposes.
1 year
Toggle DoubleClick/Google MarketingDoubleClick/Google Marketing
A comprehensive digital advertising platform for managing campaigns, optimizing performance, and analyzing audience data.
Name
Description
Duration
IDE
This cookie is used for targeting, analyzing and optimisation of ad campaigns in DoubleClick/Google Marketing Suite
2 years
ar_debug
Store and track conversions
Persistent
Toggle LinkedInLinkedIn
LinkedIn is a professional networking platform for job seekers, employers, and industry connections.
Name
Description
Duration
bscookie
Used by LinkedIn to track the use of embedded services.
1 year
AnalyticsSyncHistory
Used to store information about the time a sync with the lms_analytics cookie took place for users in the Designated Countries
30 days
bcookie
Used by LinkedIn to track the use of embedded services.
1 year
li_sugr
Used to make a probabilistic match of a user's identity outside the Designated Countries
90 days
lidc
Used by the social networking service, LinkedIn, for tracking the use of embedded services.
1 day
UserMatchHistory
Used by LinkedIn Ads to synchronize and match user IDs across different ad networks and data providers.
30 days
Toggle LinkedIn InsightLinkedIn Insight
LinkedIn Insight is a web analytics service that tracks and reports website traffic.
Service URL: www.linkedin.com (opens in a new window)
Name
Description
Duration
li_sugr
Used to make a probabilistic match of a user's identity.
90 days
lidc
Used for routing and session management.
24 hours
Toggle LiveIntentLiveIntent
LiveIntent provides a platform for email advertising and identity-driven marketing solutions.
Name
Description
Duration
_lc2_fpi_js
Companion cookie to _lc2_fpi used by JavaScript to facilitate cross-domain ad tracking and user identification.
1 year
_lc2_fpi
First-party tracking cookie usually associated with LiveRamp to identify users across devices for targeted advertising.
1 Year
_li_ss
Sets a unique ID for the visitor, that allows third party advertisers to target the visitor with relevant advertisement. This pairing service is provided by third party advertisement hubs, which facilitates real-time bidding for advertisers.
1 month
lidid
Collects data on visitors' behaviour and interaction - This is used to make advertisement on the website more relevant. The cookie also allows the website to detect any referrals from other websites.
2 years
Toggle Cookie PolicyCookie Policy
You can find more information in our Privacy Policy.
Allow AllDecline All
Accept