Image Gallery: Ordering, Captions and Mobile Rules

An image gallery groups multiple related still images into one ordered editorial unit. The sequence is part of the meaning: a reader should understand why these images belong together, what each one contributes, and whether moving from item 1 to item 2 represents time, priority, viewpoint, or simple browsing order.

This example uses an editorial grid because all three views are equally important and fit without hiding an item. The order moves from identification to two condition checks. The captions state what each view proves; they do not merely repeat “connector image.”

Why this element matters

People inspect a set differently from a pile. A visible boundary and deliberate sequence tell a reader that the images answer one larger question together. The overview creates orientation, then the detail images reduce uncertainty. That progression prevents the reader from opening unrelated images, remembering their positions, and constructing the relationship alone.

Ordering controls expectations. A chronological set promises change; a product set promises overview, scale, features, variants, and condition. Filename or upload order can make important evidence look secondary or imply a narrative that does not exist.

Machine extractability is the ability of software to isolate the gallery without losing the relationship among its images. A machine can identify separate image files, but it cannot safely infer whether they are alternatives, steps, evidence, or decoration. A gallery title, declared ordering logic, stable item positions, individual alt text, and visible captions provide that relationship in text. The same fields can feed search indexing, content inventories, accessibility checks, and structured data without relying on computer vision.

The shared element writing rules govern typed-element precedence, portable directives, and body mapping. This page takes precedence for image-gallery-specific item limits, ordering, captions, and mobile behavior. Do not imitate a gallery with loose images or a generic slider when this element’s purpose applies.

When to use it

Use an image gallery when two or more images are peers that answer one question better together than separately. Each image must add a distinct view, state, stage, detail, or example. Strong cases include product views, before-and-after evidence, a short process sequence, location orientation, a design portfolio, or several details supporting one review conclusion.

Apply the removal test to each item. If removing an image changes nothing the reader can decide, verify, or understand, remove it from the set. A gallery is not a storage surface for every available asset.

Near misses need different elements:

• Use a single figure or imagebox when one image carries the point and the prose interprets it.
• Use an annotated screenshot when readers must locate several controls inside one interface image. Do not split one screen into a gallery of unexplained crops.
• Use a comparison table when the reader must compare repeated attributes across many options. Images may support the decision, but they cannot replace textual criteria.
• Use a step list when actions are the primary content. A gallery can show resulting states, but it must not turn required instructions into captions.
• Use a product slider when each card has price, availability, rating, and an action. A gallery contains images, not purchasable entities.
• Use separate figures when the images support different sections and share no meaningful sequence.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the gallery immediately after the paragraph that states the question the set will answer. A product-condition gallery follows the condition claim; a case-study sequence follows the intervention; a location gallery follows arrival information.

Keep the gallery title, optional introduction, all items, captions, credits, and controls in one semantic container. Do not insert prose, an advertisement, a call to action, or a page break between items. Follow the gallery with the interpretation or next decision when the captions do not carry it completely.

A gallery may not sit directly beside another gallery, video, large table, full-width chart, imagebox, or unrelated call to action. Add explanatory prose between dense visual units or combine genuine peers.

Do not put a gallery inside a step, list item, callout, table cell, accordion, clickable card, or another gallery. Never split a claim from its source or a warning from the action it limits. Reserve the first viewport for the direct answer unless the images are the answer.

Anatomy

The anatomy is semantic. Grid columns, thumbnail sizes, shadows, corner radii, and animation belong to the renderer rather than the content model.

1. Gallery container: Groups the title, description, items, and controls under one accessible name.
2. Gallery title: States the shared subject or question in 3–10 words.
3. Introduction: Optionally explains the sequence or inspection task in one sentence.
4. Ordered item: Preserves stable source order regardless of the desktop layout.
5. Image: Uses an existing, rights-cleared asset with intrinsic width and height.
6. Alternative text: Describes that image’s purpose in the set rather than copying its caption.
7. Caption: Identifies the view and explains its distinct contribution.
8. Credit: Provides creator, source, or license information when required.
9. Controls: For an interactive gallery, visible buttons support pointer, keyboard, switch, and touch input.
10. Position indicator: Announces “2 of 5” in text when some items are hidden from view.
11. Mobile order: Matches DOM order, numbering, keyboard order, and the intended narrative.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Choose the least interactive variant that preserves the relationship. Every variant keeps complete captions available in text and uses the same source order at every breakpoint.

Editorial grid

Use a grid for 2–6 equally weighted images that can appear together. Desktop may use two or three columns. Mobile collapses to one column; it never shrinks three images into unreadable thumbnails.

Sequential strip

