Quick Start and Reference

1. Quick start

<head>
  <script src="tmtg.js?v=1.3.2"></script>
</head>
<body>
  <div class="tmtgContainer" id="tmtgContainer">
    <div class="tmtgGallery" id="tmtgGallery">
      <img src="data:," data-src="photo1.jpg" alt="Short description"
           data-description="Optional caption">
      <img src="data:," data-src="photo2.jpg" alt="Short description">
    </div>
  </div>
</body>

That's all. The gallery starts by itself when the page loads.

• Keep tmtg.css in the same folder as tmtg.js. The script loads it; your page doesn't link to it.
• "?v=1.3.2" is the version number. Change it whenever you update the gallery, so visitors' browsers fetch the new files. (docs: 9, "Updating the gallery")
• For a live site, use tmtg-1.3.2.min.js instead, with tmtg-1.3.2.min.css in the same folder. No "?v=" is needed. (docs: 9, "Minified files")
• One gallery per page, with the IDs shown above.

Back to contents

2. Images and captions

<img src="data:," data-src="photo1.jpg"
     data-thumb="thumbs/photo1.jpg" alt="Short description"
     data-description="A <i>caption</i>.">

src / data-src

The image's address. Use data-src for more than a handful of images: only the current image and two on each side are loaded at a time. Keep src="data:," on data-src images, exactly as shown; it downloads nothing, and the page stays valid HTML. Without JavaScript, data-src images don't show. (docs: 9, "Large galleries")

alt

Required. A short description (100 characters or fewer) for screen readers.

data-description

Optional caption, any length. Without one, the slide number is centered in the caption row; if no image has a caption, the captions button is left out. (docs: 9, "Slide numbers")

data-thumb

Optional smaller file for the thumbnail strip, about 320 pixels wide and roughly 16:9. Saves a lot of memory on phones. A missing file falls back to the full image. (docs: 9, "Thumbnail files")

Caption formatting: only <i>, <em>, <b>, and <strong>, without attributes. Other tags are removed and their text kept; <script>, <style>, and comments are removed entirely. To show a tag as text, write <b>. (docs: 9, "Caption formatting")

Long captions scroll inside their box rather than being cut off. (docs: 9, "Long captions")

Back to contents

3. Options

Options go in a JSON block inside #tmtgContainer. Both the type and the class are required. List only the options you want to change.

<div class="tmtgContainer" id="tmtgContainer">
  <script type="application/json" class="tmtgOptions">
    { "start": 3, "thumbs": false }
  </script>
  <div class="tmtgGallery" id="tmtgGallery"> ... </div>
</div>

(docs: 3, the full option reference, including advanced features)

Write it as strict JSON:

• numbers and true/false without quotes: "start": 3, "thumbs": false
• text values in double quotes: "height": "85vh"
• no trailing commas, comments, or single quotes.

A mistake never breaks the gallery: the faulty option falls back to its default, and the browser's developer console (F12) shows a warning starting with "TMTG:". (docs: 5)

Examples:

{ "autoAdvance": 8000, "thumbs": false }
{ "height": "min(85vh, 120vw)" }
{ "decorative": true, "autoAdvance": 8000, "objectFit": "cover" }
{ "decorative": true, "autoAdvance": false }      (a still banner)

(docs: 4, more examples)

Back to contents

4. User interaction

Toolbar (top center)

Auto-advance, captions, thumbnails, and fullscreen buttons, each an on/off toggle.

Arrows

Previous and next image, at the sides.

Thumbnail strip

Five thumbnails around the current image. In galleries of more than five, « and » move five images; on tablets, swiping the strip does too.

Swipe

On touch screens, swipe the image to move one. Pinching zooms in; while zoomed in, dragging moves the view. (docs: 9, "Swipes and pinch-to-zoom")

Keyboard

Left/Right arrows: previous/next while the gallery is on screen, with focus in it or nowhere in particular (not on other links or controls, in form fields, or with modifier keys held). On a page that scrolls sideways, only after a click or Tab into the gallery. With focus in the gallery: Home/End go to the first/last image, Page Up/Page Down move five. The thumbnails are a single Tab stop. (docs: 9, "Keyboard")

Auto-advance stops for good as soon as a visitor takes control: a click, tap, swipe, or key, or keyboard focus entering the gallery. The timer button restarts it. (docs: 3, "About auto-advance and visitors")

Screen readers hear each new image announced (number, alt text, caption), except while auto-advance runs. (docs: 9, "Screen reader announcements")

Visitors whose device asks for reduced motion get no auto-advance at launch and a fade instead of a slide. (docs: 9, "Reduced motion")

Back to contents

5. Controlling the gallery from a script

Call these from an external script file. (An inline <script> is blocked on sites with a strict Content-Security-Policy.) (docs: 8)

tmtgRun(n)

Show slide n (also starts a manual gallery).

