Help:Interactive Maps

Interactive Maps is a feature available on Fandom that enables communities to design their own customized maps. It is available to any community that wishes to use it.

Getting Started
Map creation and editing is currently limited to those with the user right, which is automatically given to administrators and Fandom Staff. There is an "Interactive map tester" usergroup that administrators can give to users to enable them to create and edit Maps.

Once you have the permission to edit Maps, you can find a link "Interactive Maps" in the Explore menu of the top navigation, or you can directly navigate to the creation tool by visiting Special:AllMaps on your wiki, where you can create your own Map and find a list of every Map that exists on your community.

All Interactive Maps live in the  content namespace, e.g.  . Maps created in any other namespace, including as a userspace subpage, will not be correctly generated. When creating a Map via the button on Special:AllMaps, this namespace is automatically added, omitting the need to make this part of the page title.

Unless you have set your preferences to use the source editor, the "Edit" button at the top right of any page in the Map namespace will open the visual Interactive Maps Editor, which is a user-friendly option to edit Maps quickly and easily. Clicking "Edit source" from the dropdown menu will instead take you to the source editor and load the base JSON (JavaScript Object Notation) structure for the Map. If you have the source editor selected as your preference, these options are reversed and the button in the dropdown reads "Edit map". Clicking the pencil icon present on the map itself will always open the visual Interactive Maps Editor, regardless of your preferred editor. While inside the visual Interactive Maps Editor, hovering over the button with the three vertical dots will open a dropdown with the option to "edit source".

Map Display
This section allows you to view your Map name, upload a Map image as your background, and group markers that are in close proximity.


 * Map Name: This is the title of your Map. Your Map will be viewable using the URL, where My New Map is the name that you chose. If you wish to change the name after the Map's creation, hover over the button with the three vertical dots in the top right-hand corner on the Map itself and select the option "move". This will close the Interactive Maps Editor and take you to Special:MovePage.
 * Map Image: Click on this area to upload the image you would like to use for your Map. You can upload a .jpg, .jpeg, .png, or .svg. The maximum file size is 10 MB. Once uploaded, there is an option to replace the image, but doing so may require you to reposition markers placed on the Map.
 * Group Markers: Toggle this option "on" to simplify the number of markers on a Map by grouping ones that are in close proximity. If you click on a grouped location, it will zoom in and show a sub-group or individual markers in a selected location. We recommend grouping large numbers of markers for a better viewing experience.

Categories
Organize markers of a similar kind by grouping them into categories. This list will appear next to the Map and allows you to filter markers by categories.


 * Creating categories: Click the "+ Add Category" button to create a new category.
 * Renaming categories: Click on the category name to change it.
 * Re-ordering categories: Grab hold of the horizontal bars on the right of the category and drag to re-order the categories in the list.
 * Deleting categories: Clicking on the category name will transform the horizontal bar into a trashcan icon to give you the option to delete the category.
 * Customizing category markers: Click the pin icon on the left of the category to open a menu that allows you to customize how markers are displayed for that category.
 * Background color: This will change the color of the marker icon. Click on the colored square to select a color using the color slider, or input a hex code in the field to the right.
 * Emoji or Character: You may choose to add an emoji or single character as a customization option within category markers. This field has a 1 character limit. After adding an emoji or character, it will be displayed inside the default marker icon in place of the dot in the center. To delete the emoji or character, click the X on the right of the input field.
 * Custom icon: Click on this area to upload an image file as a custom icon image for the category, which will replace the default pin icon. You can upload a .jpg, .jpeg, .png, or .svg. The file size for the icon should be between 32x32px and 64x64px. Once uploaded, there is an option to replace or delete each custom icon individually.
 * While the options to either upload a custom icon or use an emoji/character are always enabled, both cannot be active at the same time. In order for the emoji or character to be displayed, you cannot have a custom icon image in use. Uploading an icon image after choosing an emoji will override the emoji and replace it with an image.

