The Image component provides a reusable pattern for image in the interface.
Plain image
Just a plain image
Hey, I am a caption for an image
<figure class="c-image" data-component="image">
<div class="c-image__image-wrapper">
<img class="c-image__image" src="https://picsum.photos/id/1026/300/200" alt="This is a image" loading="lazy" />
</div>
<figcaption>
<span class="c-image__caption">Hey, I am a caption for an image</span><br />
</figcaption>
</figure>
@image([
'src'=> "https://picsum.photos/id/1026/300/200",
'alt' => "This is a image",
'caption' => "Hey, I am a caption for an image",
])
@endimage
Rounded corners
An image with border radius for rounded corners
Image with rounded corners (default size: md)
<figure class="c-image c-image--radius-1" data-component="image">
<div class="c-image__image-wrapper">
<img class="c-image__image" src="https://picsum.photos/id/1032/300/200" alt="This is a image" loading="lazy" />
</div>
<figcaption>
<span class="c-image__caption">Image with rounded corners (default size: md)</span><br />
</figcaption>
</figure>
@image([
'src'=> "https://picsum.photos/id/1032/300/200",
'alt' => "This is a image",
'caption' => "Image with rounded corners (default size: md)",
'rounded' => true
])
@endimage
Missing plain image
Image not found but rendered as a placeholder.
<figure class="c-image c-image--is-placeholder c-image--is-placeholder" data-component="image">
<div class="c-image__placeholder" aria-label="This is a image not found">
<!-- icon.blade.php -->
<label class="c-image__placeholder-text">Image not found</label>
</div>
</figure>
@image([
'src'=> false,
'alt' => "This is a image not found",
'placeholderText' => "Image not found"
])
@endimage
Full width image
Image in full width mode.
<figure class="c-image c-image--full-width" data-component="image">
<div class="c-image__image-wrapper">
<img class="c-image__image" src="https://picsum.photos/id/1026/1024/400" alt="This is a image" loading="lazy" />
</div>
</figure>
@image([
'src'=> "https://picsum.photos/id/1026/1024/400",
'alt' => "This is a image",
'fullWidth' => true
])
@endimage
Cover image
Image with cover mode, that covers the parent container.
<figure class="c-image c-image--cover" data-component="image">
<div class="c-image__image-wrapper">
<img class="c-image__image" src="https://picsum.photos/id/1026/1024/400" alt="This is a image" loading="lazy" />
</div>
</figure>
@image([
'src'=> "https://picsum.photos/id/1026/1024/400",
'alt' => "This is a image",
'cover' => true
])
@endimage
Container query switching (default)
The default behaviour for an ImageInterface source with several candidate sizes: one <img> per size, switched by CSS container queries. Inspect the element to see multiple <img> tags, only one of which is visible at a time.
By default, an ImageInterface source with multiple candidate sizes renders one <img> per size, switched by CSS container queries. Inspect the element to see several <img> tags, only one of which is visible.
<figure class="c-image c-image--container-query" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;">
<!-- Image assets -->
<img class="c-image__image c-image--mock-image-6ab0191e273ef-425" src="https://picsum.photos/seed/styleguide-container-query/425/177" alt=
"A photograph used to demonstrate responsive image loading." style="object-position: 50% 50%;" loading="lazy" /> <img class="c-image__image c-image--mock-image-6ab0191e273ef-768" src=
"https://picsum.photos/seed/styleguide-container-query/768/320" alt="A photograph used to demonstrate responsive image loading." style="object-position: 50% 50%;" loading="lazy" /> <img class=
"c-image__image c-image--mock-image-6ab0191e273ef-1024" src="https://picsum.photos/seed/styleguide-container-query/1024/427" alt="A photograph used to demonstrate responsive image loading."
style="object-position: 50% 50%;" loading="lazy" /> <img class="c-image__image c-image--mock-image-6ab0191e273ef-1440" src="https://picsum.photos/seed/styleguide-container-query/1440/600" alt=
"A photograph used to demonstrate responsive image loading." style="object-position: 50% 50%;" loading="lazy" /> <img class="c-image__image c-image--mock-image-6ab0191e273ef-1920" src=
"https://picsum.photos/seed/styleguide-container-query/1920/800" alt="A photograph used to demonstrate responsive image loading." style="object-position: 50% 50%;" loading="lazy" />
</div>
<figcaption>
<span class="c-image__caption">By default, an ImageInterface source with multiple candidate sizes renders one <img> per size, switched by CSS container queries. Inspect the element to see
several <img> tags, only one of which is visible.</span><br />
</figcaption>
</figure><!-- Image styles -->
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::responsive('styleguide-container-query'),
'caption' => "By default, an ImageInterface source with multiple candidate sizes renders one <img> per size, switched by CSS container queries. Inspect the element to see several <img> tags, only one of which is visible.",
])
@endimage
Single image via srcset (opt-in)
Setting preferSrcset renders a single <img> using srcset, sizes and container query data instead of one <img> per breakpoint. Inspect the element to verify only one <img> is rendered.
One responsive <img>, fed by a fake ImageInterface with several candidate sizes. Opted in via preferSrcset, since the default is container-query switching.
<figure class="c-image" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;">
<img class="c-image__image" src="https://picsum.photos/seed/styleguide-responsive/1920/800" alt="A photograph used to demonstrate responsive image loading." sizes="100cqw" style=
"object-position: 50% 50%;" width="1920" height="800" loading="lazy" srcset=
"https://picsum.photos/seed/styleguide-responsive/425/177 425w, https://picsum.photos/seed/styleguide-responsive/768/320 768w, https://picsum.photos/seed/styleguide-responsive/1024/427 1024w, https://picsum.photos/seed/styleguide-responsive/1440/600 1440w, https://picsum.photos/seed/styleguide-responsive/1920/800 1920w" />
</div>
<figcaption>
<span class="c-image__caption">One responsive <img>, fed by a fake ImageInterface with several candidate sizes. Opted in via preferSrcset, since the default is container-query
switching.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::responsive(),
'preferSrcset' => true,
'caption' => "One responsive <img>, fed by a fake ImageInterface with several candidate sizes. Opted in via preferSrcset, since the default is container-query switching.",
])
@endimage
Focus point
A responsive image with an off-center focus point, verifying that object-position is applied together with the srcset/sizes attributes.
The image is focused towards the top right corner.
<figure class="c-image c-image--cover" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio: 16/9;">
<img class="c-image__image" src="https://picsum.photos/seed/styleguide-focus/1920/1920" alt="A photograph used to demonstrate responsive image loading." sizes="100cqw" style=
"object-position: 80% 15%;" width="1920" height="1920" loading="lazy" srcset=
"https://picsum.photos/seed/styleguide-focus/425/425 425w, https://picsum.photos/seed/styleguide-focus/1024/1024 1024w, https://picsum.photos/seed/styleguide-focus/1920/1920 1920w" />
</div>
<figcaption>
<span class="c-image__caption">The image is focused towards the top right corner.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::withFocusPoint(),
'cover' => true,
'preferSrcset' => true,
'caption' => "The image is focused towards the top right corner.",
'wrapperAttributes' => ['style' => 'aspect-ratio: 16/9;'],
])
@endimage
Low quality image placeholder
A responsive image with a low quality placeholder shown as a background while the full image loads.
A low quality placeholder is shown as a background while the image loads.
<figure class="c-image" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;background-image: url(https://picsum.photos/seed/styleguide-lqip/32/32); background-position: 50% 50%;">
<img class="c-image__image" src="https://picsum.photos/seed/styleguide-lqip/1920/800" alt="A photograph used to demonstrate responsive image loading." sizes="100cqw" style=
"object-position: 50% 50%;" width="1920" height="800" loading="lazy" srcset=
"https://picsum.photos/seed/styleguide-lqip/425/177 425w, https://picsum.photos/seed/styleguide-lqip/768/320 768w, https://picsum.photos/seed/styleguide-lqip/1024/427 1024w, https://picsum.photos/seed/styleguide-lqip/1440/600 1440w, https://picsum.photos/seed/styleguide-lqip/1920/800 1920w" />
</div>
<figcaption>
<span class="c-image__caption">A low quality placeholder is shown as a background while the image loads.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::responsiveWithLqip(),
'preferSrcset' => true,
'caption' => "A low quality placeholder is shown as a background while the image loads.",
])
@endimage
Transparent background with LQIP (srcset)
Images with a transparent background don't work well with low quality placeholders: the placeholder is typically encoded without an alpha channel, so it renders with a solid backing colour instead of transparency. Rendered as a single <img> via srcset.
A single <img> via srcset. The low quality placeholder loses its transparency, showing a solid colour behind the final transparent image.
<figure class="c-image" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;background-image: url(https://placehold.co/32x32/2c3e50/2c3e50/jpg); background-position: 50% 50%;">
<img class="c-image__image" src="https://placehold.co/1920x800/transparent/2c3e50/png?text=styleguide-transparent-srcset" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." sizes="100cqw" style="object-position: 50% 50%;" width="1920" height="800" loading="lazy" srcset=
"https://placehold.co/425x177/transparent/2c3e50/png?text=styleguide-transparent-srcset 425w, https://placehold.co/768x320/transparent/2c3e50/png?text=styleguide-transparent-srcset 768w, https://placehold.co/1024x427/transparent/2c3e50/png?text=styleguide-transparent-srcset 1024w, https://placehold.co/1440x600/transparent/2c3e50/png?text=styleguide-transparent-srcset 1440w, https://placehold.co/1920x800/transparent/2c3e50/png?text=styleguide-transparent-srcset 1920w" />
</div>
<figcaption>
<span class="c-image__caption">A single <img> via srcset. The low quality placeholder loses its transparency, showing a solid colour behind the final transparent image.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::transparentWithLqip('styleguide-transparent-srcset'),
'preferSrcset' => true,
'caption' => "A single <img> via srcset. The low quality placeholder loses its transparency, showing a solid colour behind the final transparent image.",
])
@endimage
Transparent background with LQIP (container query)
Images with a transparent background don't work well with low quality placeholders: the placeholder is typically encoded without an alpha channel, so it renders with a solid backing colour instead of transparency. Rendered as one <img> per candidate size, switched by CSS container queries.
One <img> per candidate size, switched by CSS container queries. The low quality placeholder loses its transparency, showing a solid colour behind the final transparent image.
<figure class="c-image c-image--container-query" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;background-image: url(https://placehold.co/32x32/2c3e50/2c3e50/jpg); background-position: 50% 50%;">
<!-- Image assets -->
<img class="c-image__image c-image--mock-image-6ab0191e27c24-425" src="https://placehold.co/425x177/transparent/2c3e50/png?text=styleguide-transparent-cq" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." style="object-position: 50% 50%;" loading="lazy" /> <img class=
"c-image__image c-image--mock-image-6ab0191e27c24-768" src="https://placehold.co/768x320/transparent/2c3e50/png?text=styleguide-transparent-cq" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." style="object-position: 50% 50%;" loading="lazy" /> <img class=
"c-image__image c-image--mock-image-6ab0191e27c24-1024" src="https://placehold.co/1024x427/transparent/2c3e50/png?text=styleguide-transparent-cq" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." style="object-position: 50% 50%;" loading="lazy" /> <img class=
"c-image__image c-image--mock-image-6ab0191e27c24-1440" src="https://placehold.co/1440x600/transparent/2c3e50/png?text=styleguide-transparent-cq" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." style="object-position: 50% 50%;" loading="lazy" /> <img class=
"c-image__image c-image--mock-image-6ab0191e27c24-1920" src="https://placehold.co/1920x800/transparent/2c3e50/png?text=styleguide-transparent-cq" alt=
"A logo with a transparent background, used to demonstrate low quality image placeholders." style="object-position: 50% 50%;" loading="lazy" />
</div>
<figcaption>
<span class="c-image__caption">One <img> per candidate size, switched by CSS container queries. The low quality placeholder loses its transparency, showing a solid colour behind the final
transparent image.</span><br />
</figcaption>
</figure><!-- Image styles -->
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::transparentWithLqip('styleguide-transparent-cq'),
'caption' => "One <img> per candidate size, switched by CSS container queries. The low quality placeholder loses its transparency, showing a solid colour behind the final transparent image.",
])
@endimage
Single candidate size
An image contract with only one candidate size. No srcset or sizes attribute should be rendered.
Only one candidate size is available, so no srcset or sizes attribute is rendered.
<figure class="c-image" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:1024/683;">
<img class="c-image__image" src="https://picsum.photos/seed/styleguide-single/1024/683" alt="A photograph used to demonstrate responsive image loading." style="object-position: 50% 50%;" width=
"1024" height="683" loading="lazy" />
</div>
<figcaption>
<span class="c-image__caption">Only one candidate size is available, so no srcset or sizes attribute is rendered.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::withoutSrcset(),
'preferSrcset' => true,
'caption' => "Only one candidate size is available, so no srcset or sizes attribute is rendered.",
])
@endimage
Eager loading with priority
Overriding imgAttributeList to opt out of the lazy-loading default, useful for above-the-fold images such as a Hero background.
Overriding imgAttributeList lets a caller opt out of the lazy-loading default, e.g. for above-the-fold images. preferSrcset is also set, since a prioritized image should render once, not switch between several candidates.
<figure class="c-image c-image--full-width" data-component="image">
<div class="c-image__image-wrapper" style="aspect-ratio:425/177;">
<img class="c-image__image" src="https://picsum.photos/seed/styleguide-eager/1920/800" alt="A photograph used to demonstrate responsive image loading." loading="eager" fetchpriority="high" sizes=
"100vw" style="object-position: 50% 50%;" width="1920" height="800" srcset=
"https://picsum.photos/seed/styleguide-eager/425/177 425w, https://picsum.photos/seed/styleguide-eager/768/320 768w, https://picsum.photos/seed/styleguide-eager/1024/427 1024w, https://picsum.photos/seed/styleguide-eager/1440/600 1440w, https://picsum.photos/seed/styleguide-eager/1920/800 1920w" />
</div>
<figcaption>
<span class="c-image__caption">Overriding imgAttributeList lets a caller opt out of the lazy-loading default, e.g. for above-the-fold images. preferSrcset is also set, since a prioritized image
should render once, not switch between several candidates.</span><br />
</figcaption>
</figure>
@image([
'src'=> \MunicipioStyleGuide\Helper\MockImage::responsive('styleguide-eager'),
'preferSrcset' => true,
'imgAttributeList' => [
'loading' => 'eager',
'fetchpriority' => 'high',
'sizes' => '100vw',
],
'fullWidth' => true,
'caption' => "Overriding imgAttributeList lets a caller opt out of the lazy-loading default, e.g. for above-the-fold images. preferSrcset is also set, since a prioritized image should render once, not switch between several candidates.",
])
@endimage
