Wikipedia:Extended image syntax

This page documents an English Wikipedia editing guideline. It is a generally accepted standard that editors should attempt to follow, though it is best treated with common sense, and occasional exceptions may apply. Any substantive edit to this page should reflect consensus. When in doubt, discuss first on the talk page.

Shortcut: WP:EIS

In brief, the syntax for displaying an image is (see Multimedia syntax below for extra syntax for sound and multimedia files):

[[File:Name|Type|Border|Location|Alignment|Size|link=Link|alt=Alt|Caption]]

Only Name is required. Most images should use "[[Image:Name|thumb|alt=Alt|Caption]]" and should not specify a size. The other details are optional and can be placed in any order.

Type 

"thumb" (or "thumbnail"; either can be followed by "=filename"), "frame" (or "framed"), or "frameless". Display the image with specific formatting (see below).

Border 

"border". Put a small border around the image.

Location 

"right", "left", "center" or "none". Determine the horizontal placement of the image on the page. This defaults to "right" for thumbnails.

Alignment 

"baseline", "middle", "sub", "super", "text-top", "text-bottom", "top", or "bottom". Vertically align the image with respect to adjacent text. This defaults to "middle".

Size 

"Widthpx" or "xHeightpx" or "WidthxHeightpx" or "upright" or "upright=Factor". Scale the image to be no greater than the given width and/or height, keeping its aspect ratio. With "upright", scale a thumbnail from its default size by the given factor (default 0.75), rounding the result to the nearest multiple of 10 pixels. Size is disabled when the image is 'framed'.

Link 

Link the image to a different resource, or to nothing. Must not be set for non-public domain images unless attribution is provided in some other fashion.

Alt 

Specify the alt text for the image. This is intended for visually impaired readers. See WP:ALT for how this typically should differ from the caption.

Caption 

Specify the image's caption.

It does not matter whether the file is from Wikimedia Commons or on Wikipedia; the same syntax is used.

Detailed syntax

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 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 "=".

Type

Zero or one of these options may be specified to control whether or not the image is scaled down and given a border.

thumb 

(Or thumbnail.) Scale the image down, and put a box around the image. Show any caption below the image. Place the image on the right unless overridden with the location attribute. If no image size is specified, use a per-user preference for logged-in users (see "Thumbnail size" under Special:Preferences/Appearance/Files), defaulting to 220 pixels for non-logged-in users. With an operand, e.g., "thumb=Example.png", the operand names an image that is used as the thumbnail, ignoring any size specification.

Thumbnailing animated GIFs is not supported. Thumbnailing an animated GIF does not result in an error, so there is no warning, but the animated GIF is not processed. Instead the original animated GIF is shipped, and whether the animated GIF is subsequently scaled to fit the allotted space is down to the capabilities of the receiving browser.

frame 

Preserve the original image size, and put a box around the image. Show any caption below the image. Sizing does not work when "frame" is used.

(nothing specified) 

Preserve the original image size, and do not add a border around the image. Do not show a caption. If no alt text is specifically requested, use the requested caption as alt text.

frameless 

Like "thumb", but omit the visible caption and the box around the image. Another way to put it is that this is like specifying no type, except that the default size is that of a thumbnail and the "upright" option works.

Border

border 

Generate a one-pixel border around the image. This has an effect only around unframed images, as framed images always have borders.

Location

Zero or one of these options may be specified to control the position of the image.

right 

Place the image on the right side of the page. The article text that follows the image flows around the image. This is the default.

left 

Place the image on the left side of the page. The article text that follows the image flows around the image.

center 

Place the image in the center of the page. The article text that follows the image is placed below the image.

none 

Place the image on the left side of the page. The article text that follows the image is placed below the image.

Vertical alignment

Zero or one of these options may be specified to control the vertical alignment of the image with respect to adjacent text. These options apply only to plain images, which do not cause breaks and are not floated. In the following list, each option's explanation is preceded by what Image:Flag of Hungary vertical.svg looks like when aligned with that option, using the markup:

[[Image:Flag of Hungary vertical.svg|option|7px|link=|alt=]]

baseline

Align the bottom of the image with the baseline of the text.

middle