Markers
To add a marker to your Map, click the pin icon in the top right-hand corner. Move your cursor to the desired placement on the Map and click to drop it. After you place the marker, a menu will come up with several options that control how your marker will appear on the Map:
 * Title: This is the name of your marker/location. It must be 50 characters or less.
 * Description (optional): This description will be displayed under your title in the pop-up window when your marker is clicked on. This field supports wikitext, so all wikitext specific characters will be displayed in standard wikitext format. The description is limited to 300 characters or less, including wikitext characters that will not be shown in the final marker tooltip. You must save your changes to the marker tooltip in order to see your wikitext rendered.
 * Link (optional): You have the option to link to any article on your wiki (perhaps one that gives more detail on the selected marker/location).
 * Page title: Put the name of the article you would like to link in this field. It does not matter whether you use spaces or underscores for article names.
 * Link display text: Choose how you would like the link text to be displayed. It could be the same name as the article or something like "See more". This field is required if you link a page title.
 * Category: Select which category you would like your marker to be grouped in. Each marker must be associated with a category to better group similar markers.

Once a marker is created, you can drag it to a different location on the Map if you so choose. You can also click on the marker and hover over the three vertical dots to bring up options to edit or delete the marker.

Additional Functions

 * Zooming: Use the + and - buttons in the bottom right corner to zoom in and out of your Map. You can also use the scroll/mouse wheel.

Hovering over the button with the three vertical dots will open a dropdown. Depending on your user rights, you will always get the option to "edit source", "history", and "move" the Map.
 * Edit source: Clicking this will take you out the visual Interactive Maps Editor and to the JSON code of the Map. If you wish to return to the visual Interactive Maps Editor, you need to exit the source mode and click the edit pencil on the Map again.
 * History: This will take you out of the editor and to the page history of the Map, showing you all edits and changes made by anyone and giving you the option to undo them if necessary.
 * Move: This will close the Interactive Maps Editor and take you to Special:MovePage, where you can choose a new name for your Map.

The following options are only available to those with the content moderator right or higher.
 * Protect: It opens the options for protecting your Map.
 * Delete: This will delete your Map. You can always restore it if you did this by accident.

As you are making edits, the preview window will display your changes in real time, so you can see how your Map will look before you save it. When you are finished, click the "Save" button and your new Map will now appear on the wiki!

Building a Map using JSON in Source Editor
Every Interactive Map is defined in JSON (JavaScript Object Notation). The following fields should be defined in order to generate the Map:
 * (required) – name of the file that will be used as the map background image. The image must be uploaded to the wiki (e.g. using ). The following file extensions are supported:   /   /   /.
 * (required) – bounds defining the edges of the map, given as a  matrix of integers.
 * (required) – list of categories that will be displayed in the filters list (the dropdown menu found top-left of the map).
 * (required) – list of markers that will be displayed on the map. Each marker must be associated with a defined category.
 * (required) – location of the origin point [0,0] in the coordinate system.
 * Possible values:  (default) or.
 * (optional) – category of the page.  will put the map into "Category:Foo".
 * (optional) – Used to change the default sort key, which influences the position that the map appears in category pages. If not present, the map is sorted using its page name (i.e. without the Map: namespace prefix).
 * (required) – order of coordinates used in defining map bounds and marker positions.
 * Possible values:  (default) or.