tmtgRun(n, 0 or 1)

The same, hiding (0) or showing (1) the strip.

tmtgSetThumbs(true/false)

Show or hide the thumbnail strip.

tmtgSetCaptions(true/false)

Show or hide captions.

tmtgAutoAdvOn()

Start auto-advance.

tmtgAutoAdvOff()

Stop auto-advance.

Manual launch, with "manual": true in the options:

my-page.js:
  document.addEventListener("DOMContentLoaded", function() {
    /* ...add your images to #tmtgGallery here... */
    tmtgRun(1);
  });

A manual gallery doesn't auto-advance by itself; call tmtgAutoAdvOn() after tmtgRun(), checking for reduced motion first. (docs: 6)

Older pages with an inline <script>tmtgRun(...)</script> still work; move the starting slide into "start" and remove the line. (docs: 7)

Back to contents

6. Languages

The controls' labels and tooltips follow the page's language:

<html lang="fr">

Supported:

en (the fallback), es, pt (Brazilian), pt-pt (European, also Portuguese-speaking Africa), fr, de, it, zh-hans (Simplified; also "zh", "zh-CN", "zh-SG"), zh-hant (Traditional; "zh-TW", "zh-HK", "zh-MO"), ja, ko, hi.

Regional codes use their language's labels ("es-MX" uses "es"). Any other language gets English. Your own alt text and captions are shown as written.

To add a language, copy the 'en' block in tmtgLabels near the top of tmtg.js, translate it, and name it with the language code in lower case. Right-to-left languages aren't supported yet. (docs: 9, "Language")

Back to contents

7. Notes

Browsers

Chrome and Edge 111 or later, Firefox 113 or later, Safari 16.2 or later, and iPhones and iPads on iOS or iPadOS 16.2 or later. In older browsers the layout comes apart. (docs: 9, "Supported browsers")

Sizing

Set "height", or put the gallery in an element that has a height of its own, and the gallery is exactly that tall; the image takes what the caption and strip leave. Otherwise the image area takes a 3:2 shape, up to 60% of the window's height but at least 200 pixels tall. You can also set the height or shape in your stylesheet:

#tmtgContainer { --tmtg-height: 85vh; }
#tmtgContainer { --tmtg-aspect: 16 / 9; }

(docs: 9, "Sizing")

Fullscreen

Fullscreen opens without the thumbnail strip; leaving it restores the earlier setting. On iPhones, which don't allow web pages to go fullscreen, the gallery fills the browser window instead, and Safari's bars stay visible. For phones with a notch, add viewport-fit=cover to your viewport tag. (docs: 9, "Fullscreen on iPhones")

Phones

In a gallery 576 pixels wide or less (on a phone, or in a narrow column), the thumbnail strip starts hidden; the thumbnails button shows it. On a phone held sideways, captions also start hidden, the slide number moves up beside the toolbar, and the gallery can be as tall as the screen, but no taller. (docs: 9, "Phones held sideways")

Decorative galleries

Use "decorative" only when the images carry no meaning, since screen readers skip them entirely. An auto-advancing decorative gallery has no stop button, so your page must provide one (outside #tmtgContainer) that calls tmtgAutoAdvOff(), unless you set "autoAdvance": false. (docs: 9, "Decorative galleries")

Appearance

Set these on #tmtgContainer in your own stylesheet:

--tmtg-background

backdrop color (#000)

--tmtg-foreground

text and controls color (#fff)

--tmtg-accent

hover color behind white icons; keep it dark (rgb(100, 26, 0))

--tmtg-corner-radius

corners (default 1.05em; 0 for square)

--tmtg-aspect

image area shape, if no height (3 / 2)

--tmtg-font

caption font (system-ui, sans-serif)

--tmtg-height

height, like the "height" option

--tmtg-decorative-padding

decorative frame thickness (.3em)

For example:

#tmtgContainer { --tmtg-corner-radius: 6px; --tmtg-aspect: 4 / 3; }

Fullscreen always stays black and white. The background and foreground need a contrast of at least 7:1; the browser's console warns if they fall short. Other --tmtg- variables aren't meant to be changed. (docs: 10)

Security

The gallery works under a strict Content-Security-Policy, including Trusted Types, with nothing to configure. (docs: 8)

Troubleshooting

If the gallery doesn't behave as expected, open the browser's developer console (F12) and look for warnings starting with "TMTG:".

Back to contents

8. License

MIT License: free to use, change, and share, including commercially. Keep the copyright line and license with every copy; the file headers and the LICENSE.txt file carry them. No warranty. (docs: 11)

Back to contents

9. Feedback

Latest version, demo, and documentation: https://timcode.dev/tmtg

Bug reports, feature requests, and questions: tim@timcode.dev. For a bug, include the browser and device, the TMTG version, and any "TMTG:" console warnings. Translations welcome. Pull requests aren't accepted. (docs: 12)

Back to contents