(This is the default.) Align the vertical middle of the image with the baseline of the text plus half the x-height of the text, so that the image is vertically centered around a lower case "x" in 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 "X₂".

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 "X²".

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 of ascenders 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 of descenders 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.

Size

Zero or one 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 a 'frame' is used.

Widthpx 

(E.g., "100px".) Scale the image to make it the specified number of pixels in width, and scale the height to retain the original aspect ratio.

xHeightpx 

(E.g., "x150px".) Scale the image to make it the specified number of pixels in height, and scale the width to retain the original aspect ratio.

WidthxHeightpx 

(E.g., "100x150px".) Scale the image to be no wider and no higher than the specified number of pixels. The image will keep its original aspect ratio.

(nothing specified) 

For thumbnails, use the size specified in preferences for logged in users, and use a size determined by resolution for anonymous users. For non-thumbnails, use the native size of the image.

upright 

Scale a thumbnail image to 75% of normal thumbnail width, rounding the result to the nearest multiple of 10 pixels.

upright=Factor 

Adjust a thumbnail's size to Factor times the default thumbnail size, rounding the result to the nearest multiple of 10. For instance, "upright=1.5" makes the image larger, which is useful for maps or schematics that need to be larger to be readable. The parameter "upright=1" returns the same size as thumbnail width, and "upright=0.75" is functionally identical to "upright" alone.

The "upright" option must be used along with the "thumb" parameter.

Resizing animated GIFs is not supported. Resizing an animated GIF does not result in an error, so there is no warning, but the animated GIF is not processed. Instead the original animated GIF is shipped, and whether the animated GIF is subsequently scaled to fit the allotted space is down to the capabilities of the receiving browser.

Link

Ordinarily, an image acts as a hypertext link to the image description page, a page with information about the image itself. Using the link option allows an image to act as a hypertext link to a different page. See Wikipedia:Images linking to articles for more information.

link=Page 

The image acts as a hypertext link to the specified page. Do not enclose the page name in square brackets. If Page is a URL, the image acts as an external link; otherwise it links to the named Wikipedia page.

link= 

No hyperlink is created. Clicking on the image will have no action.

The "link" parameter cannot be used in conjunction with "thumb", as "thumb" is always meant to link to the larger version of the image. In addition, "link" cannot be used with "frame".

File:Example.svg‎ rendered as a thumbnail above; Media:Example.svg‎ is the direct link

One may wish to link directly to the image file without displaying any thumbnail or preview image at all, possibly useful for downloading or viewing directly with a compatible browser. The example SVG at the right contains [[Media:Example.svg‎]] as such a virtual Media: link in its caption.

Alt text and caption

Zero or more of these options may be specified to control the alt text, link title, and caption for the image. Captions may contain embedded wiki markup, such as links or formatting. See Wikipedia:Captions for discussion of appropriate caption text. See Wikipedia:Alternative text for images for discussion of appropriate alt text. Internet Explorer displays the link title as a tooltip but other browsers may not.

alt=Alt 

Use Alt as the alt text for the image.

Caption

