Image

Default density Compact density Restart from the initial state Show the copyable source

Usage

The browser still picks and loads the file: Image passes src, srcset, sizes and <source> children to a native <picture>, so lazy loading and responsive candidates work as usual. With a lazy srcset of width descriptors and no sizes, it sets sizes="auto, 100vw" so the browser fetches the laid-out width. Set alt="" for a decorative image.

An explicit sizes is passed through unchanged. An eager image without sizes keeps the browser default (100vw).

Ratio and fit

ratio (width ÷ height) reserves a fixed frame before the image loads, so nothing shifts. fit decides how the picture fills it, as object-fit does. Round the frame with border-radius on the host.

Setting an invalid ratio throws RangeError and keeps the previous value. Without ratio, the image keeps its own proportions. Give width and height (or set them on the selected <source>) so the space is reserved before the image loads. When the host has an explicit block size, fit applies within it.

Default density Compact density Restart from the initial state Show the copyable source

Placeholder and fallback

While loading, Image shows a pulsing skeleton; placeholder="spinner" adds a spinner and none shows nothing. If the image fails or has no source, it shows a muted surface with a broken-image icon, or your fallback slot content, which stays exposed to assistive technology.

Once loaded, the image fades in. A cached image appears without a loading phase or fade. The image stays hidden until it loads, so a broken-image glyph never appears.

The placeholder and the default fallback are hidden from assistive technology and never announce anything, so a gallery doesn’t create dozens of live regions. The frame reports aria-busy while loading.

Image paints no surface of its own. The placeholder and fallback surfaces are the composed Skeleton, so theme tokens such as --tp-muted apply.

Default density Compact density Restart from the initial state Show the copyable source

No cover yet

For a gentler load, put a tiny blurred version of the photo in the placeholder slot; it shows until the full image is ready.

Default density Compact density Restart from the initial state Show the copyable source

Hover zoom

zoom="in" scales the picture up while the pointer hovers, and zoom="out" settles it from enlarged to natural size. The frame never changes size. Set zoomed to drive the effect from a surrounding card instead.

Hover zoom applies only to devices that can hover, and it never changes layout or the clipping frame. Tune it with --tp-image-zoom-duration and --tp-image-zoom-easing.

Default density Compact density Restart from the initial state Show the copyable source

Here the whole card drives the zoom, so the photo responds wherever the pointer enters the card.

Default density Compact density Restart from the initial state Show the copyable source

Quiet floor

12 bookable desks with natural light.

Reveal and groups

reveal animates an image into place the first time it scrolls into view, from tokens such as fade up or zoom-in. Wrap a set in tp-image-group to wait until every image has loaded, then reveal them in order, stagger milliseconds apart. A reveal that would start during a same-document view transition waits for it to finish.

The group starts fetching every member once it is within 25% of the viewport, so lazy members don’t hold the set back. It reveals nothing until every member has settled (loaded and decoded, or failed and showing its fallback). Members that have no reveal of their own use the group’s reveal. Inside a group, members never trigger their own reveal; the group owns their timing. Lay the group out like any block, for example as a grid.

Members’ events bubble through the group with the same names, so check event.target === group to handle only the group’s.

Default density Compact density Restart from the initial state Show the copyable source

Images outside a group reveal on their own as each loads. Tune them with --tp-image-reveal-duration, --tp-image-reveal-easing and --tp-image-reveal-delay, set on a container to apply to every image inside; a growing delay staggers a grid. Add reveal-repeat to replay the reveal each time an image scrolls back into view. Scroll the box to see it.

Default density Compact density Restart from the initial state Show the copyable source

Keep scrolling

The reveal never starts before the image is ready. An image that enters while still loading stays in its start state until it has loaded and decoded, then reveals if it is still in view. An image that fails to load reveals its fallback, and one with no source reveals at once. Add reveal-repeat to play it again on every entry: once the image is fully out of view, it returns to its start state instantly, out of sight, and reveals again when it is back at least 10% inside the viewport. That margin stops it flickering at an edge.

To sequence images with surrounding text, wrap them in a Scroll trigger. It waits for the group’s images to load, then reveals the heading, the images and the caption in order.

Default density Compact density Restart from the initial state Show the copyable source

Spaces that work the way you do

Open desks, quiet rooms and a terrace, all bookable from the app.

An image belongs to its nearest group or trigger, and a group inside a trigger or another group is one member of it, playing its own stagger after the delay it receives. Images added later join the set and reveal as soon as they settle. For other motion, hold the group, wait for what you need, then clear reveal-hold. Inside a scrubbing trigger the scroll position drives the image’s reveal (delay, duration and easing included) instead of time.

Under reduced motion, from motion-policy="reduce" or the system preference, images appear already revealed and zoom is instant.

Parallax

parallax moves the picture inside its frame as the page, or the nearest scrolling container, scrolls past. The image is enlarged by parallax-depth so the frame edges never show; add zoom-in or zoom-out to scale it as it travels.

Clipping wrappers that don’t scroll, such as a card with overflow: hidden, are skipped. Directions are physical and don’t flip for right-to-left text, and any direction works with either axis; left and right suit a horizontal strip. Parallax only moves while the container actually scrolls past the image. An image is placed shortly before it scrolls into view, so it never jumps when it appears.

Default density Compact density Restart from the initial state Show the copyable source

Scroll zoom scales the image instead of moving it: zoom-in grows it as it passes through the box, and zoom-out settles it from enlarged to natural size. Combine zoom with a direction, such as up zoom-in, to zoom and drift at once.

Default density Compact density Restart from the initial state Show the copyable source

Scroll zoom scales the picture inside the moving layer, so it also combines with hover zoom, and it only ever enlarges, so the frame edges never show.

A container that scrolls only sideways measures progress along its inline axis, so parallax="left" drifts each image as the strip moves.

Default density Compact density Restart from the initial state Show the copyable source

parallax-smoothing, from 0 to 1, makes the picture trail the scroll and ease into place after it stops. In this scroller the first image is locked to the scroll and each following one is smoother.

Default density Compact density Restart from the initial state Show the copyable source

The value is the share of the remaining distance still left after one 60 fps frame: 0.5 trails slightly, 0.9 glides slowly. It is clamped to 0.98, and it behaves the same at any frame rate.

Art direction

<source> children give the native picture other candidates, such as a tighter crop for narrow screens through media. For a hero that is the largest content on first paint, set loading="eager" and fetchpriority="high".

Use media to switch crops between layouts and type for AVIF or WebP with a fallback. The authored <source> elements never request anything themselves. Adding, removing or editing a source reloads the image.

When the browser switches candidates after loading, for example when you resize across a media breakpoint, currentSrc updates and the status stays loaded.

Default density Compact density Restart from the initial state Show the copyable source

Performance

Image is built for pages with hundreds of images. Placeholders that are off screen pause their animation, and no will-change is applied, so idle images create no compositing layers.

API Reference

Every element also accepts motion-policy.

<tp-image-group>

Related

Components, widgets and patterns that use this one.