If I need to include CSS or JS files in my custom extensions, what would be the best and safest way to achieve this:

  1. Should I put them i a specific folder in my extension zip file?
  2. How should I declare the files in my XML manifest?
  3. How do I include the files in the Joomla header (only when needed)?

2 Answers 2


The best way would be to use the media folder. So, you will firstly need to create a folder called media in your module folder.

Note: This folder should be created before installing, not after.

The inside the media folder, create 2 sub folders, css and js. This isn't required but it's just nicer to keep things separate.

Then add the following to your XML file:

<media folder="media" destination="mod_EXAMPLE">

Change mod_EXAMPLE to whatever your module is.

Upon installation, the media folder will automatically be moved and you will end up with the following:




I know so far I have been referring to a module but the same applies for components too.

To call the file, you can add the following code to your default.php file for your extension:

JHtml::_('stylesheet', JUri::root() . 'media/mod_EXAMPLE/css/style.css');  // For CSS files
JHtml::_('script', JUri::root() . 'media/mod_EXAMPLE/js/script.js');       // For JS files

Hope this helps

  • 2
    You can also do JHtml::stylesheet("mod_EXAMPLE/style.css", array(), true) to load media/mod_EXAMPLE/css/style.css (note the additional css/ part), and JHtml::script("mod_EXAMPLE/script.js", false, true) to load media/mod_EXAMPLE/js/script.js (note the additional js/ part).
    – Flimm
    Jun 15, 2015 at 16:59
  1. I assume that your extension is a component. The best way is to create a media directory beside admin and site directories. Then put js, css and img files inside separate directories like this:

    [+] admin
    [+] site
    [-] media
       [-] js
       [+] css
       [+] img

    Note that any folder should have an empty index.html file.

  2. In your XML manifest (YOUR_COMPONENT_NAME.xml), you can declare media file like this:

    <media destination="com_YOUR_COMPONENT_NAME" folder="media">
  3. Edit the default view (default.php) and add these lines to include the files in the Joomla! head:

    $document = JFactory::getDocument();
    $document->addStyleSheet(JUri::base() . 'media/com_YOUR_COMPONENT_NAME/css/main.css');
    $document->addScript(JUri::base() . 'media/com_YOUR_COMPONENT_NAME/js/main.js');
    $test_image_url = JUri::base() . 'media/com_YOUR_COMPONENT_NAME/img/test.jpg';
  • JHtml should be used to import CSS and JS files rather than addStyleSheet and addScript: docs.joomla.org/J3.x:Adding_JavaScript_and_CSS_to_the_page
    – Lodder
    Aug 4, 2014 at 15:43
  • @Lodder No, it should not. The point is that the parameters of JHtml::script() and JHtml::stylesheet() are changed: docs.joomla.org/Potential_backward_compatibility_issues_in_Joomla_3_and_Joomla_Platform_12.2
    – Farahmand
    Aug 4, 2014 at 16:26
  • @Lodder Regarding your reference: JHtml offers much more flexibility than JDocument, whilst using the same base functionality - indeed at the end of the day JHtml will call JFactory::getDocument()->addStyleSheet() or JFactory::getDocument()->addScript().
    – Farahmand
    Aug 4, 2014 at 16:35
  • 1
    @Fari The parameters only changed from 2.5 to remove support for the 1.5 way of doing things. If you use the 3.x parameters they will work fine in 2.5. Also having written the Joomla Docs page you referenced I would strongly advise that you use JHtml if you're putting stuff in the media folder so people can override your scripts easier (something that isn't possible with JDocument). Although as you say it's not compulsory. Aug 4, 2014 at 18:37
  • 1
    @GeorgeWilson As mentioned in the above referenced link: If you wish to just include a straight file path, in a template for example, then you are better using JDocument. However if you wish to take into account whether debug is enabled to include a compressed script or take advantage of template overridable scripts and stylesheets then using JHtml is generally better. It is recommended all 3rd Party Developers use JHtml to allow template overrides of their CSS and javascript for template designers. So J! site developers use JDocument and 3rd party public extension developers can use JHtml.
    – Farahmand
    Aug 4, 2014 at 19:29

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.