(any text that is not recognised as some other part of the image syntax): How this text is used depends on the image type. When the type has a visible caption ("thumbnail", "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 explicit alt=Alt has not been supplied.

The actual alt text for the displayed image will be one of the following, in order of preference:

1. The explicitly requested Alt, if any;
2. The explicitly requested Caption, if the image type has no visible caption;
3. The empty string, if there is an explicitly requested Caption and the image type has a visible caption.
4. The image file name if there is no explicitly requested Alt or Caption. This is never a satisfactory option.

It is only possible to specify the link title text 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.

How to display an image in uploaded size, with a caption

To display an image as uploaded with a caption use [[Image:Westminstpalace.jpg|frame|none|alt=alt text|caption text]].

caption text

How to display an image with no caption or formatting

The old syntax for images without captions is [[Image:Westminstpalace.jpg|alt text]]. This is rendered inline, and the specified text is used as the image's alt attribute (alternate text for programs which cannot display images, such as screen readers) and as the title attribute (supplementary text, often displayed as a tool tip when the mouse is over the image).

See Wikipedia:Image markup with HTML for an old, deprecated, way of putting a caption under the image using HTML code. Please use the new way of associating captions with images, as described on this page.

See Wikipedia:Captions for discussion of appropriate caption text. See Wikipedia:Alternative text for images for discussion of appropriate alt text.

Example

New syntax for images

The Palace of Westminster

The new syntax is backward compatible, so articles don't have to be changed.

In the syntax [[Image:filename|options]] (e.g., [[Image:Westminstpalace.jpg|thumb|100px|left|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]] shown in the left), several options can be set when including an image. Those affect the placing of the image, its size or the way the image will be presented. The options are right, left, center, none, sizepx, thumbnail (thumb), frame, and alternate (caption) text.

From the Thames

• The options can be combined, and vertical bars ("|") are used to separate options from each other.
• Do not put spaces around the vertical bars for readability – options will not be interpreted correctly.
• The options can be put in any order.
• An unknown option is taken as the caption text, but this will appear only if thumbnail or frame are specified.
• If there are two or more unknown options, the last one upstages the rest: [[Image:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster|200px|right|From the Thames]] (shown on the right).
  

Here is the description of the options other than the caption text:

right

The image is right-aligned, and text floats to the left of the image: [[Image:Westminstpalace.jpg|right|70px|alt=A large clock tower and other buildings line a great river.]] (shown on the right).

left

The image is left aligned, and text floats to the right of the image: [[Image:Westminstpalace.jpg|left|70px|alt=A large clock tower and other buildings line a great river.]] (shown on the left).

center

The image is centered, and...

the text following the image starts below it: [[Image:Westminstpalace.jpg|center|70px|alt=A large clock tower and other buildings line a great river.]] (shown above).

none

The image is put at the left, and...

the text following does not float to the right (or to the left, obviously), and starts below it: [[Image:Westminstpalace.jpg|none|70px|alt=A large clock tower and other buildings line a great river.]] (shown above).

Notes:

The above four options are incompatible. When used combined, the first one overrides the rest: [[Image:Westminstpalace.jpg|center|left|none|right|70px|alt=A large clock tower and other buildings line a great river.]] (shown in the center).

What is between the last vertical bar and the closing brackets ("]]"), void or not, is taken as the last option, and works as usual. For instance, when the last option is right, the image is right-aligned, and text floats to the left: [[Image:Westminstpalace.jpg|70px|alt=A large clock tower and other buildings line a great river.|right]] (shown on the right).

This text is displayed.

In particular, if the last option is the void text (that is, if there is nothing between the last vertical bar and the closing brackets), the caption is not displayed: [[Image:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|This text is not displayed.|70px|left|]] (shown on the left) and [[Image:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|This text is displayed.|70px|right]] (shown on the right).

sizepx 

This option renders a version of the image that's [size] pixels wide (e.g., [[Image:Westminstpalace.jpg|right|50px|alt=A large clock tower and other buildings line a great river.]] shown on the right). Height is computed to keep (i.e. the shape of the image)

Notes:

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. By 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. Animated GIFs are not processed by the server. When a smaller size is specified the original full sized animated GIF is served. Whether the animated GIF is subsequently scaled to fit the allotted space is down to the capabilities of the receiving browser. Resizing an animated GIF will significantly reduce its quality, without any reduction of download time.

From MediaWiki 1.5 the default thumbnail width can be set in the preferences, so it is recommended not to specify "px", in order to respect the users' preferences (unless, for a special reason, a specific size is required regardless of preferences, or a size is specified outside the range of widths 120–300px that can be set in the preferences).

If you specify a "frame" option the image will not be scaled, and no size specifiers will be in the HTML. The image will be rendered at full size

When there are two or more "size" options, only the last one is valid: [[Image:Westminstpalace.jpg|right|50px|80px|alt=A large clock tower and other buildings line a great river.]] (shown on the right).

thumbnail, thumb 

The Palace of Westminster

The thumbnail (thumb) option generates a image. It is automatically resized when the "size" attribute is not specified. Without the options left, center, and none, the image is normally on the right. If the image has a caption text, it is displayed in the lower margin. E.g., [[Image:Westminstpalace.jpg|thumbnail|left|100px|alt=A large clock tower and other buildings line a great river.]] (shown on the left) and [[Image:Westminstpalace.jpg|thumb|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]] (shown on the right). Note: thumbnail (thumb) cannot be used in lists.

This is a globe, and take a look at it in the actual size.

An "enlarge"-icon is put also in the lower margin of the thumbnail. Both the image itself and the icon link to the image description page with the image in its actual size. The icon shows the link title "Enlarge" in its hoverbox, even in cases where this term does not apply, because it leads from the enlarged image to the one with the actual size. E.g., [[Image:tst.png|right|thumb|100px|alt=tiny globe|This is a globe, and take a look at it in [[Media:tst.png|the actual size]].]] (shown on the right).

upright 

The "upright" option is about 75% of thumbnail width.

The "upright=1.5" option

The upright option works in combination with the thumbnail or thumb option to resize an image to about 75% of the width of a plain thumbnail. The upright option scales larger or smaller in step with user screen resolution. The relative size can be determined with a multiplier such as upright=x. If x=1 then the image is standard thumbnail width. E.g., [[Image: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 [[Image: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).

frame 

The Palace of Westminster

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 options left, center, and none, the image is normally on the right: [[Image:Westminstpalace.jpg|frame|thumbnail|50px|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]].

With none of the options other than sizepx and alternate (caption) text, an embedded image is rendered inline.

text text text text text text
[[Image:Westminstpalace.jpg|150px|alt=A large clock tower and other buildings line a great river.|The Palace of Westminster]]
text text text text text
[[Image:tst.png|100px|alt=tiny globe|This is a globe.]]
text text text text

gives

text text text text text text text text text text text text text text text

The option none can be used to have thumbnails without left- or right-alignment. This is probably most useful for tables. This is an example:

How to use none
London's palaces
Palace of Westminster	From the Thames	[[Image:Westminstpalace.jpg|thumb|none|100px|alt=A large clock tower and other buildings line a great river.|From the Thames]]
Buckingham Palace	Queen's home	[[Image:Buckingham palace Copyright2003KaihsuTai.jpg|thumb|none|100px|alt=grand city building below beautiful blue sky and clouds|Queen's home]]

Thumbnail with caption text underneath that has one or more links

From MediaWiki 1.3, it is also possible to include links in the caption text, e.g.:

[[Image:Westminstpalace.jpg|right|thumbnail|alt=A large clock tower and other buildings line a great river.|This is the [[Palace of Westminster]] in London]]

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

Additional caption formatting options are possible.

[[Image:Westminstpalace.jpg|right|thumbnail|alt=A large clock tower and other buildings line a great river.|<div align="center">This is <span style="color: green">the </span><br /> [[Palace of Westminster]]<br /> '''in <span style="color: red">London</span>'''</div>]]

This is the
Palace of Westminster
in London

All of the normal text formatting options work.

Overlaying annotations on an image

Spine

Dorsal

Upper lateral

Lower lateral

Ventro-lateral

       = Frontal

An example of a diagram with clickable links and overlaid text

In some cases, it may be desirable to add clickable annotations to an image. The template Template:Annotated image exists for this purpose.

Compatibility considerations

The floating options left, center, and right explained above are supported by modern browsers, but don't work with older browsers. If necessary it's simple to get a floating effect also for old browsers:

{| align="right"
| [[Image:Westminstpalace.jpg|160px|alt=A large clock tower and other buildings line a great river.|Example]]
|}

This code is not intended for general use, however. There are few, if any, instances where support for such legacy browsers is necessary.

Cancelling floating-around-image mode

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, possibly due to aesthetic reasons or a change in topics.

<br style="clear:both" />

For legacy align="right" (etc.) floating this isn't good enough; legacy browsers would ignore inline CSS. To cancel floating under all conditions the following markup (valid XHTML 1.0 transitional) works:

<br clear="all" />

The same code can be issued by using template {{clear}} or {{Clr}} or {{-}} in certain namespaces (En, meta).

Linking to the image description page

If you want to make a link to the description page for an image, use a leading colon before "Image:" in an intra-wiki link, like this: [[:Image:STS-32 crew.jpg|STS-32 crew]] which yields: STS-32 crew

Images that link somewhere other than the image description page

It is possible to make an image that links to a different page instead of to the image description page by using the "|link=" option. To disable the link altogether and have a purely decorative image, in the sense that the image is not shown to visually impaired readers, use "|link=|alt=", with no arguments for either parameter.

Multimedia syntax

The extended syntax, in addition to yet more syntax, can also be applied to sound and video files. In these examples, File:, the namespace equivalent to Image, is used. Either namespace can be used.

Sound files (Ogg)

File description icon 

"noicon". Do not display the icon that links to the sound file description page.

Normally, sound files in Ogg format are presented on Wikipedia pages using the Template:Listen or its related templates. However, it is also possible to present an audio file without any template.

	Code	Output
1.	[[File:Accordian chords-01.ogg]]
2.	[[File:Accordian chords-01.ogg|noicon]]
3.	[[File:Accordian chords-01.ogg|noicon|90px]]

Note that none of these examples provide links to Wikipedia:Media help, and examples 2 and 3 provide no navigable links to the files themselves. Thus, whenever this method is used, the Template:Inline audio 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:Accordian chords-01.ogg|90px|noicon|left]] [[:File:Accordian chords-01.ogg|Accordion chords]]	Accordion chords
2.	[[:File:Accordian chords-01.ogg|Accordion chords]] [[File:Accordian chords-01.ogg|90px|noicon|right]]	Accordion chords
3.	[[:File:Accordian chords-01.ogg|Accordion chords]] [[File:Accordian chords-01.ogg|90px|noicon]]	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.

