Fandom Developers Wiki

Modal library is a library for easier and faster creation and display of Fandom's built-in modals.



To import the Modal library inside your script, use:

    type: 'script',
    article: 'u:dev:MediaWiki:Modal.js'

The script's object won't be immediately available, but it will call a hook through mw.hook. To ensure it exists, you can use:

mw.hook('dev.modal').add(function(modal) {
    // `modal` object is the library's exported object, same as

Exported object

The library exposes an object with several properties:

The main class of the library. Instantiating it registers the modal in the library.
Class for modal's buttons.
Object with all registered modals.
Function called before the hook is fired as a callback for when Fandom's modal component loads.
Fandom's modal component internally used by the library.



Class representing the modal object.


Unique ID of the modal. This parameter is required.
Object that modal events should be bound to.
Size of the modal. Accepted values are small, medium, large and content-size.
Content of the modal.
If set to a string, it represents the HTML the modal contains.
If set to an object while UI-js is imported (UI-js must be imported before Modal, otherwise it won't work), it runs the object through the dev.ui function and sets the generated HTML as the modal's content.
Note: DOM events set on the nodes through UI-js will get unregistered, as the library calls .outerHTML on the node.
Title of the modal. By default set to "Modal". This is safe by default unless isHTML is set, in that case it must be escaped properly.
Whether the title of the modal is passed as HTML.
Array of objects representing parameters to the ModalButton model.
Map of event names to event listeners to register in the modal. These events can be called by modal buttons.
By default, Fandom's modal component registers a close event called when the close button is clicked.
Values of the events object can be single functions, which registers as the only event listeners, or arrays of functions, which registers them all as event listeners.
class / classes
String or an array of strings representing the classes of the modal.
Function called upon closing the modal, which can return false if the modal should not continue closing.
Whether the modal should be closed when the Esc button is pressed. By default enabled, set to false to disable.
Title on the X button for closing the modal.


Here are the available properties of a Modal instance. Most of them are based on input parameters described above.

  • id
  • context
  • buttons
  • classes
  • closeFunc — Callback after closing the modal.
  • closeEscape
  • closeTitle
  • content — HTML of the modal as a string.
  • events — Map of event names to arrays of callback functions when these events are fired.
  • size
  • title
  • titleIsHTML — Whether the title is displayed unescaped.
  • _loading — Internal promise object that is resolved at the time the modal's component is created.
  • _modal — Internal modal object returned by the modal factory.


Here are the available methods of a Modal instance. Most of them as used as setters for properties mentioned above. Each of these methods returns a self instance so they can be easily chained together.

  • create() — Starts the creation of the modal component and returns a promise that resolves when the creation is done.
  • show() — Shows the modal. If its creation hasn't finished yet, it will wait until the creation and then show the modal.
  • close() / hide() — Closes the modal.
  • setButtons(buttons)
  • setClass(class)
  • setClasses(classes)
  • setClose(close)
  • setCloseEscape(closeEscape)
  • setCloseTitle(title)
  • setContent(content)
  • setEvent(name, listener)
  • setEvents(events)Note: This resets all other events of the modal.
  • setSize(size)
  • setTitle(title, isHTML)
  • _close() — Internal callback after a close event has been triggered. Starts recreation of the modal.
  • _created(modal) — Internal callback after the modal component has been created.


Class representing a button in the modal's footer.


Type of the button. Set to button by default. Can be set to either:
  • link
  • input
  • button
Whether the button is a primary one or not. Adds a primary class to the button.
Adds a normal class to the button.
text / value
Text on the button. This parameter is required.
events / event
Array of events the button is triggering, or a string if it's triggering a single event.
Array of classes, in addition to the primary and normal ones.
ID of the button.
Whether the button is disabled.
sprite / imageClass
Sprite class added to the button. Available sprite classes are:
  • edit      
  • talk      
  • talk-two      
  • categorization      
  • move      
  • new      
  • photo      
  • video      
  • search      
  • mytools      
  • follow
  • share
  • logo
  • logo2      
  • logo3      
  • logo4      
  • logo9      
  • drag      
  • trash      
  • activity      
  • random      
  • close      
  • edit-pencil      
  • edit-pencil-small      
  • blog      
  • message      
  • lock      
  • remove      
  • details      
  • info-icon      
  • ok      
  • error      
  • contribute      
  • question      
  • close-notification      
  • popout      
  • embed      
  • email
  • share2      
  • gear      
  • facebook
  • external      
  • progress      
  • play      
Location the button is linking to if type is set to link.
Title of the link, if type is set to link.
Target of the link, if type is set to link.
Name of the input element, if type is set to input.


Available properties of the button object. Their purpose is described in the parameters.

  • primary
  • normal
  • classes
  • disabled
  • events
  • href
  • id
  • name
  • text
  • type
  • sprite
  • target
  • title


Available methods of the button object. Most of these are setters for the properties described above.

  • create — Returns required Mustache parameters for rendering the modal button.
  • setClasses
  • setDisabled
  • setEvents / setEvent
  • setHref
  • setID
  • setName
  • setText
  • setSprite
  • setTarget
  • setTitle


As the documentation above might be confusing, here are a few examples with demonstrations. Wrappers mentioned in the Usage section won't be used.

Simple modal

This example simply creates a small modal with the default title, ID of SimpleModal and "Hello World!" as contents.

var modal = new{
    content: 'Hello World!',
    id: 'SimpleModal',
    size: 'small'
Try it out!

Medium-sized modal

This example creates a medium-sized modal with the title of "Medium sized modal" and ID of MediumModal.

var modal = new{
    content: 'This is a medium-sized modal.',
    id: 'MediumModal',
    size: 'medium',
    title: 'Medium-sized modal'
Try it out!

UI-js modal

This example creates a modal with contents being generated by UI-js and sized the same as the page content.

var modal = new{
    content: {
        children: [
            'This modal uses UI-js to generate the content and it\'s the same size as the content.',
                attr: {
                    alt: 'Fandom logo',
                    title: 'Fandom logo',
                    src: ''
                type: 'img'
        type: 'div'
    id: 'UIModal',
    size: 'content-size'
Try it out!

Buttons modal

This example creates a modal with various kinds of buttons. One is disabled, one is primary, one is an input element and one is a link.

var modal = new{
    buttons: [
            classes: ['my-custom-class'],
            event: 'custom1',
            id: 'my-custom-id',
            primary: true,
            text: 'Primary button'
            disabled: true,
            text: 'Disabled button'
            event: 'custom2',
            sprite: 'ok',
            text: ' '
            event: 'custom3',
            name: 'my-name',
            type: 'input',
            value: 'This is actually an input element!'
            href: mw.util.getUrl('Special:Random'),
            target: 'hmm',
            text: 'This is a link!',
            title: 'This is the link\'s title!',
            type: 'link'
    content: 'This modal has buttons!',
    events: {
        custom1: function() {
            new BannerNotification('Custom event 1!', 'confirm').show();
        custom2: function() {
            new BannerNotification('Custom event 2!', 'warn').show();
        custom3: function() {
            new BannerNotification('Custom event 3!', 'error').show();
    id: 'ButtonsModal'
Try it out!
Text above can be found here (edit)