ReferencePopups is a re-implementation of Wikipedia's reference popup gadget, a feature which allows you to hover over a citation and view the contents of the reference in a floating box. The obvious advantage of this is that you can view the references in situ (in position), without having to scroll to the bottom or click the citation and lose your place in the article. You can have a look at the demonstration here.

This gadget includes intelligent color scheme matching so it will try to fit itself into the wiki's color scheme automatically without requiring any custom CSS to fix it. It does this using the colors from Special:ThemeDesigner; if you have altered the wiki's colors using CSS instead of ThemeDesigner then this might not work properly.

Monobook lacks ThemeDesigner support which means that the color system for that skin is more fragile than Oasis, so please be sure to check that it displays appropriate colors in that skin when you install it. If you encounter a wiki where the color adaptation doesn't work properly and it looks wrong, please report it on the talk page so that it can be made smarter.


See also: Help:Including additional CSS and JS, Help:Advanced CSS and JS
  • For site-wide use, an administrator can add the line below to the wiki's MediaWiki:ImportJS page.
  • For personal use, add the code snippet below to your global.js page (for use on all wikis) or your common.js page on your wiki (for use on a single wiki). Note that personal JS must be enabled for your account.
    type: 'script',
    articles: [
importArticles — Best Practices for installing JavaScript on FANDOM
The importArticles statement is designed to combine multiple HTTP requests into a single data transfer, allowing multiple scripts to load and execute faster. If you've been installing several different scripts, your JavaScript file has probably accumulated unnecessary import statements. Click "Expand" to learn how to efficiently batch import scripts to speed up performance and make your code look cleaner. One other approach is by using the MediaWiki:ImportJS.
If your JavaScript file has several lines of code that say importScript, importScriptPage, or importArticles, you may be able to combine them! By batch importing a collection of scripts with a single import, your JavaScript code will load faster and look cleaner. Consider the example below. On the left is an example of what your JavaScript file might currently look like. On the right is how you could improve that code.
Multiple imports — messy and slow One import — clean and efficient
  type: 'script',
  article: 'u:dev:FloatingToc/code.js'
importScriptPage('page1.js', 'wikiname');
importScriptPage('page2.js', 'wikiname');
    type: 'script',
    articles: [
Note: In this example, pay close attention to the placement of commas and other punctuation. For people who aren't familiar with programming (and even those who are!), a common mistake when writing code is to accidentally delete, forget, or misplace critical symbols like commas or quotation marks. This can cause a syntax error that breaks the code. Carefully follow the convention shown here when using importArticles.
But there's much more to importArticles than just this! For more examples and advanced usage, see the help page at Help:Including additional JavaScript and CSS.

Usage Notes

The popups are configurable via the built-in UI. You can trigger them via clicking instead of hovering, customise the hover delay, and turn the animations on and off. It's also possible to disable them entirely on a per user basis for individual users who don't want it.

When popups are disabled, there is a link at the end of the article, just below the categories, that can be clicked to reopen the configuration UI to turn them back on later.

Quick Help on Configuration

The options in the popup configuration are:

  • Disable Reference Popups — This deactivates the popups so they will no longer appear, except custom ones. They can be turned back on using the "Configure Reference Popups" link at the bottom of articles.
    • Some wikis may lock the popups which will prevent you from being able to turn them off. You should contact the administrators on that wiki to discuss it in that case.
  • Hover delay — The amount of time (in milliseconds) you must hover your mouse over the reference before the popup will open. The default is 200ms but you can adjust it if this is too long or too short for your taste. Be aware that very short values can be annoying when scrolling.
  • Make popups stay open until touched with the mouse — Popups will stay open once they appear, like they do in Click mode, until you move your mouse over the popup and then out of it. This allows you to open the popup by hovering then move your mouse somewhere else without the popup closing on you until you want it to.
  • Activate by — By default, the popups react on hovering; however, you can toggle between hovering and clicking at your preference. In click mode, you must click the references to open the popups.
    • In click mode, clicking the reference a second time whilst the popup is already open will bypass it (close it) and take you to the references section at the bottom of the article as per normal.
  • Enable Open/Close Animations — By default, the popups have a sliding open/closed animation that runs for 300ms. This is generally more pleasing to the eye then snapping open, but if you don't care for it then you can turn it off.

Administrator Configuration

Administrators can remove the gadget's configuration link from their wiki by putting Reference Popups into "lockdown" mode. This will force the popups to stay enabled and remove the configuration link from the end of the article, but not from the popup itself.

To enable lockdown, just add this to MediaWiki:Common.js above the aforementioned import:

(( = || {}).ReferencePopups = dev.ReferencePopups || {}).lockdown = true;

You can also alter the defaults for new users. You can disable the animation by default using:

(( = || {}).ReferencePopups = dev.ReferencePopups || {}).defaults = { animate: false };

Custom Popups

The popup component of this script is fully reusable and can be repurposed to display anything you want as well as references. A pre-made script and template set is provided if you just want something to drop in and use. Alternatively, if you are capable of writing your own JavaScript, you can instead code against the popups directly to do things like AJAX new content and display it in a popup as certain elements are interacted with.

To use the custom popups, you will need to import the Custom Popup script:

    type: 'script',
    articles: [
        // ...
        // ...

And you will need to copy these 2 templates onto your wiki to make use of the script:

The templates describe how to use them.

An important thing to note is that the custom popup script will use the user's ReferencePopup configuration even though the gear icon doesn't appear in custom ones. This means that if the popup is in click mode then attaching popups to page elements that already have their own scripts can have strange consequences. Unlike normal popups, custom ones are never sticky and can't be disabled though.

You can also construct custom skins for you custom popups as well. An example of this is on the demo page, you can see the CSS for it over here.