UI Macro not visible in Form Layout – Why Formatter is required in ServiceNow Classic UI?

[rohan_agarwal]

❗ Problem Statement

I created a UI Macro to display a custom header/banner on a ServiceNow form.

However, after creation, the UI Macro was not visible in Form Layout, and I was unable to add it to the form.

---

🔍 What I tried

• Created UI Macro under System UI → UI Macros
• Expected it to appear directly in Form Layout
• Checked Form Layout personalization list
• UI Macro was not available for selection

---

🧠 Root Cause

A UI Macro cannot be directly added to a form layout in ServiceNow.

The platform does not expose UI Macros in Form Layout.

👉 Instead, a Formatter (sys_ui_formatter) is required as a bridge:

UI Macro → Formatter → Form Layout

---

🛠️ Solution

To resolve this issue, I followed these steps:

1️⃣ Create UI Macro

Created a UI Macro with HTML content for the header/banner.

---

2️⃣ Create Formatter

Navigate to:

System UI → Formatters → New

Configured:

• Name: Disaster Header
• Formatter Type: UI Macro
• UI Macro: Selected created macro
• Table: Target table

---

3️⃣ Add Formatter to Form Layout

Go to:

Form Layout → Personalize Layout

Now the formatter appears as:

👉 Disaster Header (Formatter)

Add it to the form and save.

---

🎯 Final Result

✔ UI Macro rendered successfully on the form
✔ Custom header/banner displayed correctly
✔ No issues in Form Layout

---

⚠️ Key Takeaways

• UI Macro cannot be directly used in Form Layout
• Formatter is required to render UI Macro
• This works only in Classic UI (not Workspace)
• For Workspace, UI Builder is recommended instead

---

🤝 Community Question

Is this the correct and recommended approach for displaying UI Macros in ServiceNow Classic UI?

Are there better alternatives in Workspace / UI Builder for implementing similar custom headers or banners?

#ui-macro #formatter #form-layout #servicenow-development #client-script

[rohan_agarwal · Accepted solution]

Sharing this based on my implementation experience. Happy to discuss improvements or alternative approaches.

[rohan_agarwal]

Sharing this based on my implementation experience. Happy to discuss improvements or alternative approaches.