Frappe Doctype Form View

Frappe DocType Form Controller (.js)

See frappe-doctype-schema for the .json schema. See frappe-doctype-controller for the .py server controller. See frappe-doctype-list-view for the _list.js list view controller. See frappe-doctype-tests for writing DocType controller Python tests. See frappe-js-api for full option tables on frappe.call, frappe.db.*, dialogs, datetime, and all other globals. Full per-hook details: REFERENCE.md. Common use-case examples: EXAMPLES.md.

Quick Start

// myapp/mymodule/doctype/my_doc_type/my_doc_type.js
frappe.ui.form.on('My Doc Type', {
    setup(frm) {
        // runs ONCE per doctype load — wire set_query, one-time event listeners
        frm.set_query('customer', () => ({
            filters: { disabled: 0 },
        }))
    },

    onload(frm) {
        // runs when a new docname is loaded for the first time
        // use for defaults that need server context (frm.doc.name exists here)
        if (frm.is_new()) {
            frm.set_value('posting_date', frappe.datetime.get_today())
        }
    },

    refresh(frm) {
        // runs on EVERY render — initial load, after save, after submit/cancel
        // ALL conditional buttons and field visibility logic lives here
        frm.add_custom_button(__('Run Report'), () => {
            // called synchronously as user action
        })
        frm.toggle_display('tax_id', frm.doc.party_type === 'Company')
    },

    customer(frm) {
        // field trigger: fires when frm.doc.customer changes
        if (!frm.doc.customer) {
            frm.set_value('customer_name', '')
        }
    },
})

Placement Rules

These rules prevent the most common JS form bugs. Follow them strictly.

The Golden Three

Placement Decision Tree

Does it react to a field value changing?
  YES → field trigger (fieldname(frm))
  NO  → Does it run every time the form renders?
    YES → refresh(frm)
    NO  → Is it wiring search queries or one-time listeners?
      YES → setup(frm)
      NO  → Is it setting default values on new docs?
        YES → onload(frm) + guard with frm.is_new()
        NO  → on_submit / before_cancel / validate / etc.

Custom Buttons Are Always Safe in refresh

Framework calls frm.clear_custom_buttons() automatically inside refresh_header(), which runs before the refresh trigger fires in the serial chain:

refresh_header()          ← clears all custom buttons
form-refresh (global)     
refresh_fields()          
script_manager.trigger('refresh')  ← your refresh(frm) runs here

So just add your buttons — no manual clear needed:

refresh(frm) {
    if (frm.doc.status === 'Pending') {
        frm.add_custom_button(__('Approve'), () => approve(frm))
    }
}

frm.clear_custom_buttons() manually is only needed if you want to wipe buttons from within a button's click handler or some other non-refresh context.

frm Object — Key Properties

frm.doc           // live local document (plain JS object)
frm.doctype       // "My Doc Type"
frm.docname       // "MY-DOC-0001"
frm.fields_dict   // { fieldname: field_control }
frm.is_new()      // true when doc is unsaved (no server name)
frm.is_dirty()    // true when doc has unsaved changes
frm.page          // frappe.ui.Page — page-level buttons, title
frm.dashboard     // frappe.ui.form.Dashboard — in-form progress bars, stats
frm.custom_buttons// { label: jQuery$btn } — track added custom buttons

Common APIs — Quick Reference

See REFERENCE.md for full signatures.

Field Visibility / State

frm.toggle_display(fnames, show)        // show/hide one or more fields
frm.toggle_reqd(fnames, mandatory)      // set required
frm.toggle_enable(fnames, enable)       // set editable / read-only
frm.set_df_property(f, prop, value)     // set any docfield property ('label', 'options', ...)

Setting Values

await frm.set_value('field', value)
await frm.set_value({ field1: val1, field2: val2 })

Triggering Events Programmatically

frm.trigger(event, cdt?, cdn?) fires a registered event handler as if the user had caused it. Use it to avoid duplicating logic that already lives in a field trigger or a named event.

// Fire a field trigger manually (e.g. after setting a value in code)
async customer(frm) {
    await frm.set_value('territory', 'Peru')
    // set_value does NOT fire the territory trigger — call it explicitly
    frm.trigger('territory')
},

// Fire a named (non-field) event — useful for separating concerns
refresh(frm) {
    if (frm.doc.status === 'Cancelled') {
        frm.trigger('on_cancel_ui')   // delegate display logic to a named handler
    }
},

