WP:ALT

Shortcuts: WP:ALT · Roovet Articles:ALT

Alternative text, commonly called alt text, is text associated with an image that communicates the image's essential information or function when the image cannot be seen. It may be read aloud by screen readers, rendered through assistive technology, displayed when an image cannot load or used by systems that process a page without relying on its visual presentation.

On Roovet Articles, editors normally provide alt text through the alt= option in MediaWiki image syntax:

[[File:Example.jpg|thumb|alt=Short description of the image|Visible caption]]

Good alt text communicates what the image contributes to the particular page. It should not merely list every visible object, repeat the filename or serve as a collection of search-engine keywords.

This guidance applies to:

• photographs;
• portraits;
• logos and seals;
• flags;
• maps;
• charts and graphs;
• diagrams;
• illustrations;
• screenshots;
• icons;
• image links;
• galleries;
• infobox images; and
• images generated or displayed through templates.

Core principle

Write the text that would preserve the image's purpose if the image were unavailable.

Ask:

1. Why is this image included?
2. What information does it add?
3. Does it perform an action or link somewhere?
4. Is the same information already stated nearby?
5. What would a reader need to know if the image were removed?

The appropriate text depends on the image's context. The same image may need different alt text on different pages.

For example, a photograph of a school may be used:

• to identify the building;
• to show its architectural design;
• to document storm damage;
• to show a historical appearance; or
• merely to decorate a school profile.

The alt text should reflect the reason the image is being used on that page.

MediaWiki image syntax

The standard syntax is:

[[File:Filename.jpg|thumb|alt=Alternative text|Caption]]

Example:

[[File:Lake Shore Middle School.jpg
|thumb
|alt=Front entrance of Lake Shore Middle School in Jacksonville
|Lake Shore Middle School on Bayview Road
]]

MediaWiki converts alt= into the HTML alternative-text attribute used by browsers and assistive technology.

Do not insert a space before or after the equals sign in the option name:

Correct:

|alt=School entrance

Incorrect:

|alt = School entrance

In some image contexts, incorrectly spaced image options may be treated as captions rather than as image options.

Alt text and captions

Alt text and captions have different purposes.

Alt text:

• is normally not visibly displayed;
• communicates the image's essential meaning or function;
• should be plain text;
• should be concise;
• should not contain citations, templates or wikilinks; and
• is intended primarily as a text replacement for the image.

A caption:

• is visible to readers;
• identifies or explains the image;
• may establish why the image is relevant;
• may contain wikilinks;
• may contain citations; and
• can provide context that does not belong in the alt text.

Example:

[[File:Government education report.jpg
|thumb
|alt=Cover of a federal education statistics report
|The 2025 edition of the ''Digest of Education Statistics''
]]

Avoid making a screen-reader user hear substantially the same sentence twice through both the alt text and the caption.

When the visible caption already provides all necessary information, the alt text can focus on information not supplied by the caption.

Types of images

Informative images

An informative image communicates a fact, concept, appearance or relationship that is not fully available in nearby text.

The alt text should convey the meaning supplied by the image rather than providing an inventory of every visual detail.

Example:

[[File:School exterior.jpg
|thumb
|alt=Two-story brick school building with a central entrance and flagpole
|The school's main building
]]

A description such as “brick building” may be sufficient in one context but inadequate in an article discussing the building's architecture.

Decorative images

A decorative image adds visual styling but does not supply information needed to understand the page.

Examples may include:

• ornamental dividers;
• background flourishes;
• repeated icons beside identical visible text;
• an image whose information is fully stated in nearby text; or
• an illustration included only for atmosphere.

Decorative images should normally use empty alt text so assistive technology can skip them:

[[File:Decorative divider.svg|20px|alt=|link=]]

The empty link= removes the image link. Before removing an image-description link, confirm that the file's licensing and attribution requirements are satisfied elsewhere.

An image that remains linked should not create a meaningless empty link for screen-reader users. When the image must stay linked, use a brief useful description rather than leaving an unhelpful link target with no accessible name.

Functional images