Sound files (MIDI)

Media:K520.mid

Video files (Ogg)

To display a video as uploaded with a caption use [[File:First flights in aviation history.ogg|frame|none|alt=alt text|caption text]].

caption text

More syntax for videos

Initial still image 

"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 above:

Man in suit tie and hat at 21 seconds. Time syntax using seconds only: "21"

Monoplane seen at 23 seconds. Time syntax using minutes and seconds: "0:23"

Landed biplane seen at 33 seconds. Time syntax using hours, minutes and seconds: "0:0:33"

Displaying small videos larger

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]]

displays the 16-pixel wide video at its original size on the left and eight times wider at the right (the squares should be all black or all white and the edges should be sharp - any blurriness or off-white colour is likely due to the browser or the wikimedia server rendering):

Thumbtime in a gallery

Until mediawiki handles the thumbtime parameter inside a gallery (as of 2010-01-24 mediawiki ignored the parameter inside <gallery> tags, {{Gallery}} or {{Image gallery}}), you need to manually write a gallery if you wish to use it. The following shows how mediawiki handles thumbtime in galleries (please update this help when it changes):

thumbtime=21|Man in suit tie and hat at 21 seconds.

thumbtime=0:23|Monoplane seen at 23 seconds.

Here is an example pseudo gallery that obeys thumbtime followed by the wikicode that created it.

