7.x common.inc drupal_add_library($module, $name, $every_page = NULL)

Adds multiple JavaScript or CSS files at the same time.

A library defines a set of JavaScript and/or CSS files, optionally using settings, and optionally requiring another library. For example, a library can be a jQuery plugin, a JavaScript framework, or a CSS framework. This function allows modules to load a library defined/shipped by itself or a depending module, without having to add all files of the library separately. Each library is only loaded once.


$module: The name of the module that registered the library.

$name: The name of the library to add.

$every_page: Set to TRUE if this library is added to every page on the site. Only items with the every_page flag set to TRUE can participate in aggregation.

Return value

TRUE if the library was successfully added; FALSE if the library or one of its dependencies could not be added.

See also




11 calls to drupal_add_library()
drupal_add_js in includes/common.inc
Adds a JavaScript file, setting, or inline code to the page.
drupal_add_tabledrag in includes/common.inc
Assists in adding the tableDrag JavaScript behavior to a themed table.
JavaScriptTestCase::testLibraryAlter in modules/simpletest/tests/common.test
Adds a JavaScript library to the page and alters it.
JavaScriptTestCase::testLibraryRender in modules/simpletest/tests/common.test
Adds a library to the page and tests for both its JavaScript and its CSS.
JavaScriptTestCase::testLibraryUnknown in modules/simpletest/tests/common.test
Tests non-existing libraries.

... See full list

3 string references to 'drupal_add_library'
JavaScriptTestCase::resetStaticVariables in modules/simpletest/tests/common.test
Resets static variables related to adding JavaScript to a page.
JavaScriptTestCase::setUp in modules/simpletest/tests/common.test
Sets up a Drupal site for running functional and integration tests.
overlay_render_region in modules/overlay/overlay.module
Renders an individual page region.


includes/common.inc, line 4845
Common functions that many Drupal modules will need to reference.


function drupal_add_library($module, $name, $every_page = NULL) {
  $added =& drupal_static(__FUNCTION__, array());

  // Only process the library if it exists and it was not added already.
  if (!isset($added[$module][$name])) {
    if ($library = drupal_get_library($module, $name)) {

      // Add all components within the library.
      $elements['#attached'] = array(
        'library' => $library['dependencies'],
        'js' => $library['js'],
        'css' => $library['css'],
      $added[$module][$name] = drupal_process_attached($elements, JS_LIBRARY, TRUE, $every_page);
    else {

      // Requested library does not exist.
      $added[$module][$name] = FALSE;
  return $added[$module][$name];


jim0203’s picture

It is mentioned, but it would be good to be clearer about the fact that the libraries need to have been defined by hook_library().

skomorokh’s picture

You can find out which libraries are available from a module via drupal_get_library(), I used something like: dpm(drupal_get_library('system'));

This I learned after attempting to re-use the jQuery BBQ library from core. I had blindly googled about and found a few places mentioning this: drupal_add_library('overlay', 'jquery-bbq');

Whereas in the release it's: drupal_add_library('system', 'jquery.bbq');

shafiul’s picture

Where do I call this function? In my module or template files or pre-processor functions?

jackbravo’s picture

you can add it on the preprocess_html (theme) or in the hook_init function if you are including the library in all pages or just on the hook function you are using the library (module).

Dorian’s picture

This is so abstract for me. Could someone post a nice example of how to add a jqueryplugin of a cusom module with this library api...

That would be awesome!

mattsmith3’s picture

use hook_init in the .module file.

function my_module_init() {
        drupal_add_library('system', 'ui.tabs');

other scripts (not jquery.ui... but custom module scripts) should be added via the .info file:

scripts[]   =    js/my_module.js
bburg’s picture

hook_init is run on every request that goes through Drupal. This includes callbacks performed via ajax/ahah/ajaj, which might be expecting a specific JSON object. Now why would you want to insert arbitrary javascript here ;)

allenfantasy’s picture

Just drag an example from a third-party module called "View Accordion", which I used to add the jQuery Accordion to my views:

function pre_render($result) {
  drupal_add_library('system', 'ui.accordion');

Actually you can add a jQuery plugin library wherever you want in your theme:

function mytheme_preprocess_page($vars) {
  //prefix code
  drupal_add_plugin('system', 'ui.tabs');
  //suffix code

Or in your custom module, like this:

function mymodule_preprocess_node($vars) {
  drupal_add_library('system', 'ui.tabs');
Astrayus’s picture

It tooks me a week to achieve this so i figured someone will find it usefull to read it on the first place i went to look for an answer.

Apparently, setting $every_page to FALSE wasn't enough, completely uneffective to be honest, to prevent the aggregation of my library (i was using ckeditor lib).
Eventualy i found a hint here http://drupalcontrib.org/api/drupal/contributions!libraries!libraries.ap... in the last example, with the undocumented (not that i could find at least) use of the the preprocess variant.

The solution was to specify directly inside the library if the .js file could support JS aggregation, in my case it ended like this:

$items['ckeditor'] = array( 'title' => 'ckeditor', 'version' => '4.3.1',
'css' => array( "$path/content.css" => array()),
'js' => array( "$path/ckeditor.js" => array('preprocess' => FALSE)));

that file is not going to be aggregated regardless the value of $every_page you will choose.

dorficus’s picture

but I 'm running into this issue now. Wouldn't hook_libraries_info_alter(&$libraries) be a good way to do this? I'm having trouble with jquery.ui and aggregation and I'd like to alter it to add the preprocess => false, but I can't get the dpm or kpr or print_r or var_dump to return anything to use.

drclaw’s picture

This function has been removed in Drupal 8. Adding a library to the page should now be done using the #attached property of a renderable array. @see Change Record https://drupal.org/node/2169605

drupalshrek’s picture

It wasn't clear to me how to find the value for the $module parameter, "the name of the module that registered the library". Erm, how do I know what that is exactly? I will describe how I found out.

My initial code was:

* Implements hook_init().
function mymodule_init() {
	$info = libraries_load('underscore');
	$return = drupal_add_library('underscore', 'underscore');
	$info = libraries_load('backbone');
	$return = drupal_add_library('backbone', 'backbone');

I had added libraries_load() and drupal_add_library() to my own hook_init(), but it wasn't working, so something was wrong, but where? Firstly I added variables $info and $return to be able to easily view in my IDE what the return values from each of the functions was. The $info returned valid data, but my drupal_add_library() calls were both returning 'false'. Progress, of a sort, to know where things were not working.

I looked at the $info array returned and that contained $info['module']. The value was 'quickedit', so I changed my code to use this in the drupal_add_library() call:

* Implements hook_init().
function mymodule_init() {
	$info = libraries_load('underscore');
	$return = drupal_add_library('quickedit', 'underscore');
	$info = libraries_load('backbone');
	$return = drupal_add_library('quickedit', 'backbone');

That worked!

So, if you want to know what the value for the $module parameter is, check the $info['module'] value returned by libraries_load().

KeyboardCowboy’s picture

Rather than calling drupal_add_library() directly, libraries should be attached to an render element like standalone CSS and JS files.

$build['element']['#attached']['library'][] = array('module_name', 'library_name', [$every_page = NULL]);

This prevents the library from being loaded on pages that don't require it.

Dependency libraries like underscore and backbone should be loaded along with whichever scripts require them. If you want them to be loaded on every page, I recommend attaching them to your main content block via hook_page_alter() instead of in hook_init() as the init hook is called whenever Drupal bootstraps, not only when rendering markup (i.e. during drush commands).