Office Settings & Configuration

Add Custom Macro Buttons and Icons to the Word Ribbon or QAT

Phi Hung VoPhi Hung Vo Nov 22, 2026 868 views

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.
Before you start

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.

Solution 1Recommended

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.

1
Create the callback

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.

2
Add the Custom UI part

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.

3
Embed the icon

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.

4
Save and test

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.

Use a template for wider availability: A .dotm template can provide the customization to documents that load it. For global availability, place a trusted template in Word's Startup folder and restart Word; the folder location can be checked in Word's File Locations settings.
Free Microsoft Office alternative

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.

Edit documents in a familiar Ribbon-style interfaceOpen and save Microsoft Word DOC and DOCX filesUse a free, lightweight suite for everyday office tasksMove common document-editing work from Microsoft Office with minimal adjustment
microsoft office alternative - wps office

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.