Man in suit tie and hat at 21 seconds	From the Thames
Queen's home	Monoplane seen at 23 seconds

{| class="wikitable"
| [[File:First flights in aviation history.ogg|thumb|thumbtime=21|alt=Man in suit, tie and hat|Man in suit tie and hat at 21 seconds]]
| [[File:Westminstpalace.jpg|thumb|none|alt=A large clock tower and other buildings line a great river.|From the Thames]]
|-
| [[File:Buckingham palace Copyright2003KaihsuTai.jpg|thumb|none|alt=grand city building below beautiful blue sky and clouds|Queen's home]]
| [[File:First flights in aviation history.ogg|thumb|thumbtime=0:23|alt=Monoplane|Monoplane seen at 23 seconds]]
|}

See also

• Wikipedia:Images for an overview of images in Wikipedia
• Wikipedia:Picture tutorial
• Wikimedia Commons (Commons Main Page), a free multimedia repository, that you can use directly in Wikipedia and the other Wikimedia projects. You can upload new images or use the stored ones.
• Commons:Video, outline of videos on Commons; using, playing, policy, finding, converting and uploading
• Wikipedia:Creation and usage of media files, a how-to guide, old but still useful
• Wikipedia:Image use policy
• Wikipedia:Finding images tutorial
• meta:Help:Images and other uploaded files