Atlas

Image

One img tag, rendered by whichever driver fits the source: a URL, a WordPress attachment id, or nothing at all.

<x-atlas::image>

A row of cranes reflected in still harbour water 
<x-atlas::image
    src="https://picsum.photos/seed/atlas-image/480/320"
    alt="A row of cranes reflected in still harbour water"
/>
Preview follows the site's light/dark mode. Open standalone →

Three sources, three drivers

The component itself renders nothing. It hands the source to an image manager, which picks a driver and returns the finished <img>:

  • A string src uses the standard driver: a plain <img> with decoding="async" and loading="lazy" already applied.
  • An attachment-id uses the WordPress driver, which calls wp_get_attachment_image() so the CMS emits its own srcset and sizes for the requested size.
  • An empty or missing source is caught before either of them by a decorator that renders a bundled placeholder SVG, inlined as a data URI.

Because attachment-id decides the driver, passing both means the URL is ignored. The choice is made per image, so there is nothing to configure. A host with a different media library replaces a driver instead: bind its own Atlas\Contracts\ImageDriver implementation to the class it replaces, in a service provider.

app/Providers/AppServiceProvider.php

use Atlas\Drivers\StandardImageDriver;
use App\Images\CdnImageDriver;

public function register(): void
{
    $this->app->bind(StandardImageDriver::class, CdnImageDriver::class);
}
This documentation site is plain Laravel with no WordPress behind it, so the attachment-id path cannot be demonstrated here — wp_get_attachment_image() does not exist and the call would fail. Every example below uses a URL or no source at all.

Aspect ratios

aspect adds an Atlas utility class and the image is cropped with object-fit: cover. Only the ratios the stylesheet ships take effect: 1/1, 2/3, 3/4, 4/5, 3/2, 4/3 and 16/9. Anything else silently leaves the image at its natural ratio. 

<x-atlas::image
    src="https://picsum.photos/seed/atlas-image-a/480/320"
    aspect="1/1"
    alt=""
/>

<x-atlas::image
    src="https://picsum.photos/seed/atlas-image-b/480/320"
    aspect="16/9"
    alt=""
/>

<x-atlas::image
    src="https://picsum.photos/seed/atlas-image-c/480/320"
    aspect="3/4"
    alt=""
/>
Preview follows the site's light/dark mode. Open standalone →

Missing source

An empty source is a normal state, not an error — an editor has not uploaded the picture yet. The placeholder keeps the layout intact and carries a border so it is recognisable as a gap rather than mistaken for artwork. To use your own SVG, set components.image.placeholder in config/atlas.php to its absolute path. 

<x-atlas::image aspect="4/3" alt="" width="480" height="360" />
Preview follows the site's light/dark mode. Open standalone →

Extra attributes

Attributes you pass are merged onto the <img> last, so they win over the defaults. That is how you opt one image out of lazy loading — the hero at the top of a page, which should start downloading immediately.

Sunrise over the storm surge barrier 
<x-atlas::image
    src="https://picsum.photos/seed/atlas-image-hero/480/320"
    alt="Sunrise over the storm surge barrier"
    width="480"
    height="320"
    loading="eager"
    fetchpriority="high"
/>
Preview follows the site's light/dark mode. Open standalone →

Card

A linked content card: cropped image, badges, heading, meta list and subtitle, with the whole card acting as one link.

Video

A self-hosted video player and an iframe wrapper for embedded ones, both cropped to a fixed aspect ratio.

Swiper

A carousel built on Swiper 14: a track of slides with keyboard support, arrows and pagination, configured entirely from Blade props.

Reference

<x-atlas::image>

  • Name
    src
    Type
    string
    Default
    default: null
    Description
    Image URL, rendered by the standard driver. Ignored when attachment-id is set.
  • Name
    attachment-id
    Type
    int
    Default
    default: null
    Description
    WordPress attachment id. Its presence switches the component to the WordPress driver, which calls wp_get_attachment_image().
  • Name
    size
    Type
    string
    Default
    default: large
    Description
    WordPress image size name, passed to the attachment lookup. The standard driver accepts it and does nothing with it.
  • Name
    alt
    Type
    string
    Default
    default: ''
    Description
    Alternative text. Left empty the image is treated as decorative.
  • Name
    aspect
    Type
    1/1 | 2/3 | 3/4 | 4/5 | 3/2 | 4/3 | 16/9
    Default
    default: null
    Description
    Crops the image to a ratio through an Atlas utility class. Without it the image keeps its natural ratio.