Help:Including additional CSS and JS

This help page will explain the recommended ways to include additional CSS and JavaScript on your community.

ImportJS[]

MediaWiki:ImportJS provides an interface for including articles that contain scripts - both local and fromDev Wiki - on a community.

The wiki does not needcustom JS enabled for ImportJS to work.

Usage[]

ImportJS is a plain text article in which article names to import are specified line-by-line. All local files and Dev Wiki imports must be in the MediaWiki namespace to work. When stating files to import, the MediaWiki namespace should not be included in the name.

The system attempts to load each line, ignoring invalid titles. Thus you can achieve comments by prefixing a line with//, or#, or any other invalid title character. Example:

//local JS file, located at "MediaWiki:Cat.js"Cat.js// Dev Wiki script, located at "MediaWiki:UploadMultipleFiles.js"dev:UploadMultipleFiles.js

The functionality of ImportJS is similar to that ofimportArticles(), which can import several articles from local and external communities, bundling them into one network request andminifying them. BothimportArticles() and ImportJS reduce file size and web traffic, effectively making a community with a large number of additional files load much more quickly.

JavaScript review: The ImportJS feature of the Content Review extension bypasses the need for theJavaScript review process, allowing the immediate addition or removal of a community's JavaScript imports.

Load order[]

When using ImportJS, the pages within will be loadedlast. The full load order is:

1. Common.js
2. Fandomdesktop.js
3. Imported scripts through Common.js
4. Imported scripts through Fandomdesktop.js
5. ImportJS

Common.js and Fandomdesktop.js is guaranteed to be executed before any imports. As such, many dev scripts use these pages for configuration purposes.

For groups of imports (being each separate call toimportArticles(),mw.loader.using(), or the ImportJS definition), the order above determines what order they arerequested, but not necessarily what order they are executed in. This is because they are downloaded asynchronously, and executed as soon as they are loaded.

However, multiple scripts within a single import do have a predictable execution order:

• InimportArticles() andmw.loader methods, scripts are executed alphabetically.
• InImportJS, scripts are executed sequentially in the order that they appear on the page.

If writing code that depends on the existence of an imported script, you should never rely on the execution order. Instead, always use the callback or promise returned byimportArticles() ormw.loader.using(), which fires/resolves when the script(s) are loaded and executed. Seeadvanced usage for more information.

CSS imports[]

@import method[]

Using the@import, styles can be imported from any CSS file hosted on a wiki or on other websites (ending with .css on the url and contains changes for the default skin elements on the file). The syntax is as follows:

@import"path_to_file_to_import.css"

Per the above example, to import Local.css into Common.css, place this at the top of your Common.css file (it must be before any other rules):

@import"/load.php?articles=MediaWiki:Local.css&only=styles&mode=articles";

If you are importing more than one CSS file hosted on the wiki, it is recommended to pass each CSS file you are importing toarticles= as a| delimited string:

@import"/load.php?articles=MediaWiki:One.css|MediaWiki:Two.css&mode=articles&only=styles";

For a non-English wiki, include the language path at the start of the URL:

@import"/de/load.php?articles=MediaWiki:Local.css&only=styles&mode=articles";

@import is render-blocking, meaning that the site will wait until the CSS file is fully loaded before anything is displayed. This ensures that there is no flicker that might occur as a result of styles taking affect after the site has already been rendered on the user's device. However using imports can slow down page loads, particularly if multiple import statements are present as they will occur sequentially instead of concurrently.

You can read more on this methodhere.

importArticles[]

In lieu of the above method, importArticles will only be discussed here in regards to CSS imports. For JS imports, please seethis page.

importArticles can still be used to import CSS styles. However, they will be subject to JS review since it has to be implemented through JavaScript.

Unlike @import, importArticles can occur in the background, and the presentation of the page isn't blocked. Loading CSS in this way can result in faster load times, but may result in a flicker effect as the styles are applied after the page is initially displayed.

Which method you use comes down to your use case. If you're applying styles that drastically affect the appearance of every page and need to avoid flicker; use the @import method. If your styles aren't important, need to be conditionally loaded, or affect parts of the page that aren't always visible immediately; use importArticles.

Example[]

Importing a local CSS file through importArticles:

importArticles({type:"style",article:"MediaWiki:Local.css"});

See also[]

• Help:Including additional CSS and JS/technical
• Help:CSS and JS customization
• Help:Advanced CSS and JS
• Help:CSS and JS pages

Further help and feedback[]

• Browse and search other help pages atHelp:Contents
• CheckFandom Community Central for sources of further help and support
• CheckContacting Fandom for how to report any errors or unclear steps in this article