A functional image performs an action or serves as a link. Its alt text should describe the action or destination, not merely the icon's appearance.

Better:

[[File:Search icon.svg
|20px
|alt=Search Roovet Articles
|link=Special:Search
]]

Weaker:

|alt=Magnifying glass

Other examples include:

• Print this page;
• Open the official website;
• Download the report;
• Next page;
• Play video; and
• View a larger map.

When an icon appears inside the same link as clear visible text, an empty alt value may be appropriate because the adjacent link text already communicates the action.

Images containing text

When important words appear only inside an image, include those words in the alt text.

Example:

[[File:School motto banner.png
|alt=RISE: Resilience, Integrity, Service and Excellence
]]

When the exact text is already written immediately beside the image, repeating it in the alt text may create unnecessary duplication. In that situation, an empty value may be appropriate if the image is unlinked and contributes no additional information.

Avoid using images of text when ordinary styled text can provide the same result.

Complex images

Complex images contain more information than can be communicated effectively in one short phrase. Examples include:

• charts;
• graphs;
• maps containing substantial data;
• timelines;
• organizational diagrams;
• scientific diagrams;
• technical illustrations; and
• detailed infographics.

Complex images require two levels of explanation:

1. concise alt text identifying the image and its main purpose; and
2. a longer description in nearby prose, a list or an accessible data table.

W3C guidance recommends making the essential information from complex images available as text, rather than attempting to place every detail into one long alt attribute.

Example:

[[File:Enrollment by grade chart.png
|thumb
|alt=Bar chart comparing sixth-, seventh- and eighth-grade enrollment
|Enrollment by grade during the 2024–2025 school year
]]

The surrounding article should then state the figures:

Grade	Students
Sixth grade	229
Seventh grade	260
Eighth grade	259

The table gives nonvisual readers access to the same data and may also be more useful to readers who need exact values.

Photographs and portraits

For a portrait, identify the person when identity is the image's relevant information:

|alt=Portrait of Tony James Nelson II

A person's clothing, expression, position or surroundings should be described only when those details matter to the article.

Examples:

|alt=Tony James Nelson II speaking at a podium

|alt=Latasha Clark standing at the entrance of Lake Shore Middle School

Avoid unsupported interpretations such as:

|alt=A dishonest-looking official

Alt text must remain factual and should not introduce conclusions, diagnoses, emotions or identities that are not evident and supported.

Logos, seals and trademarks

For a logo used to identify an organization, a concise identification is usually sufficient:

|alt=Roovet logo

|alt=National Center for Education Statistics logo

Do not describe every color, letter shape and design element unless the article discusses the logo's design.

For example, an article about the history of a logo may require:

|alt=Red Roovet wordmark above a circular search symbol

A caption may separately provide the date, version or trademark information.

Flags

When a flag appears beside a visible country name, the visible text may already identify it.

Example:

[[File:Flag of the United States.svg|23x15px|border|alt=|link=]] United States

When the flag is displayed without accompanying identifying text, use:

|alt=Flag of the United States

Historical flags should identify the relevant period when necessary:

|alt=Flag of the United States used from 1777 to 1795

Templates such as Template:Flag country should avoid causing a screen reader to announce the country name twice. When the visible linked name immediately follows the icon, the flag image may be treated as decorative.

Maps

Alt text for a map should communicate what the map demonstrates.

Weak:

|alt=Map

Better:

|alt=Map showing Jacksonville in northeastern Florida

For a complex map, summarize its purpose in the alt text and explain significant boundaries, locations or patterns in nearby prose.

Example:

|alt=Map showing Duval County Public Schools middle-school attendance zones

The article should then describe the zones or provide an accessible list or table.

Do not rely exclusively on color names such as “the red area” and “the green area.” Explain what the colored areas represent.

Diagrams and illustrations

Describe the information or process communicated by the diagram.

Example:

|alt=Diagram showing NCES within the Institute of Education Sciences and the Department of Education

For a process diagram:

|alt=Five-step process from data collection through publication

When the sequence or relationships are complex, reproduce them as a numbered list or structured text near the image.