Use a strip for 3–8 images with an explicit chronological or spatial progression. On narrow screens it may become a horizontally scrollable region only when visible controls, a position indicator, keyboard operation, and a stacked non-JavaScript fallback exist. Never make swipe the sole means of navigation.

Comparison pair

Use exactly two images for before-and-after, original-and-revised, or two viewpoints that must be judged together. Use persistent text labels, not color or position alone. Mobile stacks item 1 before item 2 and repeats the labels beside the images.

Primary image with detail views

Use this for 3–12 product or artifact views when one overview anchors the set and the remaining images answer distinct inspection questions. Selecting a thumbnail must update the primary image’s alt text, caption, position, and announced state. Every image remains reachable without JavaScript.

Mobile stacked default

Use the stacked list whenever interactivity would not materially improve comprehension. It is the default for editorial content because all items and captions remain visible, linkable, printable, and readable without gestures.

Parameters

The contract stores editorial meaning and asset metadata. Layout tokens, column widths, gaps, control icons, transition duration, and breakpoints belong to the renderer.

Captions are required for evidence, meaning-changing order, comparison labels, and visible rights information. A product angle may omit one only when its alt text and context distinguish the view. mobile=scroll is valid only for strip or primary-details with the required controls.

Syntax and code examples

All mappings preserve the same title, order, item fields, and fallback. Production must reject example paths until the files exist.

Portable Markdown directive

:::image-gallery{layout=grid mobile=stack orderedBy=viewpoint}
## Three views that establish product condition

:::gallery-item{src="/cdn-assets/examples/connector-overview.webp" alt="Complete black industrial connector on a neutral surface, oriented with its locking tab facing upward" width=1600 height=1200}
**1. Overview.** The complete connector establishes shape, scale, and orientation.
:::

:::gallery-item{src="/cdn-assets/examples/connector-lock.webp" alt="Close view of the connector showing an intact raised locking tab with no visible crack" width=1600 height=1200}
**2. Locking tab.** The close view confirms that the retention clip is intact.
:::
:::

The first heading becomes title; each item body becomes its caption. Source order is canonical, so masonry may not reorder items to fill gaps.

Hugo shortcode mapping

{{< image-gallery layout="grid" mobile="stack" orderedBy="viewpoint" >}}
## Three views that establish product condition

{{< gallery-item src="/cdn-assets/examples/connector-overview.webp" alt="Complete black industrial connector on a neutral surface, oriented with its locking tab facing upward" width="1600" height="1200" >}}
**1. Overview.** The complete connector establishes shape, scale, and orientation.
{{< /gallery-item >}}

{{< gallery-item src="/cdn-assets/examples/connector-lock.webp" alt="Close view of the connector showing an intact raised locking tab with no visible crack" width="1600" height="1200" >}}
**2. Locking tab.** The close view confirms that the retention clip is intact.
{{< /gallery-item >}}
{{< /image-gallery >}}

This adapter specification is not a registered shortcode. Until approval, use semantic figures in source order and do not reference missing assets.

WordPress block

<!-- wp:amicited/image-gallery {"layout":"grid","mobile":"stack","orderedBy":"viewpoint"} -->
<section aria-labelledby="condition-gallery">
  <h2 id="condition-gallery">Three views that establish product condition</h2>
  <ol>
    <li><figure><img src="connector-overview.webp" width="1600" height="1200" alt="Complete black industrial connector on a neutral surface, oriented with its locking tab facing upward"><figcaption><strong>Overview.</strong> The complete connector establishes shape, scale, and orientation.</figcaption></figure></li>
    <li><figure><img src="connector-lock.webp" width="1600" height="1200" alt="Close view of the connector showing an intact raised locking tab with no visible crack"><figcaption><strong>Locking tab.</strong> The close view confirms that the retention clip is intact.</figcaption></figure></li>
  </ol>
</section>
<!-- /wp:amicited/image-gallery -->

A WordPress implementation may use a native Gallery block only if it preserves per-item alt text, captions, intrinsic dimensions, source order, and the accessible group name. Styling a sequence of background images does not meet the contract.

Examples

Good: every view resolves a different uncertainty

Used equipment condition — inspection order

1. Full unit: Establishes identity and shows that the casing is complete.
2. Serial plate: Confirms the exact model and rated voltage in readable focus.
3. Power connector: Shows straight pins and an intact locking tab.
4. Wear surface: Shows the deepest visible scratch beside a ruler for scale.

This follows the buyer’s inspection logic. Each caption is verifiable, the ruler prevents a close-up from exaggerating damage, and the mobile stack preserves order.

Bad: a carousel used as an asset dump