on_cancel_ui(frm) {
    frm.toggle_display('cancellation_reason', true)
    frm.toggle_reqd('cancellation_reason', true)
},

Rules:

• frm.trigger is always synchronous dispatch — it calls the handler immediately but the handler may itself be async. If you need to await its side-effects (e.g. a frappe.call inside it), await the trigger: await frm.trigger('field').
• Calling frm.trigger('refresh') re-runs your refresh hook — rarely needed but valid.
• For child-table events pass cdt and cdn: frm.trigger('item_code', cdt, cdn).
• Do not trigger setup or onload — those hooks are lifecycle-managed by the framework.

Buttons

frm.add_custom_button(__('Label'), handler, group)  // group=null for top-level
frm.remove_custom_button(__('Label'), group)
frm.clear_custom_buttons()
frm.change_custom_button_type(__('Label'), group, 'primary')  // or 'danger', 'warning'

Link Search Filters

// Preferred: in setup(frm) — runs once, no repeated work
frm.set_query('fieldname', () => ({ filters: { active: 1 } }))
frm.set_query('child_fieldname', 'parent_table_field', () => ({ filters: {} }))

Calling Server Methods

Always use frappe.call. Never use frm.call — it hides the method path, making code harder to trace.

Pass callback as a parameter rather than chaining .then() — it keeps the response handler co-located with the call options and is the idiomatic Frappe style.

When calling a document method (a @frappe.whitelist() method on the controller), pass doc: frm.doc and a short method name. The doc carries the doctype, name, and all field values — no need to repeat them in args.

// ✅ GOOD — doc method, short path, callback param
frappe.call({
    doc: frm.doc,
    method: 'my_function',   // short name — no full dotted path needed
    freeze: true,
    callback(r) { console.log(r.message) },
})

// ✅ GOOD — module-level function, full path required
frappe.call({
    method: 'myapp.mymodule.some_module.my_function',
    args: { name: frm.doc.name },
    freeze: true,
    callback(r) { console.log(r.message) },
})

// ❌ BAD — avoid frm.call
frm.call('my_function')  // do not use

// ❌ BAD — avoid .then() for response handling
frappe.call({ doc: frm.doc, method: 'my_function' }).then(r => { ... })

Dialogs

// Simple prompt
frappe.prompt([{ label: 'Date', fieldname: 'date', fieldtype: 'Date', reqd: 1 }],
    (values) => console.log(values.date), __('Title'), __('Confirm'))

// Full dialog
const d = new frappe.ui.Dialog({
    title: __('My Dialog'),
    fields: [...],
    primary_action(values) { d.hide() },
    primary_action_label: __('Submit'),
})
d.show()

Progress Bars

frappe.show_progress(__('Processing'), current, total, __('Description'))
frappe.hide_progress()

// In-form dashboard progress bar (inside the form, no modal dialog)
frm.dashboard.show_progress(__('Processing'), 45, __('Step 2 of 4'))  // percent 0–100
frm.dashboard.hide_progress()

Dashboard Headline Alerts

Display a colored alert banner inside the form between the form header and the first field. Persistent until explicitly cleared.

// Primitive — arbitrary HTML, color is one of: 'yellow', 'blue', 'red', 'green', 'orange'
frm.dashboard.set_headline('<b>Pending</b> approval since ' + frm.doc.creation, 'yellow')
frm.dashboard.clear_headline()                        // remove the banner

// Plain-text shorthand (wraps text in <div> automatically)
frm.dashboard.set_headline_alert(__('On Hold'), 'orange')
frm.dashboard.set_headline_alert(null)               // also clears

// Auto-dismissing (clears after 10 seconds unless permanent=true)
frm.dashboard.add_comment(__('Reminder: attach invoice before submitting'), 'yellow')
frm.dashboard.add_comment(__('Settings saved'), 'green', /*permanent=*/false)

Dashboard Indicator Pills

Add a small colored pill in the Stats section below the links area.

frm.dashboard.add_indicator(__('Overdue'), 'red')
frm.dashboard.add_indicator(frm.doc.status, 'blue')

See REFERENCE.md § Dashboard Alerts & Indicators for full signatures and color values.

Child Tables — Short Reference

// Grid reference
const grid = frm.get_field('items').grid

// Add button to grid toolbar
grid.add_custom_button(__('Fill Prices'), () => fillPrices(frm))