Screenshots

A screenshot's alt text should describe the interface, result or error relevant to the surrounding discussion.

Example:

|alt=NCES school-search page displaying the Lake Shore Middle School record

When the screenshot contains important error text, include the error in nearby prose or quote it directly in the article.

Do not write every menu item and interface control into the alt text unless they are all relevant.

Image galleries

MediaWiki galleries support an alt= option for each image:

<gallery>
File:School front.jpg|alt=Front entrance of the school|Main entrance
File:School library.jpg|alt=Students seated at tables in the school library|Library
File:School pool.jpg|alt=Outdoor swimming pool beside the school campus|Community pool
</gallery>

The gallery caption and alt text have separate purposes.

Each image should be considered individually. Do not reuse one generic phrase across an entire gallery unless every image genuinely communicates the same information.

Images in templates

Templates that display images should provide dedicated alt-text parameters.

Recommended pattern:

| image     = School building.jpg
| image_alt = Front entrance of the school
| caption   = Main building on Bayview Road

The template should pass the value into the actual file syntax:

[[File:{{{image}}}
|frameless
|alt={{{image_alt|}}}
]]

An image_alt parameter that is documented but never passed to alt= does not provide accessibility.

Public image templates should document:

• whether the image is informative or decorative;
• the expected alt-text parameter;
• whether the image is linked;
• how captions are handled;
• fallback behavior when alt text is omitted; and
• whether the image filename is ever exposed to assistive technology.

Infobox templates should support fields such as:

• logo_alt;
• seal_alt;
• image_alt;
• map_alt; and
• signature_alt.

Writing effective alt text

Good alt text is:

• purposeful;
• accurate;
• concise;
• specific enough for the context;
• written in plain language;
• free from unnecessary markup;
• neutral in tone; and
• limited to information the image actually communicates.

Prefer:

|alt=Students performing onstage during a school band concert

Avoid:

|alt=Image12345.jpg

Avoid:

|alt=This is a very beautiful and amazing photograph of students

Avoid keyword stuffing:

|alt=Jacksonville school Florida education best middle school students Duval

Alt text is an accessibility feature first. It should not be written as hidden promotional or search-engine text.

Length

Use the shortest text that preserves the image's important meaning.

A short phrase or sentence is usually enough for a simple image. Put extensive detail into the visible article body.

The most important information should appear early. A screen-reader user may choose to move past a long description once the image's purpose is clear.

There is no single mandatory character limit, but excessive length is a sign that the image may require a separate long description.

Words to avoid

It is normally unnecessary to begin with:

• “image of”;
• “picture of”;
• “graphic of”; or
• “photo showing”.

Assistive technology generally identifies the item as an image.

However, identifying the medium can matter when the medium itself is relevant:

• Oil painting of Frederick Douglass;
• Satellite image of Hurricane Andrew;
• Architectural rendering of the planned building; or
• Scanned newspaper advertisement from 1954.

Names and identities

Identify people, places and objects only when the identification is known and relevant.

Do not guess:

• a person's identity;
• ethnicity;
• nationality;
• gender identity;
• disability;
• medical condition;
• emotional state;
• relationship;
• political affiliation; or
• intention.

When a person's identity is uncertain, describe only what is visibly and reliably known.

Better:

|alt=A person standing beside the school entrance

Not:

|alt=The school's principal

unless the person is reliably identified as the principal.

Color

Mention color when it contributes meaning.

Appropriate:

|alt=Map showing evacuation areas in red and shelter locations in blue

The accompanying text should also explain the categories without requiring readers to distinguish color alone.

Unnecessary:

|alt=Red, blue and gray logo

when the image's only purpose is to identify the organization.

Common mistakes

Repeating the caption

Problem:

|alt=Lake Shore Middle School
|Lake Shore Middle School

Better:

|alt=Front entrance of the two-story school building
|Lake Shore Middle School

Using the filename

Problem:

|alt=IMG_8493-final-v2.jpg

The filename rarely communicates meaningful information.

Leaving informative images undescribed

Problem:

