Adding Module Icons on Desktop in Frappe Framework v15

Introduction & Context

In Frappe Framework v15, module icons are not just visual elements—they define how users discover, navigate, and trust your application. A well-configured desktop icon improves usability, reinforces branding, and ensures your custom app feels native within the Frappe Desk.
This guide explains how to add and manage module icons on the desktop, strictly following Frappe Framework Version 15 conventions and the official documentation.

What Are Desktop Module Icons in Frappe?

Desktop module icons are top-level navigation entries shown on the Frappe Desk. Each icon represents a Module Def and acts as an entry point to DocTypes, reports, and pages belonging to that module.
In v15, desktop icons are rendered dynamically from Module Def records and app metadata.

When Should You Add a Custom Module Icon?

You should add a module icon when:

• Creating a new custom app
• Introducing a new functional module
• Branding a vertical solution (Manufacturing, Real Estate, Healthcare, etc.)
• Improving usability for non-technical users

Technical Prerequisites

Before proceeding, ensure:

• Frappe Framework Version 15
• Developer Mode is enabled
• You have System Manager access
• Your app is installed on the site
• Desk access is available

How Desktop Module Icons Work in Frappe v15

Core Components Involved

Step-by-Step: Adding a Module Icon on Desktop

Step 1: Create or Identify a Module Def

Each desktop icon corresponds to a Module Def record.

Navigate to:

Awesome Bar → Module Def

Create a new Module Def if it doesn’t already exist.

Step 2: Configure the Module Def Properly

Fill the following fields carefully:

The Icon field expects a valid SVG icon name, not a file path.

Step 3: Choose the Correct Icon Format

Frappe v15 uses SVG icons from the built-in icon registry.

Example icon values:

• octicon octicon-briefcase
• octicon octicon-home
• octicon octicon-organization

Only supported icons render correctly on Desk.

How Icons Are Rendered on Desk

Once configured:

• The module appears on the desktop grid
• Clicking the icon opens the module workspace
• Permissions control visibility automatically

No custom JavaScript or CSS is required.

Best Practices for Module Icons

• Use clear, recognizable icons
• Keep naming consistent across modules
• Avoid overloading the desktop with too many modules
• Match icon semantics with module purpose
• Reuse standard icons where possible

Common Mistakes to Avoid

• Using unsupported icon names
• Expecting PNG/JPG icons to work
• Forgetting to assign the correct App
• Creating modules without permissions

Troubleshooting Module Icon Issues

Module Not Visible on Desktop?

Check:

• Module Def exists and is not disabled
• User has permission to the module
• App is installed correctly
• Desk cache is refreshed

Icon Not Displaying?

Ensure:

• Icon name is valid
• No spelling errors
• SVG icon exists in the registry
• Browser cache is cleared

Industry Relevance & Use Case Mapping

Desktop module icons are widely used in:

• Manufacturing ERP – Production, Quality, Inventory
• Real Estate ERP – Projects, Units, Leads
• Healthcare ERP – Patients, Appointments, Billing
• Distribution ERP – Sales, Logistics, Warehousing

A clear icon improves adoption and training speed.

Target Audience

• ERPNext Developers
• Frappe App Developers
• ERP Implementation Consultants
• System Administrators

Summary: Clean Navigation Starts with the Right Icon

In Frappe Framework v15, adding module icons is a configuration-driven, stable, and upgrade-safe process. By correctly defining Module Defs and using supported SVG icons, you ensure your app integrates seamlessly with the Desk and delivers a professional user experience.