 | A request that this page title be changed toHelp:Extended image syntaxHelp:Extended image syntax isunder discussion. Pleasedo not move this page until the discussion is closed. |
 | This help page is ahow-to guide. It explains concepts or processes used by the Wikipedia community. It is not one ofWikipedia's policies or guidelines, and may reflect varying levels ofconsensus. |
This how-to documents the syntax used to insert pictures and other media files into Wikipedia pages. The same syntax is used regardless of whether a file is from Wikipedia orWikimedia Commons.
New editors are encouraged to also see thepicture tutorial and thesimple guide for beginners.
In brief, thesyntax for displaying an image is:
[[File:Name|Type|Border|Location|Alignment|Size|link=Link|alt=Alt|class=Class|page=Page|lang=Langtag|Caption]] .Plain type means you always type exactly what you see.Bold italics represent a variable, which you replace with its actual value.
Of the options shown, onlyName is required. Others are optional and can be placed in any order.
Most images should use[[File:Name|thumb|alt=Alt|Caption]] and should not specify a size.
thumb (orthumbnail; either can be followed by=filename),frame (orframed), orframeless. Displays the image with specific formatting (see below).border. Put a small border around the image.right,left,center ornone. Determine the horizontal placement of the image on the page. This defaults toright for thumbnails and framed images.baseline,middle,sub,super,text-top,text-bottom,top, orbottom. Vertically align the image with respect to adjacent text. This defaults tomiddle.upright orupright=scaling factor. Scale a thumbnail from its default size by the given factor (default 0.75), rounding the result to the nearest multiple of 10 pixels. Theupright option must be used along with thethumb orframeless option. Alternatively, and only where absolutely necessary, users' preferences may be disregarded and the size of the image fixed by specifying a size in pixels:Width px orxHeight px orWidth xHeight px. Scale the image to be no greater than the given width or height, keeping its aspect ratio. Scaling up (i.e. stretching the image to a greater size) is disabled when the image is framed.switch-translatedSVG (Scalable Vector Graphics) files. Some SVG files are multilingual; this option specifies which language to use. The langtag should be all lowercase (e.g.,zh-hans rather thanzh-Hans). Defaults to current Wikipedia language in article namespace oren in other namespaces. See{{Translate}}.thumb orframe attribute is used, but may be displayed onmouseover in other cases.The image syntax begins with[[, contains components separated by|, and ends with]]. The[[ and the first| (or, if there is no|, the terminating]]) must be on the same line; other spaces and line breaks<br> (or<br />) are ignored if they are next to| characters or just inside the brackets. Spaces or line breaks are not allowed just before the= in the following options, and may have undesirable side effects if they appear just after the=.
Do not terminate with the code|]]; this will be taken as anempty caption and override anyreal caption before it.
One of these options may be specified to control whether or not the image is scaled and/or given a border. For options that automatically scale the image, it's usually to 220px; logged-in users can modify this (at "Thumbnail size" underPreferences →Appearance →Files). This is important to users with (e.g.) limited vision. If this is too large or small theupright attribute can be used. Specifying a fixed size in pixels overrides all of this, but is unfriendly to users who need a larger image.
thumb (orthumbnail)thumb=Example.png, the operand names an image that is used as the thumbnail, ignoring any size specification.frameframelessborder|thumb and|frame), as framed images always have borders.One of these options may be specified to control the position of the image. For examples of how all this works, seeExamples of location parameter.
rightthumb orframe is used.leftcenternonethumb norframe
like this.One of these options may optionally be specified to control the vertical alignment of the image with respect to adjacent text.
These vertical alignment options apply only to plain images, which do not cause breaks and are not floated (that is, they do not work with images that need text to flow around them. To make text flow around an image, place the image preceding the text and use thethumb parameter).
In the following list, each option's explanation is preceded by whatFile:Flag of Hungary vertical.svg looks like when aligned using the listed option, using the markup
of [[File:Flag of Hungary vertical.svg|option|frameless|upright=0.1|link=|alt=]]
middle:
(This is the default.) Align the vertical middle of the image with the baseline of the text plus half thex-height of the text, so that the image is vertically centered around a lower case "x" in the text.
baseline:Align the bottom of the image with thebaseline of the text.
sub:Align the bottom of the image to the same level that the bottom of a subscript would be, such as the bottom of the "2" in "X2".
super:Align the bottom of the image to the same level that the bottom of a superscript would be, such as the bottom of the "2" in "X2".
text-top:Align the top of the image to the top of the text. This is often a bit higher than the top of a capital letter, because ofascenders in letters like lower-case "h".
text-bottom:Align the bottom of the image to the bottom of the text. This is somewhat lower than the baseline, because ofdescenders in letters like lower-case "y".
top:Align the top of the image to the top of the line containing the text. Normally this is slightly higher than the top of the text, to make space between lines of text.
bottom:Align the bottom of the image to the bottom of the line containing the text. Normally this is slightly lower than the bottom of the text.
Here they are next to each other. The order below is:
super,topbaselinesub,text-bottommiddletext-top,bottom
Any or none of these options may be specified to control the size of the image. In the case of images with captions, if the image is already smaller than the requested size, then the image retains its original size (it is not enlarged). In the case of images without captions, the image will be enlarged or reduced to match the requested size. Sizing is disabled when thetype 'frame' is use, with the size options being flagged as abogus file option atSpecial:LintErrors.
The default thumbnail width can be set in the preferences, sospecifying in px is not recommended in order to respect the users' preferences, which may be important for accessibility. Exceptions can, of course, be made, but do try to useupright or the default if possible.
Implementation details |
|---|
Specifying a size does not just change the apparent image size using HTML; it actually generates a resized version of the image on the fly and links to it appropriately. This happens whether or not you specify the size in conjunction with "thumb". This means the server does all the work of changing the image size, not the web browser of the user. Having the server do all the work means faster downloading of pages. It also means that larger images can be stored on the server without any slowdown by the browser (especially on dial up telephone lines). Only the data for the actual size on the page is transmitted. An exception is animated GIF images. Animated GIF images are not processed by the server. When a smaller size is specified the original full sized animated GIF image is served. Whether the animated GIF image is subsequently scaled to fit the allotted space belongs to the capabilities of the receiving browser. Resizing an animated GIF image will significantly reduce its quality, without any reduction of download time. When there are two or more "size" options of the same type, only the last one is valid. However, if both an upright and an absolute size are used together, the absolute size always takes precedence, regardless of where it appears in the options. |
uprightorupright=scaling factorupright=1.5 makes the image larger, which is useful for maps or schematics that need to be larger to be readable. The parameterupright=1 returns the same size as thumbnail width, andupright=0.75 is functionally identical toupright alone. If you setscaling factor equal to the image's aspect ratio (width divided by height) the result is equivalent to scaling the height to be equal to the normal thumbnail width.upright option only works with thethumb orframeless parameter (seeType).px100px) Scale the image to make it the specified number of pixels in width, and scale the height to retain the original aspect ratio.xHeightpxx150px) Scale the image to make it the specified number of pixels in height, and scale the width to retain the original aspect ratio.xHeightpx100x150px) Scale the image to be no wider and no higher than the specified number of pixels. The imagewill keep its original aspect ratio.|link=Page|link= (alone)|link= affects only what happens when theimage itself is clicked;|thumb images carry a little rectangle-rectangle icon
in the caption area, and clicking that always leads to the image description page.Except for public-domain images, it must always be possible for the reader to reach the image-description page, so|link= should be used only with|thumb images.
|link= cannot be used with|frame.
To disable all linking from, and description of, apurely decorative image – so that it's ignored by screen readers – use "|link=|alt=" with no arguments for either parameter.
Zero or more of these options may be specified to control thealt text,link title, andcaption for the image. Captions may contain embedded wiki markup, such as links or formatting. SeeWikipedia:Captions for discussion of appropriate caption text. SeeWikipedia:Alternative text for images for discussion of appropriate alt text. Internet Explorer displays the link title as a tooltip but other browsers may not.[needs update]
Hint: to force the caption to be written (underneath the picture) and not just appear as "hover text" even when you wish to resize the image, specify "thumb". If you specify "frame" the caption does appear but any resizing (such as "125px") is ignored.
alt=Altthumbnail", "thumb", "frame" or "framed") then this text appears as a caption below the image. Otherwise, (if the image type is unspecified or is "frameless"), this text is used for the link title provided the link has not been suppressed with "|link=", and also for the alt text provided an explicitalt=Alt has not been supplied.The actual alt text for the displayed image will be one of the following, in order of preference:
It is possible to specify the link title text only for images with no visible caption (as described above). However, as not all browsers display this text, and it is ignored by screen readers, there is little point.
Note:alt is supported only for images. Audio and video files should usetimed text.
class=class=notpageimage will exclude the image from being selected by thePage Images algorithm.(phab:T301588)class=skin-invert will cause the image's colors to be inverted indark mode.class=skin-invert-image will only invert the image and not the caption.class=skin-invert-image notpageimage skin-invert | skin-invert-image | |
Normally page 1 from a PDF or DjVu file is used to generate the thumbnail. A different page can be used with the parameter|page=:[[File:IMSLP01578-Ravel - Bolero Full Score Durand 1929.pdf|thumb|page=2|''Boléro'': page 2 from the score]]:
The most basic example uses the syntax[[File:Westminstpalace.jpg|Alt text]]. This does not scale the image or allow text to wrap around it. This is not normally appropriate in an article.
This is rendered inline, and the specified text is used as the image'salt attribute (alternate text for programs which cannot display images, such asscreen readers) and as thetitle attribute (supplementary text, often displayed as a tooltip when the mouse is over the image). SeeWikipedia:Captions for discussion of appropriate caption text. SeeWikipedia:Alternative text for images for discussion of appropriate alt text.
Above, the image of the Thames was put into its own paragraph. This isn't mandatory; images can sit inline in text, as shown below.
text text text text text text[[File:Westminstpalace.jpg|150px|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]]text text text text text[[File:tst.png|100px|alt=Tiny globe|This is a globe.]]text text text text
gives
text text text text text texttext text text text text
text text text text
To display an image as uploaded with a caption use[[File:Westminstpalace.jpg|frame|none|alt=Alt text|Caption text]].
This is the style most familiar to readers. As shown on in the example image, the image is framed, is an appropriate size, and has text able to wrap around it. A caption is properly integrated.
The important part of this is thethumb parameter:[[File:Westminstpalace.jpg|thumb|upright=0.4|left|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]] (as shown in the left). For details of these options, see previous sections.
Examples of the location parameter are below:
[[File:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|right|upright=0.35]] (shown on the right).[[File:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|left|upright=0.35]] (shown on the left).[[File:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|center|upright=0.35]] (shown above).[[File:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|none|upright=0.35]] (shown above).There is a floating issue in HTML/CSS that prevents certain images (or other floating objects) from floating above others. It occurs only if:
The first floating object on the latter side of the page won't float above the last floating object on the former (see examples below). Solutions include alternating between left and right in aligning images or other floating objects (not shown); setting to "none" the alignment of the one that won't float above the others (as demonstrated on the population tablehere); and using a gallery tag for large numbers of images in a single section. PerMOS:ACCESS#FLOAT, images should be inserted in the relevant section (i.e. do not place the markup above the section headline), even if that can cause them to float into the next section.
Problematic code:
==Section 1==[[File:Westminstpalace.jpg|thumb|70px|right|Figure 1.1 ('''right''')]][[File:Westminstpalace.jpg|thumb|70px|right|Figure 1.2 ('''right''')]][[File:Westminstpalace.jpg|thumb|70px|right|Figure 1.3 ('''right''')]][[File:Westminstpalace.jpg|thumb|70px|right|Figure 1.4 ('''right''')]]Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.==Section 2==[[File:Westminstpalace.jpg|thumb|70px|left|Figure 2.1 ('''left''')]]Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
For more information on the gallery tag, seeHelp:Gallery tag.
upright" option is about 75% of thumbnail width.upright=1.5" option Theupright option works in combination with thethumbnail orthumb option to resize an image to about 75% of the width of a plainthumbnail. This is useful for displaying images in"portrait" orientation, since such tall and narrow images tend to look too large when scaled to the same width as "landscape" oriented images. Theupright option scales larger or smaller in step with user screen resolution. The relative size can be determined with a multiplier such asupright=x. Ifx=1 then the image is standard thumbnail width.E.g.,[[File:Westminstpalace.jpg|thumbnail|upright|left|alt=A large clock tower and other buildings line a great river.|The "<code>upright</code>" option is about 75% of thumbnail width.]] (shown on the left) and[[File:Westminstpalace.jpg|thumb|upright=1.5|right|alt=A large clock tower and other buildings line a great river.|The "<code>upright=1.5</code>" option]] (shown on the right).
With this option, the embedded image is shown with its actual size enclosed by a frame, regardless of the "thumb" or "size" attribute, and the caption, if any, is visible in the frame. Without the optionsleft,center, andnone, the image is normally on the right:[[File:Westminstpalace.jpg|frame|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]].
With none of the options other thansizepx andalternate (caption) text, an embedded image is rendered inline.
The optionnone can be used to have thumbnails without left- or right-alignment. This is probably most useful fortables. This is an example:
| Palace of Westminster | | [[File:Westminstpalace.jpg|thumb|none|100px|alt=A large clock tower and other buildings line a great river.|From the Thames]] |
| Buckingham Palace |  | [[File:Buckingham Palace 2003.jpg|thumb|none|100px|alt=Grand city building below beautiful blue sky and clouds|Queen's home]] |
You can put links in the caption text, as demonstrated in this image:
[[File:Westminstpalace.jpg|right|thumbnail|alt=A large clock tower and other buildings line a great river.|This is the[[Palace of Westminster]] in London]]
Just make sure the number of opening and closing square brackets are right. One extra or missing would mean the entire image syntax line would not work.
Additional caption formatting options are possible; all normal formatting should just work.
[[File:Westminstpalace.jpg|right|thumbnail|alt=A large clock tower and other buildings line a great river.|<div style="text-align: center">This is<spanstyle="color: green">the</span><br/>[[Palace of Westminster]]<br/>'''in<spanstyle="color: red">London</span>'''</div>]]
List bullets and numbers can sometimes overlap left-floating images, and indented lines may not appear correctly when next to left-floating images. For example:
| Markup | Renders as |
|---|---|
|
|
| First line
|
The{{flowlist}} template enables lists to stay clear of these left-floating objects:
[[File:Westminstpalace.jpg|left|thumb|100px]]{{flowlist}}<ol><li>list item A1<ol><li>list item B1</li><li>list item B2</li></ol>continuing list item A1</li><li>list item A2</li></ol>{{endflowlist}}{{flowlist}}First line*Second line**Third line***Fourth line{{endflowlist}}
Renders as:
First line
This method will not work inside of a table, and if your list is longer than the floated element, then the list will not flow around the image like normal, but instead be one block, leaving white space below the floated element.
 | Parts of this Wikipedia page (those related to how this works with Imagemap templates?) need to beupdated. Please help update this Wikipedia page to reflect recent events or newly available information. Relevant discussion may be found on the talk page. |
In some cases, it may be desirable to add clickable annotations to an image. The templatesTemplate:Annotated image andTemplate:Annotated image 4 exist for this purpose.
These templates allowwikitext (e.g., regular text, wikilinks, allowed HTML code, references, and other templates) to be included on the image itself. They may also be used to crop an image so as to focus on a particular portion of it, or alternatively, expand the white area around an image for better placement of wikitext.
Example of an annotated diagram (usingTemplate:Annotated image) that has clickable wikilinks and overlaid text |
|  |
There is also the template{{Overlay}}:
| ||||||||||||||||
Only item 7 is linked here.
Images can be overlaid or superimposed using{{Superimpose}},{{Superimpose2}} or{{Overlaid images}}.
Images can becropped using{{CSS image crop}} or{{Annotated image}}.
After having had an image floating next to text, putting further text below it (and again using the full width) can be done with the following markup. This blocks an image from appearing next to the material following this markup. The reason for this could beaesthetic or a change in topics.
This can be issued by using template{{clear}} or{{Clr}} or{{-}} in certain namespaces (en,meta).
To displayVR photographs (aka 360-degree panoramas or photospheres), use{{PanoViewer}}.
If you don't want to show or display the image but rather just want to make a link to the description page for an image, use a leading colon before "File:" in an intra-wiki link, like this:[[:File:STS-32 crew.jpg|STS-32 crew]] which yields:STS-32 crew. Linking to a particular PDF or DjVu page using theparameter|page= is not supported, so the template{{PDF page link}} should be used instead.
Often, sound files are presented on Wikipedia pages using{{Listen}} or its related templates. However, it is also possible to present an audio file without using any template. Similar syntax to images can be used to transclude audio or video files into pages.
| Code | Output | |
|---|---|---|
| 1. | [[File:Accordion chords-01.ogg]] | |
| 2. | [[File:Accordion chords-01.ogg|frameless|upright=1.3]] |
Note that none of these examples provide links toWikipedia:Media help, and example 2 provides no navigable links to the file itself. Consequently, whenever this method is used, the{{Inline audio}} template must be shown on that page, and the presentation of the play buttons must be accompanied by clickable links to the sound file itself. Examples:
| Code | Output | |
|---|---|---|
| 1. | [[File:Accordion chords-01.ogg|frameless|upright=0.4|left]] [[:File:Accordion chords-01.ogg|Accordion chords]] | |
| 2. | [[:File:Accordion chords-01.ogg|Accordion chords]] [[File:Accordion chords-01.ogg|90px|right]] | Accordion chords |
| 3. | [[:File:Accordion chords-01.ogg|Accordion chords]] [[File:Accordion chords-01.ogg|90px]] | Accordion chords |
Note that vertical alignment of the play button does not work, nor is it possible to present the play button inline with text; consequently, the most pleasing arrangement is achieved with examples 1 or 3.
There is also a parameter to preset the player to start at a time other than 0:00.
| Code | Output | |
|---|---|---|
| 1. | [[File:Accordion chords-01.ogg|start=0:05]] |
Since June 2019, MIDI files can be played just like other sound files. See:Help:Score.
[[File:Beethoven Op. 33 no. 1.mid|thumb|[[Bagatelles, Op. 33 (Beethoven)|''Bagatelles'', Op. 33]], no. 1]]
To display a video as uploaded with a caption use[[File:First flights in aviation history.ogg|frame|none|Caption text]].
"|thumbtime=Time". Use the frame from the video at the given time as the initial still image.Time is either a number of seconds, or hours, minutes and seconds separated by colons. Without a thumbtime parameter, a frame from the midpoint of the video is used by default. For instance, using the same video file as previously:
This syntax allows you to play a segment of the video stream or set a start time. Hover over the player to see start time listed as 87s, press play and notice it stops playback at 92 seconds.
[[File:Matt Damon Takes the ALSA Ice Bucket Challenge!.webm|thumb|upright=0.75|start=87|end=92|Starts at 87 seconds and ends playback at 92 seconds]]Note: This is not yet supported by Safari and Internet Explorer.
To display a video larger than its uploaded size use "|thumb" and "|numberpx". This may be useful if the original video is very small but shows some important but small detail, but note that upscaling may create unexpected scaling artifacts. For example, the code
[[File:cal16x16check_vdnocnoafr1len2.avi.q10.ogv|inline|left]] [[File:cal16x16check_vdnocnoafr1len2.avi.q10.ogv|right|thumb|128px]]
Thethumbtime parameter can also be used inside a gallery (either with<gallery> tags or the{{Gallery}} template):
Here is the wikicode that created it:
<gallery>File:First flights in aviation history.ogg|thumbtime=21|Man in suit tie and hat at 21 seconds.File:First flights in aviation history.ogg|thumbtime=0:23|Monoplane seen at 23 seconds.</gallery>
<gallery> markup, which is slightly different from non-gallery image markuplossy parameter for tiff files