[[File:Enrollment chart.png|thumb|Enrollment by grade]]

Better:

[[File:Enrollment chart.png
|thumb
|alt=Enrollment is lowest in sixth grade and highest in seventh grade
|Enrollment by grade
]]

The exact figures should still be provided in visible text or a table.

Overdescribing decorative details

Problem:

|alt=A thin curved dark red decorative line with a shadow

If the line is decorative, use an empty alt value and, when appropriate, remove its link.

Describing appearance instead of function

Problem:

|alt=Black printer icon

Better:

|alt=Print this page

Adding claims that cannot be cited

Alt text cannot contain inline citations. Do not use it to introduce disputed, promotional or interpretive claims.

Problem:

|alt=The most successful middle school in Jacksonville

Better:

|alt=Students entering Lake Shore Middle School

Reviewing an article

When reviewing an article's images:

1. Identify every image, icon, chart, logo and map.
2. Determine whether each is informative, functional, decorative or complex.
3. Check whether an alt= option is present.
4. Confirm that the text reflects the image's purpose on that page.
5. Remove repeated information already supplied by the caption.
6. Confirm that linked images have meaningful accessible names.
7. Supply a long description for complex graphics.
8. Check image parameters passed through templates.
9. Preview the result.
10. Inspect mobile and desktop rendering.
11. Confirm that important information does not depend on color alone.
12. Check that alt text contains no wiki markup, citations or promotional keywords.

Template-author requirements

Templates that display media should:

• expose an alt-text parameter;
• pass the parameter to MediaWiki's alt= option;
• avoid using filenames as accessible labels;
• use empty alt text for truly decorative, unlinked images;
• ensure functional images describe their action;
• avoid duplicating nearby visible text;
• preserve alternative text through nested templates;
• document all image parameters;
• provide sensible examples;
• support long descriptions outside the image when needed; and
• be tested with a screen reader or accessibility inspection tool when practical.

A template should not silently discard an article editor's supplied alt text.

Relationship to captions and article prose

Alternative text is one part of an accessible image presentation.

A complete presentation may include:

• concise alt text;
• a visible caption;
• explanatory prose;
• a table containing chart data;
• a list describing diagram steps;
• a linked file-description page; and
• image licensing and attribution information.

Do not force every part into the alt= field.

SEO and machine processing

Alternative text may help systems understand an image, but editors should not write it primarily for search rankings.

Alt text must not contain:

• unrelated keywords;
• repeated article titles;
• promotional slogans;
• hidden advertising;
• fabricated descriptions; or
• information not supported by the image and article.

Useful, accurate accessibility text is also more useful to search and indexing systems than keyword-filled text.

Enforcement and maintenance

Missing or inadequate alt text should ordinarily be corrected rather than used as a reason to remove an otherwise appropriate image.

High-use templates that cannot accept alt text should be upgraded.

Editors making large-scale changes should:

• preserve existing accurate descriptions;
• avoid replacing specific descriptions with generic text;
• review image context rather than applying one phrase automatically;
• test templates before deployment;
• monitor pages affected by template changes; and
• follow the Roovet Articles:Quality policy.

Quick decision guide

Does the image provide information not available nearby?

Write concise alt text communicating that information.

Does the image perform an action or link somewhere?

Describe the action or destination.

Is the image complex?

Write brief alt text and provide a longer visible description.

Is all of the image's information already stated nearby?

Consider empty alt text if the image is unlinked and genuinely redundant.

Is the image purely decorative?

Use empty alt text and, where licensing permits, remove the link.

Does the image contain important words?

Include those words or provide them in nearby visible text.

Are you unsure?

Describe why the image matters to the page rather than attempting to describe every visible detail.

See also

• Help:Images
• Help:Template
• Help:Transclusion
• Roovet Articles:Quality policy
• Template:Infobox
• Template:Infobox school
• Template:Infobox government agency
• Template:Flag country

External links

• W3C Images Tutorial
• W3C alt decision tree
• W3C informative images guidance
• W3C decorative images guidance
• W3C complex images guidance
• MediaWiki image help