Frappe client

Client-side JavaScript API for making requests and handling events

The Frappe client-side API provides methods for making server requests, managing events, and displaying user messages.

Making API requests

frappe.call()

Make a server-side method call from the client.

frappe.call({
    method: 'frappe.client.get_value',
    args: {
        doctype: 'Item',
        filters: { name: 'ITEM-001' },
        fieldname: ['item_name', 'item_group']
    },
    callback: function(r) {
        if (r.message) {
            console.log(r.message);
        }
    },
    error: function(r) {
        console.error('Request failed');
    }
});

method · string · required

Server-side method to call (dot notation path)

args · object

Arguments to pass to the server method

callback · function

Function called on successful response. Receives response object with message property

error · function

Function called on error

freeze · boolean

Show a loading indicator that prevents user interaction

freeze_message · string

Custom message to show during freeze

async · boolean

Whether the request should be asynchronous (default: true)

type · string

HTTP method type: ‘POST’ or ‘GET’ (default: ‘POST’)

frappe.xcall()

Promise-based wrapper around frappe.call() for async/await patterns.

try {
    const result = await frappe.xcall(
        'frappe.client.get_value',
        {
            doctype: 'Customer',
            filters: { name: 'CUST-001' },
            fieldname: 'customer_name'
        }
    );
    console.log(result);
} catch (error) {
    console.error(error);
}

method · string · required

Server-side method to call

params · object

Arguments to pass to the server method

type · string

HTTP method: ‘POST’ or ‘GET’ (default: ‘POST’)

Database methods

frappe.db.get_value()

Get a specific field value from a document.

frappe.db.get_value('Item', { name: 'ITEM-001' }, 'item_name', (r) => {
    console.log(r.item_name);
});

doctype · string · required

DocType name

filters · object | string · required

Filters object or document name

fieldname · string | array · required

Field name or array of field names to fetch

callback · function

Callback function that receives the values

frappe.db.get_list()

Get a list of documents with filtering and pagination.

const items = await frappe.db.get_list('Item', {
    fields: ['name', 'item_name', 'item_group'],
    filters: {
        item_group: 'Products'
    },
    limit: 20,
    order_by: 'item_name asc'
});

doctype · string · required

DocType name

args · object

Query parameters object

args.fields · array

Array of field names to fetch (default: [‘name’])

args.filters · object | array

Filters to apply

args.limit · number

Number of records to fetch (default: 20)

args.order_by · string

Field to sort by with direction (e.g., ‘creation desc’)

frappe.db.get_doc()

Get a complete document with all fields.

const doc = await frappe.db.get_doc('Sales Order', 'SO-001');
console.log(doc);

frappe.db.set_value()

Set a field value in a document.

frappe.db.set_value('Item', 'ITEM-001', 'item_name', 'New Name', (r) => {
    console.log('Updated');
});

frappe.db.insert()

Insert a new document.

const doc = await frappe.db.insert({
    doctype: 'ToDo',
    description: 'New task',
    status: 'Open'
});

frappe.db.delete_doc()

Delete a document.

await frappe.db.delete_doc('ToDo', 'TODO-001');

Event system

frappe.on()

Bind an event handler.

frappe.on('form-refresh', function(frm) {
    console.log('Form refreshed:', frm.doctype);
});

frappe.trigger()

Trigger an event.

frappe.trigger('custom-event', { data: 'value' });

frappe.off()

Unbind an event handler.

frappe.off('form-refresh', handler_function);

Realtime events

frappe.realtime.on()

Subscribe to realtime events from the server.

frappe.realtime.on('eval_js', function(data) {
    console.log('Received realtime event:', data);
});

frappe.realtime.emit()

Emit a realtime event to other users.

frappe.realtime.emit('doc_update', {
    doctype: 'Sales Order',
    name: 'SO-001'
});

User messages

frappe.msgprint()

Display a message dialog to the user.

frappe.msgprint('Record saved successfully');

// With options
frappe.msgprint({
    title: __('Success'),
    indicator: 'green',
    message: __('The operation completed successfully')
});

message · string | object · required

Message to display or options object

title · string

Dialog title

indicator · string

Color indicator: ‘red’, ‘green’, ‘blue’, ‘orange’, ‘yellow’

frappe.throw()

Throw an error and display it to the user.

frappe.throw(__('Invalid value for field {0}', [fieldname]));

frappe.show_alert()

Show a temporary alert notification.

frappe.show_alert({
    message: __('Document updated'),
    indicator: 'green'
}, 5);

message · string | object · required

Message to display or options object with message and indicator

seconds · number

How long to show the alert (default: 3)

frappe.confirm()

Show a confirmation dialog.

frappe.confirm(
    'Are you sure you want to delete this record?',
    function() {
        // User clicked Yes
        frappe.db.delete_doc('Item', 'ITEM-001');
    },
    function() {
        // User clicked No
        console.log('Cancelled');
    }
);

message · string · required

Confirmation message

confirm_action · function

Function to call when user confirms

reject_action · function

Function to call when user rejects