7.x system.api.php hook_library()

Registers JavaScript/CSS libraries associated with a module.

Modules implementing this return an array of arrays. The key to each sub-array is the machine readable name of the library. Each library may contain the following items:

  • 'title': The human readable name of the library.
  • 'website': The URL of the library's web site.
  • 'version': A string specifying the version of the library; intentionally not a float because a version like "1.2.3" is not a valid float. Use PHP's version_compare() to compare different versions.
  • 'js': An array of JavaScript elements; each element's key is used as $data argument, each element's value is used as $options array for drupal_add_js(). To add library-specific (not module-specific) JavaScript settings, the key may be skipped, the value must specify 'type' => 'setting', and the actual settings must be contained in a 'data' element of the value.
  • 'css': Like 'js', an array of CSS elements passed to drupal_add_css().
  • 'dependencies': An array of libraries that are required for a library. Each element is an array listing the module and name of another library. Note that all dependencies for each dependent library will also be added when this library is added.

Registered information for a library should contain re-usable data only. Module- or implementation-specific data and integration logic should be added separately.

Return value

An array defining libraries associated with a module.

See also




Related topics

6 functions implement hook_library()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

common_test_library in modules/simpletest/tests/common_test.module
Implements hook_library().
contextual_library in modules/contextual/contextual.module
Implements hook_library().
drupal_add_library in includes/common.inc
Adds multiple JavaScript or CSS files at the same time.
drupal_get_library in includes/common.inc
Retrieves information for a JavaScript/CSS library.
overlay_library in modules/overlay/overlay.module
Implements hook_library().

... See full list


modules/system/system.api.php, line 786
Hooks provided by Drupal core and the System module.


function hook_library() {

  // Library One.
  $libraries['library-1'] = array(
    'title' => 'Library One',
    'website' => 'http://example.com/library-1',
    'version' => '1.2',
    'js' => array(
      drupal_get_path('module', 'my_module') . '/library-1.js' => array(),
    'css' => array(
      drupal_get_path('module', 'my_module') . '/library-2.css' => array(
        'type' => 'file',
        'media' => 'screen',

  // Library Two.
  $libraries['library-2'] = array(
    'title' => 'Library Two',
    'website' => 'http://example.com/library-2',
    'version' => '3.1-beta1',
    'js' => array(
      // JavaScript settings may use the 'data' key.
        'type' => 'setting',
        'data' => array(
          'library2' => TRUE,
    'dependencies' => array(
      // Require jQuery UI core by System module.
      // Require our other library.
      // Require another library.
  return $libraries;


Anonymous’s picture

Something to watch out for. It turns out when you implement hook_library in your module the libraries are not automatically made available to the module. You have to add the library using drupal_add_library('your_module_name', 'name_of_library_you_want_to_load') ; Hope this helps someone.

jm.federico’s picture

The reason for this is to avoid loading it when not necessary.

aquariumtap’s picture

If you're looking for a way to include libraries that are not bundled with a module (eg: a jQuery plug-in), see the Libraries API.

Wim Leers’s picture

If you're trying to add a weight to a library, don't do it at the library level. You have to specify it at the CSS and JS level, for each CSS/JS file. See the docs for drupal_add_css() and drupal_add_js() for details.

Wim Leers’s picture

In Drupal 8, this is now called hook_library_info().

penyaskito’s picture

It was finally removed: see https://drupal.org/node/2201089

larowlan’s picture

Be careful when using the short hand syntax for js files - see http://drupal.org/node/1396892

Erich Schulz’s picture

this seems really useful, but i'm a bit confused :-)

I see reference to creating .info files for the libraries you want to use eg https://drupal.org/node/1342220#libraries-meta

how does this hook differ from this?

and wouldn't the .info file be preferable? (as it is once per library rather than for each client module)?

BrockBoland’s picture

This is confusing because the name "Libraries" is being used for two different things here.

This page, about hook_library(), is only about the core functionality included in Drupal 7.

The page you linked to is a community doc about the Libraries API module. This contrib module adds some additional functionality, but unless you download and install that module, any .info files you create will be ignored.

Erich Schulz’s picture

sorry basic questions:

* when (ie for what reason) do you implement this hook?

* when is it called?

* does it then load these files on every page?

RobLoach’s picture

when (ie for what reason) do you implement this hook?

If you're adding a third-party vendor library to your module.

* when is it called?

When using #attached for libraries, or using drupal_add_library()

does it then load these files on every page?

Nope, the libraries are only added when they are depended upon, or added directly.

RobLoach’s picture

Correction, if you're adding some JavaScript or CSS to your module, and want a dependency chain for the set of JS/CSS.