Categories
Categories are a group of markers of the same kind. Each marker category is defined through the following fields:
 * (required) – uniquely defined ID for each category, matched with the  property of each marker. Any string is valid as an "id".
 * (required) – ?
 * (required) – name of the category, which will be displayed in the filters list.
 * (required) – color each marker category will appear with, which can be given in hex colors or named colors. Categories with an invalid color field will display as black.
 * (optional) – add a single Unicode character or an emoji to the center of the default pin. The character may be represented either verbatim (by typing or pasting it into the field), or by using a JavaScript-escaped UTF-16 hex code in the format  (see a list of example codes for emojis here. E.g.   to generate 😄).
 * (optional) – When choosing a single character, you must choose its color by adding the hex code (e.g. #FF0000) or color name (e.g. red). Be mindful of accessibility and the contrast with the marker color. Note that when you edit the character later via the Interactive Maps Editor, the character color will automatically change to black or white depending on the marker's background color.
 * (optional) – icon image of the category, which will replace the default pin icon. The file used for the icon should be between 32x32px and 64x64px and allowed formats are svg, png, and jpg.

Markers
Each individual marker is defined through the following fields:
 * (required) – category associated to the marker.
 * (required) – coordinate position of the marker, within the given  and in the order defined by.
 * (required) – properties of the pop-up box that appears when a marker is clicked on:
 * (required) – title of the marker. Each marker title has a strict 50 character limit.
 * (required) – description to be displayed in the pop-up. Each marker description supports wikitext and has a strict 300 character limit. The description itself may be left blank (""), but the field must be present.
 * (optional) – article link to be added to the pop-up. Marker links are optional, but if included must be defined with both a  (the article title to be linked to) and a   (the link text to be displayed). The URL can link to both full articles and article sections.
 * – a unique ID for each marker, that can be used to link directly to a specific marker.

Marker Clusters
For ease of display, markers are grouped locally into clusters. Hovering over a cluster will show an outline of the area of the markers contained within that cluster, with the number indicating the quantity. Clicking on a cluster will zoom into that area.

There is currently no way to adjust the sensitivity of the clustering.

Filters
Maps have a filters menu that allows them to show or hide a specific marker category, if you want to see only a specific one. Select "Select all" to show all map markers, or select specific categories to only see markers from that category.

Popups
Popups display more information about the marker, including a title, a description, and an optional link pointing to a relevant page.

A dropdown menu (⋮) in the corner of the popup can be clicked to display more information:
 * Copy link: - Copies a link to the marker to the clipboard. When the link is followed, the map will zoom in to bring the marker into focus and will show its associated popup. See below for more information.

Embedding a Map
To get more eyes on your Map, you can embed it into a mainspace article if you wish. Once the Map has been created, it can be transcluded into an article using the  wikitext syntax.

Like templates, more than one Map can be embedded in an article. Maps embedded in articles will have an edit button at the top right of the Map. Clicking this will open the Interactive Maps Editor in a new tab, allowing it to be edited directly.

Aligning and Placement
By default, the map will take up 100% width of the containing element (i.e., if it's placed in the middle of an article, it will expand to the full width of the page). You can manipulate its placement by embedding it inside a  element or table, which allows you to specify alignment, width, and other properties.
 * Note that in order for a map inside such an element to fit in the article properly, it must be 530px wide or less.

For maps placed next to an infobox or other floating elements, you can adjust the embed to fit flexibly using  in a surrounding div. Alternatively you can move it below floating elements (so that it appears after the infobox) with, or a   before the embed.

Also, you can place a Map inside an infobox, although this will greatly limit its functionality.

Linking to Markers
Map markers can be directly linked to by including the query parameter  in an external link to the map, where marker_id is the ID of the marker that should be displayed.

As an example, on the Avatar Wiki, the following link will link to a marker with the ID 42 on the Avatar world map: https://avatar.fandom.com/wiki/Map:Avatar_world_map?marker=42. This can be generated in wikitext using the fullurl magic word. For example:


 * → https://avatar.fandom.com/wiki/Map:Avatar_world_map?marker=42
 * → Jang Hui

This works when linking to the map page itself, or on any page where the map is embedded. If multiple maps exist on the page being linked to, the marker matching the ID across all embedded maps on said page will be focused, not just the first.

Note that marker links can be used with a page anchor ('#'), as long as the anchor tag goes after the query string. However, the anchor will be ignored, and the map will be automatically scrolled to instead, assuming the marker ID is valid and the map is visible when the page loads. This may be used in a Tabber-embedded map to switch to the specific tab, scroll to the map (and not the start of the tab since maps override anchoring), and then focus on a marker at the same time (for example).

Useful links

 * First announcement of Interactive Maps
 * 2022 update for Interactive Maps
 * Full launch of Interactive Maps

Map examples

 * Avatar Wiki: Map of the World of Avatar
 * Pillars of Eternity Wiki: Over 200 comprehensive maps
 * Starlancer Wiki: An unorthodox use of Maps to create a starship diagram

Further help and feedback
de:Hilfe:Interaktive Karten es:Ayuda:Mapas interactivos fr:Aide:Cartes interactives id:Bantuan:Peta Interaktif it:Aiuto:Mappe Interattive pl:Pomoc:Interaktywne mapy tr:Yardım:Etkileşimli Haritalar uk:Довідка:Інтерактивні мапи zh:Help:互動式地圖