// Add button to each row (in refresh of child's frappe.ui.form.on block)
frappe.ui.form.on('My Child DocType', {
    my_child_field_on_form_rendered(frm, cdt, cdn) {
        // fires when a child row expander opens
    }
})

// Accessing a child row doc
const row = frappe.get_doc(cdt, cdn)
frappe.model.set_value(cdt, cdn, 'rate', 100)  // set value in child row

See REFERENCE.md § Child Tables for the full grid API.

Reusable Code — The frappe.ui.form.Controller Pattern

The problem

All code inside a .js file executes in the browser's global scope. Declaring helper functions at the top level puts them on window, polluting the global namespace and risking collisions across doctypes.

// ❌ BAD — pollutes window.canTransitionTo
function canTransitionTo(frm, status) { ... }

frappe.ui.form.on('My Doc', {
    refresh(frm) {
        if (canTransitionTo(frm, 'Active')) { ... }   // global leak
    },
})

The solution: extend frappe.ui.form.Controller

Frappe's built-in Controller pattern (used internally for DocType and Customize Form) is the canonical way to attach reusable methods to a form without polluting global scope.

// ✅ GOOD — safe namespace, no global pollution
frappe.provide('frappe.model')

frappe.model.MyDocTypeController = class MyDocTypeController extends frappe.ui.form.Controller {
    // this.frm is always available (set by the base class constructor)

    canTransitionTo(newStatus) {
        const allowed = { Draft: ['Active'], Active: ['Archived', 'Draft'] }
        return (allowed[this.frm.doc.status] || []).includes(newStatus)
    }

    isManager() {
        return frappe.user_roles.includes('System Manager')
    }
}

frappe.ui.form.on('My Doc Type', {
    refresh(frm) {
        if (!frm.cscript.isManager()) return

        if (frm.cscript.canTransitionTo('Active')) {
            frm.add_custom_button(__('Activate'), () => frm.trigger('activate'), __('Actions'))
        }
    },
})

// Must be the last line — merges controller methods into frm.cscript
extend_cscript(cur_frm.cscript, new frappe.model.MyDocTypeController({ frm: cur_frm }))

How it works

Namespace conventions

Follow Frappe's own convention — put the controller on a frappe.provide namespace, never on window.

frappe.provide('frappe.model')           // Frappe's own doctypes (DocType, Customize Form)
frappe.provide('myapp.model')            // ✅ recommended for app-specific doctypes
frappe.provide('myapp.controllers')      // acceptable alternative

Naming: <Namespace>.<DocTypeNameInCamelCase>Controller
Example for docttype "Sales Commission Settlement" in app "soldamundo":

frappe.provide('frappe.model')
frappe.model.SalesCommissionSettlementController = class ... extends frappe.ui.form.Controller { ... }

Placement rules for Controller methods

Controller does NOT replace event hooks

Event hooks (setup, refresh, fieldname) must stay in frappe.ui.form.on. The Controller is only for helper methods — not for declaring lifecycle hooks.

Why? If you define refresh() on the Controller, Frappe calls it as an old-style handler with (doc, cdt, cdn) signature (not (frm, ...)). Mixing old-style and new-style handlers is confusing. Keep all event declarations in frappe.ui.form.on.

Full file structure

// 1. Namespace + Controller class (top of file)
frappe.provide('frappe.model')

frappe.model.MyDocTypeController = class MyDocTypeController extends frappe.ui.form.Controller {
    ALLOWED_TRANSITIONS = {
        Draft: ['Active'],
        Active: ['Archived', 'Draft'],
    }

    canTransitionTo(newStatus) {
        return (this.ALLOWED_TRANSITIONS[this.frm.doc.status] || []).includes(newStatus)
    }

    isManager() {
        return frappe.user_roles.includes('System Manager')
    }
}

// 2. Event hooks
frappe.ui.form.on('My Doc Type', {
    refresh(frm) {
        if (!frm.cscript.isManager()) return

        if (frm.cscript.canTransitionTo('Active')) {
            frm.add_custom_button(__('Activate'), () => frm.trigger('activate'), __('Actions'))
        }
    },

    activate(frm) {
        frappe.confirm(__('Activate this record?'), () => {
            frappe.call({ method: 'activate', doc: frm.doc, callback() { frm.reload_doc() } })
        })
    },
})

// 3. extend_cscript — ALWAYS last line
extend_cscript(cur_frm.cscript, new frappe.model.MyDocTypeController({ frm: cur_frm }))