I'd like to know the 'currently' correct way to add JavaScript to the head of a page. The documentation suggests using $document->addStyleSheet($url);, but the API documentation says that this method is deprecated.

There is also the JHTML::_('script','path','options') method, but the first piece of documentation I referred to says that this is deprecated and was removed in 3, even though it still works.

1 Answer 1


The method itself isn't deprecated, only the format of the function parameters.

Earlier Joomla versions (deprecated):

$doc->addScript($url, $mime, $defer, $async)

Later Joomla versions:

$doc->addScript($url, $options, $attributes)

I'm not sure what the JHtml deprecation notice is about but it shouldn't affect what you're trying to do.

So to answer you actual question, the correct way to add Javascript to your site will be as following:


   // more Javascript here


    JUri::root() . 'templates/MY_TEMPLATE/js/file.js'

If this is for an extension if your own and you're importing a file, I'd suggest using the JHtml approach, as it will allow users to override the file , along with some other additional perks:

Path to your JS file:



JHtml::_('script', 'mod_something/file.js', array('version' => 'auto', 'relative' => true));

Notice that I'm using 'relative' => true so the path can be shortened.

Hope this helps

  • Thanks for the guidance. I've taken a look at the source and I'd argue that its a misuse of the docblock @deprecated tag within the core code. According to phpDocumentor, the @deprecated tag "declares that the associated Structural elements will be removed in a future version". Using @deprecated means that IDEs such as PHPStorm will warn about the usage of the method.
    – Dom
    Apr 27, 2018 at 13:15
  • @Dom Normally I'd agree, however with something like this, Joomla didn't want to rename the function name, meaning backwards compatibility is kept, therefore they deprecated the way it's called, rather than the method itself.
    – Lodder
    Apr 27, 2018 at 13:18
  • By changing the method signature Joomla has broken backwards compatibility. This is not how @deprecated is supposed to be used, phpDocumentor is very clear what it means and Joomla has used it incorrectly in this instance.
    – Dom
    Apr 27, 2018 at 15:06
  • They havent broken BC cause the old approach still works in 3.x but will be removed in 4.0. Deprecated doesnt mean it doesnt work anymore
    – Lodder
    Apr 27, 2018 at 15:10
  • @deprecated means that 'the associated Structure elements will be removed in future versions', not that that the method signature will change.
    – Dom
    Apr 29, 2018 at 11:09

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.