AbsoluteJS

HTML/HTMX Image Optimization

AbsoluteJS optimizes images in HTML and HTMX pages at build time using the data-optimized attribute. No JavaScript component needed.

#How It Works

At build time, AbsoluteJS scans your HTML files for <img> tags with the data-optimized attribute and transforms them:

Rewrites srcreplaces the original src with a URL pointing to the /_absolute/image optimization endpoint
Adds srcsetgenerates a responsive srcset with all configured breakpoints
Sets loading and decodingadds loading="lazy" and decoding="async" for performance
Removes data-optimizedthe attribute is stripped from the output HTML

#Usage

Add the data-optimized attribute to any <img> tag to opt in to image optimization:

HTML
<!-- AbsoluteJS transforms data-optimized images at build time -->
<img
  data-optimized
  src="/images/hero.jpg"
  alt="Hero banner"
  width="1200"
  height="600"
/>

<!-- With explicit quality -->
<img
  data-optimized
  data-quality="90"
  src="/images/photo.jpg"
  alt="High quality photo"
  width="800"
  height="600"
/>

<!--
  At build time, AbsoluteJS rewrites these to use the
  /_absolute/image endpoint with proper srcset and sizes
  attributes for responsive delivery.
-->

#Attributes

The following attributes are used by the build transform:

widthused for srcset generation. Determines the maximum width for the responsive breakpoints.
heightprevents cumulative layout shift (CLS) by reserving space before the image loads
sizesresponsive breakpoints hint for the browser. Controls which srcset entry the browser downloads.
altalternative text for accessibility. Always include a descriptive alt attribute.

The data-optimized attribute itself is removed from the output HTML. It is only used as a signal to the build transform.

#Fill Mode

For fill-style images in HTML, use CSS on the parent container. Set the parent to position: relative with explicit dimensions, then style the image with position: absolute, width: 100%, height: 100%, and object-fit: cover.

#HTMX Support

The same data-optimized attribute works in HTMX pages. The build process scans both the HTML and HTMX directories, so any <img data-optimized> tag in either directory is transformed identically.

No additional configuration is needed. HTMX partial responses that include optimized images will have their src and srcset attributes rewritten at build time just like full HTML pages.