Skip to content

No results for

↑ ↓ navigate ↵ open Esc close 
php artisan aura:add image

Copies the component source into resources/views/components/aura/. Run php artisan aura:init first if you haven't already. See the CLI guide for all options.

composer require bluestarsystem/aura-ui
php artisan aura:install

Full installation instructions in the Installation guide.

Overview

<x-aura::image> handles the parts of an <img> that are easy to get wrong: the aspect ratio, lazy loading, a fallback when the file is missing, and the alt text.

Basic Usage

<x-aura::image src="/screenshots/orders.png" alt="The orders screen, filtered to unpaid" ratio="16/9" />

Alt text is a decision, not a default

alt has no default. An image with no alt is announced by its filename — worse than nothing. An image with alt="" is skipped silently, which is right only when the image is decoration. Those two cases look identical from the outside, so the component will not guess:

<!-- Content: describe it -->
<x-aura::image src="/chart.png" alt="Revenue rose 12% between March and June" />

<!-- Decoration: say so -->
<x-aura::image src="/pattern.svg" decorative />

decorative sets alt="" and aria-hidden, which is the pair that actually removes it from the reading order.

Props

Prop Type Default Description
src string|null null Sanitised.
alt string|null null The description. Required unless decorative.
decorative bool false Marks the image as decoration.
ratio string|null null e.g. 16/9. Reserves the space so the page does not jump as it loads.
fit string 'cover' cover, contain, fill, none.
rounded string 'md' none, sm, md, lg, full.
caption string|null null Rendered as a real <figcaption>.
lazy bool true loading="lazy" and decoding="async".
fallback string|null null Swapped in when the source fails to load.

Accessibility

  • A caption is a <figcaption>, so it is associated with the image rather than being a paragraph that happens to sit underneath.
  • A caption does not replace alt. The caption is for everyone; the alt describes the picture to someone who cannot see it, and repeating the caption there adds nothing.
  • With ratio, the space is reserved before the file arrives, so the page does not jump under someone who is already reading — that shift is a usability failure as much as a visual one.