Our latest event
Twelve near-identical stage photographs, no captions, auto-advancing every four seconds. Navigation appears only on hover. The mobile version shows a cropped center slice and accepts swipe gestures only.

Neither membership nor order has a reason. Twelve filenames convey nothing to a screen reader; auto-advance prevents inspection; hover-only controls exclude keyboard and touch users; swipe-only navigation hides access; and the crop can remove the subject. Select the few frames that tell a defined story, write distinct alternatives and captions, stop automatic motion, and default to a mobile stack.

Schema markup and accessibility

A gallery does not automatically earn special search treatment. Mark up only relationships that the visible page and assets support. Meaningful images can map to ImageObject with stable contentUrl, caption, creator or credit text, license information, and representative status when those facts are known. An explicitly ordered gallery can map to ItemList, using position values that match source order. Product views may populate the parent Product.image property. Do not create entities for decorative images, invent licenses, or claim every image is representative.

Use native <img> elements inside <figure> elements with visible <figcaption> where required. Name the section through its heading. Preserve ordered relationships with <ol> or equivalent position semantics; visual placement never overrides DOM order.

Alternative text describes the purpose of each image in this set. It should not start with “image of,” repeat the caption verbatim, or describe details irrelevant to the decision. Two photographs of the same object require different alt text because each has a different purpose. Use alt="" only when an image is truly redundant and removing it would not remove evidence.

Interactive variants need named previous and next buttons, keyboard activation, a text position indicator, and a status announcement after changes. Auto-advance is prohibited. Keep focus on the activated control, and preserve content without JavaScript, at 200% zoom, and with reduced motion.

Writing rules

Every gallery answers one shared question. State why it exists, then order by narrative, chronology, priority, viewpoint, or comparison—never upload order.

• Use 2–8 items for a normal gallery; use exactly 2 for a comparison and 3–12 for a primary product/detail set.
• Write titles in 3–10 words and optional introductions in one sentence of 8–30 words.
• Keep captions to 5–30 words. Begin with the view, state, or item label when that improves scanning, then explain its contribution.
• Use parallel caption structure across the set. If the first starts with a state label, the others should too.
• Keep alternative text focused on what a non-visual reader needs from that specific frame; target 40–180 characters and never exceed 250.
• Maintain a factual, observational tone. State “the seal sits flush” rather than “the amazing seal looks perfect.”
• Identify time, scale, crop, state, and source whenever they constrain interpretation.
• Use the same comparison conditions when appearance is evidence: equivalent crop, angle, scale, lighting, and color treatment.

Never put a heading, paragraph, table, list of instructions, call to action, form, price, rating, testimonial, expandable disclosure, video, audio player, or product card inside an item caption. Never bake captions into pixels, make color the only label, conceal material defects through cropping, expose customer data, or publish an image without confirmed usage rights.

Post types that use it

The rows below mirror the postTypes frontmatter. Inclusion means the post type can use a gallery when the images form a real set; it does not make the element mandatory on every page.

QA checklist

• The title states one shared question or subject, and every image contributes a distinct answer.
• The item count matches the selected variant and contains no redundant frame.
• orderedBy records a defensible narrative, chronology, priority, viewpoint, or comparison order.
• Source, visual, keyboard, screen-reader, numbering, and mobile orders all match.
• Every src resolves to an existing, rights-cleared still image before publication.
• Every image has intrinsic width and height, an intentional alt value, and a meaningful crop.
• Evidence, comparisons, and ordered items have concise visible captions with parallel structure.
• Credits and license links are visible and accurate where required.
• Comparison images use equivalent scale, angle, crop, lighting, and labels unless a difference is disclosed.
• Mobile uses a readable stacked fallback or complete accessible controls; swipe is never the only input.
• Interactive variants have visible previous and next buttons, a text position indicator, keyboard support, and no auto-advance.
• The gallery works without JavaScript and at 200% zoom, respects reduced motion, and does not create horizontal page overflow.
• The first important image is not deferred, later loading states are announced, and reserved space prevents layout shift.
• No essential instruction, number, warning, label, or conclusion exists only in pixels.
• The gallery contains no video, product card, form, price, rating, testimonial, or call to action.
• Structured data matches visible order, captions, rights, and entity relationships without treating decoration as content.
• Portable Markdown, Hugo, and WordPress mappings preserve the same fields, item order, and meaning.

FAQ

The academy template renders the five reviewed questions stored in this page’s [[faq]] frontmatter. They cover item count, mobile carousels, alternative text and captions, prohibited mixed content, and structured data.

Success means a reader can explain the relationship among the images and each item’s contribution. Without meaningful order, distinct captions, and an accessible mobile path, the set is an asset list rather than a gallery.