Custom Module Icon in Frappe Framework (v15)
Introduction: Why Custom Module Icons Matter
A custom module icon in Frappe Framework v15 allows you to visually brand your application modules in the Desk interface.
It improves usability, enhances recognition, and creates a professional ERP experience—especially important for ERPNext-based solutions delivered to end users.
What Is a Custom Module Icon in Frappe?
A custom module icon is an SVG-based icon associated with a Module Def.
Frappe uses this icon to represent the module in:
- Desk sidebar
- Workspace module switcher
- App dashboards
Icons are loaded from the app’s public assets and mapped through configuration.
When Should You Add a Custom Module Icon?
You should add a custom module icon when:
- Creating a custom Frappe app
- Branding ERPNext for a specific industry
- Delivering white-labeled ERP solutions
- Improving navigation clarity for users
This feature is fully supported and stable in Frappe v15.
Technical Prerequisites
Before adding a custom module icon, ensure:
- Frappe Framework v15 is installed
- A custom app exists
- A Module Def is already created
- You have access to app source code
How to Add a Custom Module Icon in Frappe (v15)
Step-by-Step Overview
- Create an SVG icon
- Place the icon in your app’s public folder
- Reference the icon in hooks.py
- Clear cache and reload Desk
Each step is explained in detail below.
Step 1: Create the Module Icon (SVG)
Frappe only supports SVG icons for modules.
Requirements:
- SVG format
- Simple paths (no external styles)
- Square aspect ratio (recommended 24×24 or 32×32)
Example filename:
custom_module.svg
Step 2: Place Icon in App Public Folder
Copy the SVG file to:
your_app/public/images/custom_module.svg
This path is mandatory because Frappe serves module icons from public assets.
Step 3: Configure Module Icon in hooks.py
Open your app’s hooks.py and add the following:
app_module_icons = {
"Your Module Name": "octicon octicon-file-directory"
}
To use a custom SVG, reference it via CSS instead (recommended approach in v15).
Recommended v15 Approach: Using module_icons
In Frappe v15, module icons are mapped using module_icons:
module_icons = {
"Your Module Name": "custom_module"
}
Frappe automatically resolves the icon from:
/assets/your_app/images/custom_module.svg
Step 4: Clear Cache and Reload Desk
Run the following commands:
bench clear-cache
bench build
bench restart
Then refresh your browser to see the new module icon.
How Frappe Resolves Module Icons (v15 Internals)
Frappe loads module icons by:
- Reading module_icons from hooks
- Resolving the icon name
- Loading the SVG from app assets
- Rendering it in the Desk UI
This logic is implemented in the Desk module loader of Frappe v15.
Common Use Cases
ERPNext Industry Solutions
- Manufacturing modules
- Real estate modules
- Healthcare apps
White-Label ERP Products
- Client-specific branding
- SaaS ERP platforms
Internal Tools
- HR systems
- Workflow dashboards
Best Practices for Custom Module Icons
- Use clean, minimal SVGs
- Keep icon names lowercase
- Match icon style across modules
- Avoid large or complex SVG paths
Common Issues and Troubleshooting
Icon Not Showing
Checklist:
- SVG is in public/images
- module_icons key matches Module Def name
- Cache is cleared
Wrong Icon Displayed
- Ensure no duplicate module names
- Check browser cache
- Verify asset build completed
Target Audience
- Frappe Developers
- ERPNext Consultants
- Custom App Builders
- SaaS ERP Providers
Industry Relevance
Custom module icons are especially valuable in:
- ERP product branding
- Multi-tenant ERP deployments
- Client-facing ERP dashboards
They significantly improve user adoption and interface clarity.
Summary: Branding Your Frappe Modules the Right Way
In Frappe Framework v15, adding a custom module icon is a simple yet powerful customization.
It strengthens branding, improves navigation, and enhances the overall ERP experience—without touching core code.
For production-grade ERPNext solutions, custom module icons are a must-have.
