Frappe Dialog API in Frappe Framework v15

What is the Frappe Dialog API?

The Frappe Dialog API provides a structured way to create modal dialog windows in the Frappe Desk interface. In Frappe Framework v15, dialogs are built using the frappe.ui.Dialog class and are commonly used for user input, confirmations, and lightweight workflows without navigating away from the current page.
Dialogs are a core UI component in ERPNext and custom Frappe applications, especially for client-side scripting and Desk customizations.

Who Should Use the Frappe Dialog API?

Target Audience

• ERPNext Developers
• Frappe Framework Developers
• Technical Consultants
• Frontend Customization Engineers

Technical Prerequisites

• Frappe Framework v15
• JavaScript (ES6)
• Basic understanding of DocTypes and Desk UI

How Does frappe.ui.Dialog Work?

The frappe.ui.Dialog class creates a modal window using predefined field definitions. It internally uses the same field system as DocTypes, ensuring consistency across forms and dialogs.
Core Entity: frappe.ui.Dialog
Module: Desk
File Source (v15): frappe/public/js/frappe/ui/dialog.js

How to Create a Dialog in Frappe Framework v15?

Basic Dialog Example

let dialog = new frappe.ui.Dialog({
title: 'User Information',
fields: [
{
label: 'Full Name',
fieldname: 'full_name',
fieldtype: 'Data',
reqd: 1
},
{
label: 'Email',
fieldname: 'email',
fieldtype: 'Data'
}
],
primary_action_label: 'Submit',
primary_action(values) {
console.log(values);
dialog.hide();
}
});
dialog.show();

What this does:

This creates a modal dialog with two input fields and a primary action button. When clicked, the dialog collects user input and executes the defined action.

What Field Types Are Supported in Dialogs?

Dialogs support all standard Frappe field types, including:

• Data
• Int
• Float
• Date / Datetime
• Check
• Select
• Link
• Table
• HTML

This consistency ensures dialogs behave exactly like DocType fields.

How to Set Default Values in a Dialog?

dialog.set_value('full_name', 'John Doe');

This method programmatically assigns a value to a dialog field after initialization.

How to Retrieve Values from a Dialog?

let values = dialog.get_values();

Returns an object containing all field values. If mandatory fields are missing, it returns null.

How to Dynamically Update Dialog Fields?

dialog.set_df_property(’email’, ‘hidden’, 1);

Supported properties include:

• hidden
• reqd
• read_only
• description

This allows dynamic UI behavior based on user interaction or logic.

How to Add Secondary Actions in a Dialog?

dialog.add_secondary_action('Cancel', () => {
dialog.hide();
});

Secondary actions are useful for cancel, reset, or alternative flows.

How to Use Tables Inside Dialogs?

Dialogs support child tables using the Table field type.

{
fieldname: 'items',
fieldtype: 'Table',
label: 'Items',
fields: [
{
fieldtype: 'Data',
fieldname: 'item_name',
label: 'Item Name'
}
]
}

This is commonly used in ERPNext for quick transaction helpers.

Best Practices for Using Frappe Dialog API

• Keep dialogs lightweight and task-focused
• Avoid complex workflows inside dialogs
• Validate mandatory fields using reqd: 1
• Always hide dialogs after action completion
• Reuse dialogs where possible instead of recreating

Common Use Cases in ERPNext

Industry Relevance

• Manufacturing: Quick job card inputs
• Finance: Approval confirmations
• Sales: Inline data capture
• HR: Attendance or remarks entry

Dialogs are widely used across ERPNext modules to improve user experience without page reloads.

Troubleshooting Common Issues

Dialog Not Showing

• Ensure dialog.show() is called
• Check for JavaScript errors in the browser console

get_values() Returns Null

• Mandatory fields are not filled
• Fieldnames are incorrect

Advanced Tips for Frappe v15

• Use dialogs inside custom buttons (frm.add_custom_button)
• Combine with frappe.call for server-side actions
• Leverage depends_on for conditional fields
• Avoid heavy DOM manipulation inside dialogs

How Does the Dialog API Fit into ERPNext Customization?

The Dialog API is a core building block for ERPNext frontend customization. It integrates seamlessly with:

• DocType forms
• Custom scripts
• Workflows
• REST API calls

It enables rapid UI extensions without altering core screens.

Cross-References

• Frappe Client Scripts
• Frappe Form API
• Frappe Field Types
• ERPNext Desk Customization

Official References

Frappe Dialog Docs (v15):

https://docs.frappe.io/framework/user/en/api/dialog

GitHub Source (v15):

https://github.com/frappe/frappe/tree/version-15