Backdrop includes a new Dialog API for opening and manipulating dialogs via AJAX requests.

In the most simple use-case, any page served by Backdrop can be opened in a dialog just by adding an HTML attribute to the link that should open the dialog. First, make sure that the ajax.js file is loaded on the page:

backdrop_add_library('system', 'backdrop.ajax');

Then in the HTML, include two things, the class use-ajax on the link, and a data attribute telling Backdrop that the response should load in a dialog:

<a href="/node/1" class="use-ajax" data-dialog="true" />

Clicking this link will now load the content of the URL /node/1 into the dialog without the surrounding header, footer, or sidebars. You can also specify any jQuery UI dialog options in a second data-dialog-options attribute:

<a href="/node/1" class="use-ajax" data-dialog="true" data-dialog-options='{"dialogClass":"my-dialog"}' />

The full list of options can be found at the jQuery UI Dialog documentation.

Besides opening a dialog, server-side requests can manipulate open dialogs to set their title, manipulate their options, and close them. To do this, a form may specify a #ajax property, or another link may use the use-ajax class to a callback path. This callback path can then return a set of commands back to dialog via AJAX.

For example a form button within the dialog could save the form and then close the dialog.

function my_module_form($form, &$form_state) {
  $form['option'] = array(
    '#type' => 'textfield',
    '#title' => t('Option to save'),
  $form['actions']['#type'] = 'actions';
  $form['actions']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Close and save'),
    '#ajax' => array(
      'callback' => 'my_module_dialog_close',

function my_module_form_submit($form, &$form_state) {
  // Save the $form_state['values']['option'] value here.

function my_module_dialog_close($form, &$form_state) {
  $commands = array(
    '#type' => 'ajax',
    '#commands' => array(),
  $commands['#commands'][] = ajax_command_close_modal_dialog();
  return $commands;

There are a number of commands available to manipulate dialogs. See the list of AJAX Commands at:!includes!

Architects, Administrators, Editors
Module developers
Theme developers
Related Github Issues: