Add Custom Macro Buttons and Icons to the Word Ribbon or QAT
Question details
The user wants to add macro buttons with custom icons to the Word Ribbon or Quick Access Toolbar.
- Product
- Microsoft Word
- Device & OS
- not provided
- Scenario
- Customize a macro-enabled document or template so a VBA macro can be run from a Ribbon or Quick Access Toolbar button.
- Observed behavior
- The desired result is a button that displays a custom icon and runs the associated VBA macro.
Save the file as a macro-enabled Word document (.docm) or template (.dotm), and have the VBA macro and an icon image ready. To edit Custom UI XML and embed the image, install a Ribbon XML editor such as Office RibbonX Editor.
Add a Custom Ribbon Button with an Embedded Icon
Use Custom UI XML when you need your own image on a Ribbon button that runs a VBA macro.
The XML example adds a tab and button. It assumes an embedded image named MyIcon and a VBA procedure named RunMyMacro.
Example XML: <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"><ribbon><tabs><tab id="myTab" label="My Tools"><group id="myGroup" label="Macros"><button id="myButton" label="Run Macro" image="MyIcon" size="large" onAction="RunMyMacro"/></group></tab></tabs></ribbon></customUI>
Example callback in a standard VBA module: Public Sub RunMyMacro(control As IRibbonControl) MyMacro End Sub. Replace MyMacro with the name of your existing macro.
In Word, open the VBA editor, choose Insert > Module, and add the callback shown above. Make sure the macro it calls is available in the same document or template.
Close the file in Word, open the .docm or .dotm file in Office RibbonX Editor, and insert an Office 2007 Custom UI part. Paste the example XML into that part.
Use the Ribbon XML editor's image insertion command to add your icon, and set its image ID to MyIcon so it matches the XML image attribute.
Save the file in the XML editor, reopen it in Word, and enable macros only if you trust the file. Select My Tools > Run Macro to test the button.
Add a Macro to the Quick Access Toolbar
Use Word's interface for a quick QAT button with a built-in icon, or use XML if you need an embedded custom image.
Edit Word Documents with WPS Writer
WPS Office is a free, lightweight alternative with a familiar interface for working on Word documents. Its format compatibility helps you move everyday document editing to WPS, although it does not fix Word's Ribbon XML or QAT customization.

Frequently Asked Questions
Can I add a macro to the QAT without editing XML?
Yes. In Word, go to File > Options > Quick Access Toolbar, choose Macros, select the macro, and click Add. Use Modify to choose one of Word's built-in symbols.
Can I upload my own QAT icon in Word's settings?
Word's standard QAT settings offer built-in symbols rather than an image upload. To use your own image, embed it in the document or template and reference it from Custom UI XML.
Should I use a DOCM or DOTM file?
Use a .docm file when the macro and customization belong to one document. A .dotm template is generally preferable when you want the customization available to multiple documents or loaded globally.
Why doesn't my custom button run the macro?
Check that the XML onAction value matches a public callback in a standard VBA module and that the callback accepts an IRibbonControl argument. Reopen the file and enable macros only if the file is trusted.
How can I make the template load globally?
Place the trusted .dotm template in Word's Startup folder and restart Word. Check the folder path in Word's File Locations settings.




